#!/usr/bin/env python2
# Copyright 2017 The Chromium OS Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

"""Validates a given master configuration

This enforces various rules defined by the master configuration. Some of these
are fairly simple (the valid properties and subnodes for each node, the
allowable values for properties) and some are more complex (where phandles
are allowed to point).

The schema is defined by Python objects containing variable SchemaElement
subclasses. Each subclass defines how the device tree property is validated.
For strings this is via a regex. Phandles properties are validated by the
target they are expected to point to.

Schema elements can be optional or required. Optional elements will not cause
a failure if the node does not include them.

The presence or absense of a particular schema element can also be controlled
by a 'conditional_props' option. This lists elements that must (or must not)
be present in the node for this element to be present. This provides some
flexibility where the schema for a node has two options, for example, where
the presence of one element conflicts with the presence of others.

Usage:
  The validator can be run like this (set PYTHONPATH to your chromium dir):

  PYTHONPATH=~/cosarm ./validate_config \
      ~/cosarm/chroot/build/coral/usr/share/chromeos-config/config.dtb \
      ~/cosarm/chroot/build/reef-uni/usr/share/chromeos-config/config.dtb \
      README.md

  The output format for each input file is the name of the file followed by a
  list of validation problems. If there are no problems, the filename is not
  shown.

  Unit tests can be run like this:

  PYTHONPATH=~/cosarm python validate_config_unittest.py
"""

from __future__ import print_function

import argparse
import copy
import itertools
import os
import re
import sys

from chromite.lib import cros_build_lib

from . import fdt, fdt_util
from .validate_schema import NodeAny, NodeDesc, NodeModel, NodeSubmodel
from .validate_schema import PropCustom, PropDesc, PropString, PropStringList
from .validate_schema import PropPhandleTarget, PropPhandle, CheckPhandleTarget
from .validate_schema import PropAny, PropFile


def ParseArgv(argv):
  """Parse the available arguments.

  Invalid arguments or -h cause this function to print a message and exit.

  Args:
    argv: List of string arguments (excluding program name / argv[0])

  Returns:
    argparse.Namespace object containing the attributes.
  """
  parser = argparse.ArgumentParser(description=__doc__)
  parser.add_argument('-d', '--debug', action='store_true',
                      help='Run in debug mode (full exception traceback)')
  parser.add_argument('-p', '--partial', action='store_true',
                      help='Validate a list partial files (.dtsi) individually')
  parser.add_argument('-r', '--raise-on-error', action='store_true',
                      help='Causes the validator to raise on the first ' +
                      'error it finds. This is useful for debugging.')
  parser.add_argument('config', type=str, nargs='+',
                      help='Paths to the config files (.dtb) to validated')
  return parser.parse_args(argv)


