mbed-os/tools/config.py

"""
mbed SDK
Copyright (c) 2016 ARM Limited

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
"""

# Implementation of mbed configuration mechanism
from copy import deepcopy
from collections import OrderedDict
from tools.utils import json_file_to_dict, ToolException
from tools.targets import Target
import os

# Base class for all configuration exceptions
class ConfigException(Exception):
    pass

# This class keeps information about a single configuration parameter
class ConfigParameter:
    # name: the name of the configuration parameter
    # data: the data associated with the configuration parameter
    # unit_name: the unit (target/library/application) that defines this parameter
    # unit_ kind: the kind of the unit ("target", "library" or "application")
    def __init__(self, name, data, unit_name, unit_kind):
        self.name = self.get_full_name(name, unit_name, unit_kind, allow_prefix = False)
        self.defined_by = self.get_display_name(unit_name, unit_kind)
        self.set_by = self.defined_by
        self.help_text = data.get("help", None)
        self.value = data.get("value", None)
        self.required = data.get("required", False)
        self.macro_name = data.get("macro_name", "MBED_CONF_%s" % self.sanitize(self.name.upper()))

    # Return the full (prefixed) name of a parameter.
    # If the parameter already has a prefix, check if it is valid
    # name: the simple (unqualified) name of the parameter
    # unit_name: the unit (target/library/application) that defines this parameter
    # unit_kind: the kind of the unit ("target", "library" or "application")
    # label: the name of the label in the 'target_config_overrides' section (optional)
    # allow_prefix: True to allo the original name to have a prefix, False otherwise
    @staticmethod
    def get_full_name(name, unit_name, unit_kind, label = None, allow_prefix = True):
        if name.find('.') == -1: # the name is not prefixed
            if unit_kind == "target":
                prefix = "target."
            elif unit_kind == "application":
                prefix = "app."
            else:
                prefix = unit_name + '.'
            return prefix + name
        # The name has a prefix, so check if it is valid
        if not allow_prefix:
            raise ConfigException("Invalid parameter name '%s' in '%s'" % (name, ConfigParameter.get_display_name(unit_name, unit_kind, label)))
        temp = name.split(".")
        # Check if the parameter syntax is correct (must be unit_name.parameter_name)
        if len(temp) != 2:
            raise ConfigException("Invalid parameter name '%s' in '%s'" % (name, ConfigParameter.get_display_name(unit_name, unit_kind, label)))
        prefix = temp[0]
        # Check if the given parameter prefix matches the expected prefix
        if (unit_kind == "library" and prefix != unit_name) or (unit_kind == "target" and prefix != "target"):
            raise ConfigException("Invalid prefix '%s' for parameter name '%s' in '%s'" % (prefix, name, ConfigParameter.get_display_name(unit_name, unit_kind, label)))
        return name

    # Return the name displayed for a unit when interogating the origin
    # and the last set place of a parameter
    # unit_name: the unit (target/library/application) that defines this parameter
    # unit_kind: the kind of the unit ("target", "library" or "application")
    # label: the name of the label in the 'target_config_overrides' section (optional)
    @staticmethod
    def get_display_name(unit_name, unit_kind, label = None):
        if unit_kind == "target":
            return "target:" + unit_name
        elif unit_kind == "application":
            return "application%s" % ("[%s]" % label if label else "")
        else: # library
            return "library:%s%s" % (unit_name, "[%s]" % label if label else "")

    # "Sanitize" a name so that it is a valid C macro name
    # Currently it simply replaces '.' and '-' with '_'
    # name: the un-sanitized name.
    @staticmethod
    def sanitize(name):
        return name.replace('.', '_').replace('-', '_')

    # Sets a value for this parameter, remember the place where it was set
    # value: the value of the parameter
    # unit_name: the unit (target/library/application) that defines this parameter
    # unit_ kind: the kind of the unit ("target", "library" or "application")
    # label: the name of the label in the 'target_config_overrides' section (optional)
    def set_value(self, value, unit_name, unit_kind, label = None):
        self.value = value
        self.set_by = self.get_display_name(unit_name, unit_kind, label)

    # Return the string representation of this configuration parameter
    def __str__(self):
        if self.value is not None:
            return '%s = %s (macro name: "%s")' % (self.name, self.value, self.macro_name)
        else:
            return '%s has no value' % self.name

    # Return a verbose description of this configuration paramater as a string
    def get_verbose_description(self):
        desc = "Name: %s%s\n" % (self.name, " (required parameter)" if self.required else "")
        if self.help_text:
            desc += "    Description: %s\n" % self.help_text
        desc += "    Defined by: %s\n" % self.defined_by
        if not self.value:
            return desc + "    No value set"
        desc += "    Macro name: %s\n" % self.macro_name
        desc += "    Value: %s (set by %s)" % (self.value, self.set_by)
        return desc

