Skip to main content

cdlInterfaces object

note

Work in progress.

Purpose​

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

Syntax​

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

      ... interface members ...
    }
  ]
}

The value of the cdlInterfaces property is an array of interface objects, each having a name and a body. Names are map keys and must be unique within a parent.

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.

The value of an interface is the number of implementors that are active and enabled.

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": [ "isEnabled('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 a 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.

Transitive dependencies​

When an interface is mentioned as a dependency, the configuration tools should also ensure that all of its implementators are enabled and that their dependencies are satisfied.

The interface dependency is then replaced by the list of implementors.

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
  • customDefine - a valid C/C++ preprocessor identifier to be defined in the header file if the 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 interface
  • display - provides a node name for the interface when rendered in the configuration hierarchy
  • documentationUrls - provides the location of online documentation for the interface
  • headerFile - the full file path of the header where the interface will generate a definition (if missing, inherited from the parent node)
  • legalValues - an array of restrictions that the value of this interface must satisfy
  • privateCompilerOptions - a map of toolchain-specific objects with compiler private options used during the build if this interface is active and enabled
  • privateDefines - a map of toolchain-specific objects with preprocessor macros used during the build if this interface is active and enabled
  • privateIncludeFolders - an array of folder paths used during the build if this interface is active and enabled
  • publicCompilerOptions - a map of toolchain-specific objects with compiler public options used during the build and propagated upwards if this interface is active and enabled
  • publicDefines - a map of toolchain-specific objects with preprocessor macros used during the build and propagated upwards if this interface is active and enabled
  • publicIncludeFolders - an array of folder paths used during the build and propagated upwards if this interface is active and enabled
  • requires - an array of boolean goal expressions usually referring to other objects that need to be enabled for this interface to be enabled
  • sourceFiles - an array of source file paths that should be built if this interface is active and 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 implement 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": [
    {
      "name": "kernel.scheduler",
      ...
      "legalValues": 1
    }
  ]
}

See also​

eCos reference​