class CrosConfigValidator(object):
  """Validator for the master configuration"""
  def __init__(self, schema, raise_on_error):
    """Master configuration validator.

    Properties:
      _errors: List of validation errors detected (each a string)
      _fdt: fdt.Fdt object containing device tree to validate
      _raise_on_error: True if the validator should raise on the first error
          (useful for debugging)
      model_list: List of model names found in the config
      submodel_list: Dict of submodel names found in the config:
          key: Model name
          value: List of submodel names
    """
    self._errors = []
    self._fdt = None
    self._raise_on_error = raise_on_error
    self._schema = schema

    # This iniital value matches the standard schema object. This is
    # overwritten by the real model list by Start().
    self.model_list = ['MODEL']
    self.submodel_list = {}

  def Fail(self, location, msg):
    """Record a validation failure

    Args:
      location: fdt.Node object where the error occurred
      msg: Message to record for this failure
    """
    self._errors.append('%s: %s' % (location, msg))
    if self._raise_on_error:
      raise ValueError(self._errors[-1])

  def _IsBuiltInProperty(self, node, prop_name):
    """Checks if a property is a built-in device-tree construct

    This checks for 'reg', '#address-cells' and '#size-cells' properties which
    are valid when correctly used in a device-tree context.

    Args:
      node: fdt.Node where the property appears
      prop_name: Name of the property

    Returns:
      True if this property is a built-in property and does not have to be
      covered by the schema
    """
    if prop_name == 'reg' and '@' in node.name:
      return True
    if prop_name in ['#address-cells', '#size-cells']:
      for subnode in node.subnodes.values():
        if '@' in subnode.name:
          return True
    return False

  def ElementPresent(self, schema, parent_node):
    """Check whether a schema element should be present

    This handles the conditional_props feature. The list of names of sibling
    nodes/properties that are actually present is checked to see if any of them
    conflict with the conditional properties for this node. If there is a
    conflict, then this element is considered to be absent.

    Args:
      schema: Schema element to check
      parent_node: Parent fdt.Node containing this schema element (or None if
          this is not known)

    Returns:
      True if this element is present, False if absent
    """
    if schema.conditional_props and parent_node:
      for rel_name, value in schema.conditional_props.iteritems():
        name = rel_name
        schema_target = schema.parent
        node_target = parent_node
        while name.startswith('../'):
          schema_target = schema_target.parent
          node_target = node_target.parent
          name = name[3:]
        parent_props = [e.name for e in schema_target.elements]
        sibling_names = node_target.props.keys()
        sibling_names += [n.name for n in node_target.subnodes.values()]
        if name in parent_props and value != (name in sibling_names):
          return False
    return True

  def GetElement(self, schema, name, node, expected=None):
    """Get an element from the schema by name

    Args:
      schema: Schema element to check
      name: Name of element to find (string)
      node: Node containing the property (or for nodes, the parent node
          containing the subnode) we are looking up. None if none available
      expected: The SchemaElement object that is expected. This can be NodeDesc
          if a node is expected, PropDesc if a property is expected, or None
          if either is fine.

    Returns:
      Tuple:
        Schema for the node, or None if none found
        True if the node should have schema, False if it can be ignored
            (because it is internal to the device-tree format)
    """
    for element in schema.elements:
      if not self.ElementPresent(element, node):
        continue
      if element.name == name:
        return element, True
      elif (self.model_list and isinstance(element, NodeModel) and
            name in self.model_list):
        return element, True
      elif self.submodel_list and isinstance(element, NodeSubmodel) and node:
        m = re.match('/chromeos/models/([a-z0-9]+)/submodels', node.path)
        if m and name in self.submodel_list[m.group(1)]:
          return element, True
      elif ((expected is None or expected == NodeDesc) and
            isinstance(element, NodeAny)):
        return element, True
      elif ((expected is None or expected == PropDesc) and
            isinstance(element, PropAny)):
        return element, True
    if expected == PropDesc:
      if name == 'linux,phandle' or self._IsBuiltInProperty(node, name):
        return None, False
    return None, True

  def GetElementByPath(self, path):
    """Find a schema element given its full path

    Args:
      path: Full path to look up (e.g. '/chromeos/models/MODEL/thermal/dptf-dv')

    Returns:
      SchemaElement object for that path

    Raises:
      AttributeError if not found
    """
    parts = path.split('/')[1:]
    schema = self._schema
    for part in parts:
      element, _ = self.GetElement(schema, part, None)
      schema = element
    return schema

  def _ValidateSchema(self, node, schema):
    """Simple validation of properties.

    This only handles simple mistakes like getting the name wrong. It
    cannot handle relationships between different properties.

    Args:
      node: fdt.Node where the property appears
      schema: NodeDesc containing schema for this node
    """
    schema.Validate(self, node)
    schema_props = [e.name for e in schema.elements
                    if isinstance(e, PropDesc) and
                    self.ElementPresent(e, node)]

    # Validate each property and check that there are no extra properties not
    # mentioned in the schema.
    for prop_name in node.props.keys():
      if prop_name == 'linux,phandle':  # Ignore this (use 'phandle' instead)
        continue
      element, _ = self.GetElement(schema, prop_name, node, PropDesc)
      if not element or not isinstance(element, PropDesc):
        if prop_name == 'phandle':
          self.Fail(node.path, 'phandle target not valid for this node')
        elif not self._IsBuiltInProperty(node, prop_name):
          self.Fail(node.path, "Unexpected property '%s', valid list is (%s)" %
                    (prop_name, ', '.join(schema_props)))
        continue
      element.Validate(self, node.props[prop_name])

    # Check that there are no required properties which we don't have
    for element in schema.elements:
      if (not isinstance(element, PropDesc) or
          not self.ElementPresent(element, node)):
        continue
      if element.required and element.name not in node.props.keys():
        self.Fail(node.path, "Required property '%s' missing" % element.name)

    # Check that any required subnodes are present
    subnode_names = [n.name for n in node.subnodes.values()]
    for element in schema.elements:
      if (not isinstance(element, NodeDesc) or not element.required
          or not self.ElementPresent(element, node)):
        continue
      if element.name not in subnode_names:
        msg = "Missing subnode '%s'" % element.name
        if subnode_names:
          msg += ' in %s' % ', '.join(subnode_names)
        self.Fail(node.path, msg)

  def GetSchema(self, node, parent_schema):
    """Obtain the schema for a subnode

    This finds the schema for a subnode, by scanning for a matching element.

    Args:
      node: fdt.Node whose schema we are searching for
      parent_schema: Schema for the parent node, which contains that schema

    Returns:
      Schema for the node, or None if none found
    """
    schema, needed = self.GetElement(parent_schema, node.name, node.parent,
                                     NodeDesc)
    if not schema and needed:
      elements = [e.name for e in parent_schema.GetNodes()
                  if self.ElementPresent(e, node.parent)]
      self.Fail(os.path.dirname(node.path),
                "Unexpected subnode '%s', valid list is (%s)" %
                (node.name, ', '.join(elements)))
    return schema

  def _ValidateTree(self, node, parent_schema):
    """Validate a node and all its subnodes recursively

    Args:
      node: name of fdt.Node to search for
      parent_schema: Schema for the parent node
    """
    if node.name == '/':
      schema = parent_schema
    else:
      schema = self.GetSchema(node, parent_schema)
      if schema is None:
        return

    self._ValidateSchema(node, schema)
    for subnode in node.subnodes.values():
      self._ValidateTree(subnode, schema)

  @staticmethod
  def ValidateSkuMap(val, prop):
    it = iter(prop.value)
    sku_set = set()
    for sku, phandle in itertools.izip(it, it):
      sku_id = fdt_util.fdt32_to_cpu(sku)
      if sku_id > 255:
        val.Fail(prop.node.path, 'sku_id %d out of range' % sku_id)
      if sku_id in sku_set:
        val.Fail(prop.node.path, 'Duplicate sku_id %d' % sku_id)
      sku_set.add(sku_id)
      phandle_val = fdt_util.fdt32_to_cpu(phandle)
      target = prop.fdt.LookupPhandle(phandle_val)
      if (not CheckPhandleTarget(val, target, '/chromeos/models/MODEL') and
          not CheckPhandleTarget(val, target,
                                 '/chromeos/models/MODEL/submodels/SUBMODEL')):
        val.Fail(prop.node.path,
                 "Phandle '%s' sku-id %d must target a model or submodel'" %
                 (prop.name, sku_id))

  def GetModelTargetDir(self, path, prop_name):
    """Get the target directory for a given path and property

    This looks up the model schema for a given path and property, and locates
    the target directory for that property.

    Args:
      path: Path within model schema to examine (e.g. /thermal)
      prop_name: Property name to examine (e.g. 'dptf-dv')

    Returns:
      target directory for that property (e.g. '/etc/dptf')
    """
    element = self.GetElementByPath(
        '/chromeos/models/MODEL%s/%s' % (path, prop_name))
    return element.target_dir

  def Prepare(self, _fdt):
    """Locate all the models and submodels before we start"""
    self._fdt = _fdt
    models = self._fdt.GetNode('/chromeos/models')
    for model in models.subnodes.values():
      self.model_list.append(model.name)
      sub_models = model.FindNode('submodels')
      if sub_models:
        self.submodel_list[model.name] = (
            [sm.name for sm in sub_models.subnodes.values()])
      else:
        self.submodel_list[model.name] = []


  def Start(self, fnames, partial=False):
    """Start validating a master configuration file

    Args:
      fnames: List of filenames containing the configuration to validate.
          Supports compiled .dtb files, source .dts files and README.md (which
          has configuration source between ``` markers). If partial is False
          then there can be only one filename in the list.
      partial: True to process a list of partial config files (.dtsi)
    """
    tmpfile = None
    self.model_list = []
    self.submodel_list = {}
    self._errors = []
    try:
      if partial:
        dtb, tmpfile = fdt_util.CompileAll(fnames)
      else:
        dtb, tmpfile = fdt_util.EnsureCompiled(fnames[0])
      self.Prepare(fdt.FdtScan(dtb))

      # Validate the entire master configuration
      self._ValidateTree(self._fdt.GetRoot(), self._schema)
    finally:
      if tmpfile:
        os.unlink(tmpfile.name)
    return self._errors

  @classmethod
  def AddElementTargetDirectories(cls, target_dirs, parent):
    if isinstance(parent, PropFile):
      if parent.name in target_dirs:
        if target_dirs[parent.name] != parent.target_dir:
          raise ValueError(
              "Path for element '%s' is inconsistent with previous path '%s'" %
              (parent.target_dir, target_dirs[parent.name]))
      else:
        target_dirs[parent.name] = parent.target_dir
    if isinstance(parent, NodeDesc):
      for element in parent.elements:
        cls.AddElementTargetDirectories(target_dirs, element)

  def GetTargetDirectories(self):
    """Gets a dict of directory targets for each PropFile property

    Returns:
      Dict:
        key: Property name
        value: Ansolute path for this property
    """
    target_dirs = {}
    self.AddElementTargetDirectories(target_dirs, self._schema)
    return target_dirs


