Skip to main content

The cdlInterfaces definition

note

Work in progress.

Purpose​

Define a map of interface objects (generic functionalities that can be provided by a number of different implementations).

Syntax​

{
    "cdlInterfaces": {
        "<name>": {
            "display": "<short name>",
            "description": "<long text>",

            ... interface members ...
        }
    }
}

Description​

The cdlInterfaces objects are a special type of computed cdlOptions object. They provide an abstraction mechanism that can be used to simplify xCDL expressions. A cdlInterfaces object can have most of the properties and behaviour of a cdlOptions object, but with some limitations (see the Unavailable properties below)

As an example, suppose that some package relies on the presence of code that implements the standard kernel scheduling interface. However, the requirement is no more stringent than this, so the constraint can be satisfied by the mlqueue scheduler, the bitmap scheduler, or any additional schedulers that may get implemented in the future. A first attempt at expressing the dependency might be:

"requires": [ "iEnabled('kernel/sched-mlqueue') || isEnabled('kernel/sched-bitmap')" ]

This constraint is limited and may need to be changed if a new scheduler is added to the system. Interfaces provide a way of expressing more general relationships:

"requires": [ "implementationsOf('kernel/scheduler') === 1" ]

The interface kernel/scheduler is implemented by both the mlqueue and bitmap schedulers, and may be implemented by future schedulers as well. The value returned by implementationsOf() on an interface is the number of implementers that are active and enabled, so in a typical configuration only one scheduler will be in use and the value of implementationsOf() will be 1. If all schedulers are disabled then the value of implementationsOf() will be 0 and the requires constraint will not be satisfied.

Some component authors may prefer to use the first requires constraint, believing that the code has only been tested with the mlqueue and bitmap schedulers and cannot be guaranteed to work with any new schedulers. Other component authors may take a more optimistic view, assuming that their code will work with any scheduler until proven otherwise.

Each cdlInterfaces object is defined as a JSON object that has an name and a body. Names are map keys and must be unique within a parent.

A commonly used constraint on interface values takes the form:

"requires": [ "implementationsOf('kernel/scheduler') === 1" ]

This constraint specifies that there can be only one scheduler in the system. In some circumstances, the configuration tools can detect this pattern and act accordingly. For example, enabling the bitmap scheduler would automatically disable the mlqueue scheduler.

Containers​

The cdlInterfaces objects are not containers, so they cannot hold other objects such as cdlOptions or cdlComponents objects.

Properties​

  • activeIf - an array of boolean expressions to be evaluated; if all are true, the active state of this interface remains true
  • compilerIncludeFolders - an array of folder paths that should be used during the built if this interface is active and enabled
  • compilerOptions - a map of toolchain specific objects with compiler options to be used during the build if this interface is active and enabled
  • compilerPreprocessorSymbols - a map of toolchain specific objects with preprocessor symbols to be used during the build if this interface is active and enabled
  • compilerSourceFiles - an array of source file paths that should be built if this interface is active and enabled
  • defaultEnabled - a boolean expression that provides an initial value for the interface's enabled/disabled state
  • description - provides a reasonably long paragraph with a textual description for the component
  • display - provides a node name for the component when rendered in the configuration hierarchy
  • docsUrl - provides the location of online documentation for the component
  • generatedDefinition - a valid C/C++ preprocessor identifier to be defined in the header file if the interface is active and enabled
  • generatedFile - the full file path of the header where the interface will generate a definition (if missing, inherited from the parent node)
  • legalValues - interfaces always have a small numerical value; the legalValues can be used to apply additional constraints such as an upper limit
  • parent - provides a method to break the default hierarchy and directly specify the xCDL path of the parent of this interface
  • requires - an array of boolean goal expressions usually referring to other objects that need to be enabled for this interface to be enabled
  • valueFormat - control how the interface's value will appear in the configuration header file

Unavailable properties​

  • computed - always true; the interface's value is always computed from the number of enabled and active components that implements it
  • configurable - always true; interfaces are always enabled and this cannot be changed
  • defaultValue - undefined; meaningless since the interface's value is always computed
  • implements - interfaces cannot implement other interfaces
  • valueType - always int; interfaces always have integer non-negative values

Example​

{
    "cdlInterfaces": {
        "scheduler": {
            ...
            "parent": "kernel",
            "requires": [ "implementationsOf('kernel/scheduler') === 1" ]
        }
    }
}

See also​

eCos reference​