How to use new image configuration API
--------------------------------------

This API provides a framework to enable/disable the inclusion components in a
target image using configuration files.

Components that can be configured using this API:
  - legacy syscalls
  - kernelmod services
  - clientEnv services
  - generic "features"

The enablement works through lists, which are specified in the target
configuration files and potentially extended by chipset-specific configuration
files and the commandline.
Examples of these files are tzbsp_def.cfg, tzbsp_def_8250.cfg, mon_def.cfg, etc.
For each group of components, there are 3 lists:
  - an 'all' list, listing all of the components of this type the system knows about
  - an 'enabled' list, listing all the components of this type which are to be enabled
  - a 'disabled' list, listing all the components of this type which are to be disabled

A feature/syscall/service/... is enabled if and only if:
  - it is present in the corresponding 'all' list
  - it is present in the corresponding 'enabled' list
  - it is NOT present in the corresponding 'disabled' list.

env.FeatureIsEnabled(feature)/LegacySyscallIsEnabled(...)/KmodServiceIsEnabled(...)/CClientEnvServiceIsEnabled(...)
  - returns True if th feature/syscall/... is enabled
  - Note: this function does not check if the current environment contain the
    images a feature is meant for (e.g. monitor environment parsing a qsee
    SConscript). This check is instead done by the Add... family of functions
    (AddFeatureSources, AddFeatureLibrary, ...).
env.AddFeatureSources(images, feature, sources, stubs)/AddLegacySyscallSources(...)/AddKmodServiceSources(...)/AddCClientEnvSources(...)
  - Wrapper around env.AddBinaryLibrary
  - if enabled, the implementing files (sources) are used to build with
  - if disabled, the stubs files are used to build with
env.AddFeatureLibrary(images, libpath, feature, sources, stubs)/AddLegacySyscallLibrary(...)/AddKmodServiceLibrary(...)/AddCClientEnvLibrary(...)
  - Wrapper around env.AddBinaryLibrary
  - if enabled, the implementing files (sources) are used to build with
  - if disabled, the stubs files are used to build with
env.UIDToClassNum(uid_str)
  - returns and int value of the given uid_str.
  - uid_str can be either long form
    - e.g.
      - 'CApp_UID'
      - 'CSecureCamera_UID'
  - or short fold
    - e.g.
      - 'app'
      - 'securecamera'

env.BoolVariable(key, help, default, enable_map={}, disable_map={}, enable_if=None)
env.EnumVariable(key, help, default, allowed_values, map={}, ignorecase=0, enable_map={}, disable_map={}, enable_if=None)
env.ListVariable(key, help, default, names, map={}, enable_map={}, disable_map={}, enable_if=None)
env.PackageVariable(key, help, default, searchfunc=None, enable_map={}, disable_map={}, enable_if=None)
env.PathVariable(key, help, default, validator=None, enable_map={}, disable_map={}, enable_if=None)
  - wrapper around the named SCons Variable
    - If enable_map, disable_map, and enable_if are not specified, these methods just return the output of the underlying SCons.Variables.(Bool|Enum|List|Package|Path)Variable(...) call
  - supports setting environment vars in case of the variable itself being enabled/disabled through the commandline
    or config file
  - enable_map, disable_map
    - dictionaries of environment variable string to value
    - enable_map is added to env if config_name is set to true AND (enable_if(env) returns True or enable_if is None)
    - disable_map is added to env if config_name is set to false OR enable_if(env) returns False
  - enable_if
    - function with following signature
      enable_if(env) --> Bool
    - allows for more complex decision making to enable/disable features than simple on/off switch
  - works in conjunction with env.AddConfigVars(files, args)
  - see env.AddConfigVars(files, args) for example usage



env.AddConfigVars(files, args)
  - takes in config files to read, as well as the scons variables / BoolConfigVars to configure
  - multiple files may be read. later files in list have higher priority when configuring the same variable
  - args must be a list of tuples of scons config files as documented here: https://scons.org/doc/3.0.1/HTML/scons-user/ch10s02.html
    - can also be the return value from env.BoolVariable
  - example usage:
  env.AddConfigVars(['/path/to/my/config/file.conf'],
  [
    env.BoolVariable('debug','debug',0,{'CCFLAGS':' -g ','CPPDEFINES':'DEBUG'},{'CPPDEFINES':'NDEBUG'}),
    ('lib_path','path to user libraries','/bad/path/must/be/in/config/file'),
  ])
  - in this case, if debug=1 is specified on the commandline or file.conf, DEBUG is added to CPPDEFINES and -g is added to CCFLAGS
  - otherwise, NDEBUG is added to CPPDEFINES

env.AddCommandlineArgument(variable)
  - Takes in a SCons Variable (documented below), parses ARGUMENTS for it, and adds result to the env.
  - example usage:

  env.AddCommandlineArgument(env.BoolVariable('enable_debug','compile with -Og',0))
  if env.get('enable_debug'):
    env.Append(CCFLAGS=' -g ')