# Known directories for installation
CRAS_CONFIG_DIR = '/etc/cras'
UCM_CONFIG_DIR = '/usr/share/alsa/ucm'
LIB_FIRMWARE = '/lib/firmware'

# Basic firmware schema, which is augmented depending on the situation.
FW_COND = {'shares': False, '../whitelabel': False}

BASE_FIRMWARE_SCHEMA = [
    PropString('bcs-overlay', True, 'overlay-.*', FW_COND),
    PropString('ec-image', False, r'bcs://.*\.tbz2', FW_COND),
    PropString('main-image', False, r'bcs://.*\.tbz2', FW_COND),
    PropString('main-rw-image', False, r'bcs://.*\.tbz2', FW_COND),
    PropString('pd-image', False, r'bcs://.*\.tbz2', FW_COND),
    PropStringList('extra', False,
                   r'(\${(FILESDIR|SYSROOT)}/[a-z/]+)|' +
                   r'(bcs://[A-Za-z0-9\.]+\.tbz2)', FW_COND),
    ]

# Firmware build targets schema, defined here since it is used in a few places.
BUILD_TARGETS_SCHEMA = NodeDesc('build-targets', True, elements=[
    PropString('coreboot', True),
    PropString('ec', True),
    PropString('depthcharge', True),
    PropString('libpayload', True),
    PropString('cr50'),
], conditional_props={'shares': False, '../whitelabel': False})