# A representation of a configuration macro. It handles both macros without a value (MACRO)
# and with a value (MACRO=VALUE)
class ConfigMacro:
    def __init__(self, name, unit_name, unit_kind):
        self.name = name
        self.defined_by = ConfigParameter.get_display_name(unit_name, unit_kind)
        if name.find("=") != -1:
            tmp = name.split("=")
            if len(tmp) != 2:
                raise ValueError("Invalid macro definition '%s' in '%s'" % (name, self.defined_by))
            self.macro_name = tmp[0]
        else:
            self.macro_name = name

# 'Config' implements the mbed configuration mechanism
class Config:
    # Libraries and applications have different names for their configuration files
    __mbed_app_config_name = "mbed_app.json"
    __mbed_lib_config_name = "mbed_lib.json"

    # Allowed keys in configuration dictionaries
    # (targets can have any kind of keys, so this validation is not applicable to them)
    __allowed_keys = {
        "library": set(["name", "config", "target_overrides", "macros", "__config_path"]),
        "application": set(["config", "custom_targets", "target_overrides", "macros", "__config_path"])
    }

    # The initialization arguments for Config are:
    #     target: the name of the mbed target used for this configuration instance
    #     top_level_dirs: a list of top level source directories (where mbed_abb_config.json could be found)
    # __init__ will look for the application configuration file in top_level_dirs.
    # If found once, it'll parse it and check if it has a custom_targets function.
    # If it does, it'll update the list of targets if need.
    # If found more than once, an exception is raised
    # top_level_dirs can be None (in this case, mbed_app_config.json will not be searched)
    def __init__(self, target, top_level_dirs = []):
        app_config_location = None
        for s in (top_level_dirs or []):
            full_path = os.path.join(s, self.__mbed_app_config_name)
            if os.path.isfile(full_path):
                if app_config_location is not None:
                    raise ConfigException("Duplicate '%s' file in '%s' and '%s'" % (self.__mbed_app_config_name, app_config_location, full_path))
                else:
                    app_config_location = full_path
        self.app_config_data = json_file_to_dict(app_config_location) if app_config_location else {}
        # Check the keys in the application configuration data
        unknown_keys = set(self.app_config_data.keys()) - self.__allowed_keys["application"]
        if unknown_keys:
            raise ConfigException("Unknown key(s) '%s' in %s" % (",".join(unknown_keys), self.__mbed_app_config_name))
        # Update the list of targets with the ones defined in the application config, if applicable
        Target.add_py_targets(self.app_config_data.get("custom_targets", {}))
        self.lib_config_data = {}
        # Make sure that each config is processed only once
        self.processed_configs = {}
        self.target = target if isinstance(target, str) else target.name
        self.target_labels = Target.get_target(self.target).get_labels()
        self.target_instance = Target.get_target(self.target)

    # Add one or more configuration files
    def add_config_files(self, flist):
        for f in flist:
            if not f.endswith(self.__mbed_lib_config_name):
                continue
            full_path = os.path.normpath(os.path.abspath(f))
            # Check that we didn't already process this file
            if self.processed_configs.has_key(full_path):
                continue
            self.processed_configs[full_path] = True
            # Read the library configuration and add a "__full_config_path" attribute to it
            cfg = json_file_to_dict(f)
            cfg["__config_path"] = full_path
            # If there's already a configuration for a module with the same name, exit with error
            if self.lib_config_data.has_key(cfg["name"]):
                raise ConfigException("Library name '%s' is not unique (defined in '%s' and '%s')" % (cfg["name"], full_path, self.lib_config_data[cfg["name"]]["__config_path"]))
            self.lib_config_data[cfg["name"]] = cfg

    # Helper function: process a "config_parameters" section in either a target, a library or the application
    # data: a dictionary with the configuration parameters
    # params: storage for the discovered configuration parameters
    # unit_name: the unit (target/library/application) that defines this parameter
    # unit_kind: the kind of the unit ("target", "library" or "application")
    def _process_config_parameters(self, data, params, unit_name, unit_kind):
        for name, v in data.items():
            full_name = ConfigParameter.get_full_name(name, unit_name, unit_kind)
            # If the parameter was already defined, raise an error
            if full_name in params:
                raise ConfigException("Parameter name '%s' defined in both '%s' and '%s'" % (name, ConfigParameter.get_display_name(unit_name, unit_kind), params[full_name].defined_by))
            # Otherwise add it to the list of known parameters
            # If "v" is not a dictionary, this is a shortcut definition, otherwise it is a full definition
            params[full_name] = ConfigParameter(name, v if isinstance(v, dict) else {"value": v}, unit_name, unit_kind)
        return params

    # Helper function: process "config_parameters" and "target_config_overrides" in a given dictionary
    # data: the configuration data of the library/appliation
    # params: storage for the discovered configuration parameters
    # unit_name: the unit (library/application) that defines this parameter
    # unit_kind: the kind of the unit ("library" or "application")
    def _process_config_and_overrides(self, data, params, unit_name, unit_kind):
        self._process_config_parameters(data.get("config", {}), params, unit_name, unit_kind)
        for label, overrides in data.get("target_overrides", {}).items():
            # If the label is defined by the target or it has the special value "*", process the overrides
            if (label == '*') or (label in self.target_labels):
                # Parse out cumulative attributes
                for attr in Target._Target__cumulative_attributes:
                    attrs = getattr(self.target_instance, attr)

                    if attr+'_add' in overrides:
                        attrs.extend(overrides[attr+'_add'])
                        del overrides[attr+'_add']

                    if attr+'_remove' in overrides:
                        for a in overrides[attr+'_remove']:
                            attrs.remove(a)
                        del overrides[attr+'_remove']

                    setattr(self.target_instance, attr, attrs)

                # Consider the others as overrides
                for name, v in overrides.items():
                    # Get the full name of the parameter
                    full_name = ConfigParameter.get_full_name(name, unit_name, unit_kind, label)
                    # If an attempt is made to override a parameter that isn't defined, raise an error
                    if not full_name in params:
                        raise ConfigException("Attempt to override undefined parameter '%s' in '%s'" % (full_name, ConfigParameter.get_display_name(unit_name, unit_kind, label)))
                    params[full_name].set_value(v, unit_name, unit_kind, label)
        return params

    # Read and interpret configuration data defined by targets
    def get_target_config_data(self):
        # We consider the resolution order for our target and sort it by level reversed,
        # so that we first look at the top level target (the parent), then its direct children,
        # then the children's children and so on, until we reach self.target
        # TODO: this might not work so well in some multiple inheritance scenarios
        # At each step, look at two keys of the target data:
        #   - config_parameters: used to define new configuration parameters
        #   - config_overrides: used to override already defined configuration parameters
        params, json_data = {}, Target.get_json_target_data()
        resolution_order = [e[0] for e in sorted(Target.get_target(self.target).resolution_order, key = lambda e: e[1], reverse = True)]
        for tname in resolution_order:
            # Read the target data directly from its description
            t = json_data[tname]
            # Process definitions first
            self._process_config_parameters(t.get("config", {}), params, tname, "target")
            # Then process overrides
            for name, v in t.get("overrides", {}).items():
                full_name = ConfigParameter.get_full_name(name, tname, "target")
                # If the parameter name is not defined or if there isn't a path from this target to the target where the
                # parameter was defined in the target inheritance tree, raise an error
                # We need to use 'defined_by[7:]' to remove the "target:" prefix from defined_by
                if (not full_name in params) or (not params[full_name].defined_by[7:] in Target.get_target(tname).resolution_order_names):
                    raise ConfigException("Attempt to override undefined parameter '%s' in '%s'" % (name, ConfigParameter.get_display_name(tname, "target")))
                # Otherwise update the value of the parameter
                params[full_name].set_value(v, tname, "target")
        return params

    # Helper function: process a macro definition, checking for incompatible duplicate definitions
    # mlist: list of macro names to process
    # macros: dictionary with currently discovered macros
    # unit_name: the unit (library/application) that defines this macro
    # unit_kind: the kind of the unit ("library" or "application")
    def _process_macros(self, mlist, macros, unit_name, unit_kind):
        for mname in mlist:
            m = ConfigMacro(mname, unit_name, unit_kind)
            if (m.macro_name in macros) and (macros[m.macro_name].name != mname):
                # Found an incompatible definition of the macro in another module, so raise an error
                full_unit_name = ConfigParameter.get_display_name(unit_name, unit_kind)
                raise ConfigException("Macro '%s' defined in both '%s' and '%s' with incompatible values" % (m.macro_name, macros[m.macro_name].defined_by, full_unit_name))
            macros[m.macro_name] = m

    # Read and interpret configuration data defined by libs
    # It is assumed that "add_config_files" above was already called and the library configuration data
    # exists in self.lib_config_data
    def get_lib_config_data(self):
        all_params, macros = {}, {}
        for lib_name, lib_data in self.lib_config_data.items():
            unknown_keys = set(lib_data.keys()) - self.__allowed_keys["library"]
            if unknown_keys:
                raise ConfigException("Unknown key(s) '%s' in %s" % (",".join(unknown_keys), lib_name))
            all_params.update(self._process_config_and_overrides(lib_data, {}, lib_name, "library"))
            self._process_macros(lib_data.get("macros", []), macros, lib_name, "library")
        return all_params, macros

    # Read and interpret the configuration data defined by the target
    # The target can override any configuration parameter, as well as define its own configuration data
    # params: the dictionary with configuration parameters found so far (in the target and in libraries)
    # macros: the list of macros defined in the configuration
    def get_app_config_data(self, params, macros):
        app_cfg = self.app_config_data
        # The application can have a "config_parameters" and a "target_config_overrides" section just like a library
        self._process_config_and_overrides(app_cfg, params, "app", "application")
        # The application can also defined macros
        self._process_macros(app_cfg.get("macros", []), macros, "app", "application")

    # Return the configuration data in two parts:
    #   - params: a dictionary with (name, ConfigParam) entries
    #   - macros: the list of macros defined with "macros" in libraries and in the application
    def get_config_data(self):
        all_params = self.get_target_config_data()
        lib_params, macros = self.get_lib_config_data()
        all_params.update(lib_params)
        self.get_app_config_data(all_params, macros)
        return all_params, [m.name for m in macros.values()]

    # Helper: verify if there are any required parameters without a value in 'params'
    def _check_required_parameters(self, params):
        for p in params.values():
            if p.required and (p.value is None):
                raise ConfigException("Required parameter '%s' defined by '%s' doesn't have a value" % (p.name, p.defined_by))

    # Return the macro definitions generated for a dictionary of configuration parameters
    # params: a dictionary of (name, ConfigParameters instance) mappings
    @staticmethod
    def parameters_to_macros(params):
        return ['%s=%s' % (m.macro_name, m.value) for m in params.values() if m.value is not None]

    # Return the configuration data converted to a list of C macros
    def get_config_data_macros(self):
        params, macros = self.get_config_data()
        self._check_required_parameters(params)
        return macros + self.parameters_to_macros(params)