Skip to main content

The computed definition

note

Work in progress.

Purpose​

Specify that the current object's value is not user-modifiable but is computed using an appropriate xCDL expression.

Syntax​

{
    "cdlOptions": {
        "<name>": {
            ...
            "computed": "<expression>",
            ...
        }
    }
}

The value of the computed property is a string containing an expression that is evaluated each time the object is referenced. The content is formatted according to the valueType.

Default value​

If missing, no computed value is used and the object's value is static.

Description​

In some cases it is useful to have a configuration object whose value cannot be modified directly by the user. This can be achieved using a computed property, which defines an xCDL expression (see the Section called Ordinary Expressions in xCDL packages for a description of expression syntax). The configuration system evaluates the expression whenever needed to generate the header line or when referred from another expression. The result depends on the object's valueType:

  • none - objects with this type have no value, so the computed property is not applicable
  • bool - the expression should evaluate to a boolean value
  • int - the expression should evaluate to an integer
  • float - the expression should evaluate to a float
  • string - the expression should evaluate to a string

There are a number of valid uses for computed options, and there are also many cases where some other xCDL facility would be more appropriate.

Valid uses of computed objects include the following:

  • On some target hardware, a particular feature may be user-configurable, while on other targets it is fixed. For example, some processors can operate in either big-endian or little-endian mode, while other processors do not provide any choice. It is possible to have an option bigendian which is computed in some architectural HAL packages but user-modifiable in others.
  • Computed objects can provide an alternative way for one package to affect the behaviour of another one. Suppose a package may provide two possible implementations: a preferred one involving self-modifying code and a slower alternative. If the system involves a ROM bootstrap, then the slower alternative must be used, but it would be inappropriate to modify the startup option in every HAL to impose constraints on this package. Instead, it is possible to have a computed option whose value is valueOf('hal/startup') === "ROM", and which has appropriate consequences. Arguably, this is a spurious example, and it should be a user choice whether or not to use self-modifying code with a defaultValue based on hal/startup, but that is for the component author to decide.
  • Sometimes it should be possible to perform a particular test at compile-time, for example by using a C/C++ preprocessor #if construct. However the preprocessor has only limited functionality; for example, it cannot perform string comparisons. xCDL expressions are more powerful.
  • Occasionally, a particular sub-expression may occur multiple times in an xCDL file. If the sub-expression is sufficiently complex, then it may be worthwhile to have a computed option whose value is the sub-expression, and then reference that computed option in the appropriate places.

Alternatives to using computed options include the following:

  • The cdlInterfaces objects are a form of computed objects intended as an abstraction mechanism. For example, an interface can be used to express the concept of any scheduler, as opposed to a specific one such as the bitmap scheduler.

Example​

A constant on some target hardware, perhaps user-modifiable on other targets.

{
    "cdlOptions": {
        "period": {
            "display": "Real-time clock period",
            "parent": "hal/rtc",
            "valueType": "int",
            "computed": "12500",
        }
    }
}

See also​

eCos reference​