BASE_AUDIO_SCHEMA = [
    PropString('card', True, '', {'audio-type': False}),
    PropFile('volume', True, '', {'audio-type': False}, CRAS_CONFIG_DIR),
    PropFile('dsp-ini', True, '', {'audio-type': False}, CRAS_CONFIG_DIR),
    PropFile('hifi-conf', True, '', {'audio-type': False}, UCM_CONFIG_DIR),
    PropFile('alsa-conf', True, '', {'audio-type': False}, UCM_CONFIG_DIR),
    PropString('topology-name', False, r'\w+'),
    PropFile('topology-bin', False, '', {'audio-type': False}, LIB_FIRMWARE),

    # TODO(sjg@chromium.org): There is no validation that we have these two.
    # They must both exist either in the model's audio node or here.
    PropFile('cras-config-dir', False, r'[\w${}]+', target_dir=CRAS_CONFIG_DIR),
    PropString('ucm-suffix', False, r'[\w${}]+'),
]

BASE_AUDIO_NODE = [
    NodeAny(r'main', [
        PropPhandle('audio-type', '/chromeos/family/audio/ANY',
                    False),
    ] + BASE_AUDIO_SCHEMA)
]
NOT_WL = {'whitelabel': False}

"""This is the schema. It is a hierarchical set of nodes and properties, just
like the device tree. If an object subclasses NodeDesc then it is a node,
possibly with properties and subnodes.

In this way it is possible to describe the schema in a fairly natural,
hierarchical way.
"""
SCHEMA = NodeDesc('/', True, [
    NodeDesc('chromeos', True, [
        NodeDesc('family', True, [
            NodeDesc('audio', elements=[
                NodeAny('', [PropPhandleTarget()] +
                        copy.deepcopy(BASE_AUDIO_SCHEMA)),
            ]),
            NodeDesc('firmware', elements=[
                PropString('script', True, r'updater4\.sh'),
                NodeAny('', [
                    PropPhandleTarget(),
                    copy.deepcopy(BUILD_TARGETS_SCHEMA),
                    ] + copy.deepcopy(BASE_FIRMWARE_SCHEMA))
            ]),
            NodeDesc('touch', False, [
                NodeAny('', [
                    PropPhandleTarget(),
                    PropString('firmware-bin', True, ''),
                    PropString('firmware-symlink', True, ''),
                    PropString('vendor', True, ''),
                ]),
            ]),
            NodeDesc('mapping', False, [
                NodeAny(r'sku-map(@[0-9])?', [
                    PropString('platform-name', False, ''),
                    PropString('smbios-name-match', False, ''),
                    PropPhandle('single-sku', '/chromeos/models/MODEL', False),
                    PropCustom('simple-sku-map',
                               CrosConfigValidator.ValidateSkuMap, False),
                ]),
            ]),
        ]),
        NodeDesc('models', True, [
            NodeModel([
                PropPhandleTarget(),
                PropPhandle('default', '/chromeos/models/MODEL', False),
                PropPhandle('whitelabel', '/chromeos/models/MODEL', False),
                NodeDesc('firmware', False, [
                    PropPhandle('shares', '/chromeos/family/firmware/ANY',
                                False, {'../whitelabel': False}),
                    PropString(('sig-id-in-customization-id'),
                               conditional_props={'../whitelabel': False}),
                    PropString('key-id', False, '[A-Z][A-Z0-9]+'),
                    copy.deepcopy(BUILD_TARGETS_SCHEMA)
                    ] + copy.deepcopy(BASE_FIRMWARE_SCHEMA)),
                PropString('brand-code', False, '[A-Z]{4}'),
                PropString('powerd-prefs', conditional_props=NOT_WL),
                PropString('wallpaper', False, '[a-z_]+'),
                NodeDesc('audio', False, copy.deepcopy(BASE_AUDIO_NODE),
                         conditional_props=NOT_WL),
                NodeDesc('submodels', False, [
                    NodeSubmodel([
                        PropPhandleTarget(),
                        NodeDesc('audio', False, copy.deepcopy(BASE_AUDIO_NODE),
                                 conditional_props={'../../audio': False}),
                        NodeDesc('touch', False, [
                            PropString('present', False, r'yes|no|probe'),
                            PropString('probe-regex', False, ''),
                        ]),
                    ])
                ], conditional_props=NOT_WL),
                NodeDesc('thermal', False, [
                    PropFile('dptf-dv', False, r'\w+/dptf.dv',
                             target_dir='/etc/dptf'),
                ], conditional_props=NOT_WL),
                NodeDesc('touch', False, [
                    PropString('present', False, r'yes|no|probe'),
                    # We want to validate that probe-regex is only present when
                    # 'present' = 'probe', but have no way of doing this
                    # currently.
                    PropString('probe-regex', False, ''),
                    NodeAny(r'(stylus|touchpad|touchscreen)(@[0-9])?', [
                        PropString('pid', False),
                        PropString('version', True),
                        PropPhandle('touch-type', '/chromeos/family/touch/ANY',
                                    False),
                        PropString('firmware-bin', True, '',
                                   {'touch-type': False}),
                        PropString('firmware-symlink', True, '',
                                   {'touch-type': False}),
                        PropString('date-code', False),
                    ]),
                ], conditional_props=NOT_WL),
                NodeDesc('whitelabels', False, [
                    NodeAny('', [
                        PropString('brand-code', False, '[A-Z]{4}'),
                        PropString('wallpaper', False, '[a-z_]+'),
                        PropString('key-id', False, '[A-Z][A-Z0-9]+'),
                    ]),
                ], conditional_props=NOT_WL),
            ])
        ]),
        NodeDesc('schema', False, [
            NodeDesc('target-dirs', False, [
                PropAny(),
            ])
        ])
    ])
])


def GetValidator():
  """Get a schema validator for use by another module

  Returns:
    CrosConfigValidator object
  """
  return CrosConfigValidator(SCHEMA, raise_on_error=True)


def ShowErrors(fname, errors):
  """Show validation errors

  Args:
    fname: Filename containng the errors
    errors: List of errors, each a string
  """
  print('%s:' % fname, file=sys.stderr)
  for error in errors:
    print(error, file=sys.stderr)
  print(file=sys.stderr)


def Main(argv=None):
  """Main program for validator

  This validates each of the provided files and prints the errors for each, if
  any.

  Args:
    argv: Arguments to the problem (excluding argv[0]); if None, uses sys.argv
  """
  if argv is None:
    argv = sys.argv[1:]
  args = ParseArgv(argv)
  validator = CrosConfigValidator(SCHEMA, args.raise_on_error)
  found_errors = False
  try:
    # If we are given partial files (.dtsi) then we compile them all into one
    # .dtb and validate that.
    if args.partial:
      errors = validator.Start(args.config, partial=True)
      fname = args.config[0]
      if errors:
        ShowErrors(fname, errors)
        found_errors = True

    # Otherwise process each file individually
    else:
      for fname in args.config:
        errors = validator.Start([fname])
        if errors:
          found_errors = True
          if errors:
            ShowErrors(fname, errors)
            found_errors = True
  except cros_build_lib.RunCommandError as e:
    if args.debug:
      raise
    print('Failed: %s' % e, file=sys.stderr)
    found_errors = True
  if found_errors:
    sys.exit(1)


if __name__ == "__main__":
  Main()