Values and Expressions

Option Values

There are four factors which go into an option's value:

1. An option may or may not be loaded.

2. If the option is loaded, it may or may not be active.

3. Even if the option is active, it may or may not be enabled.

4. If the option is loaded, active and enabled then it will have some associated data which constitutes its value.

    requires CYGPKG_KERNEL
    requires CYGPKG_KERNEL_THREADS_DATA
    requires !CYGSEM_KERNEL_SCHED_TIMESLICE

cdl_component CYGPKG_LIBC_RAND {
    flavor        none
    compile       stdlib/rand.cxx

    cdl_option CYGSEM_LIBC_PER_THREAD_RAND {
        requires      CYGVAR_KERNEL_THREADS_DATA
        default_value 0
    }

    cdl_option CYGNUM_LIBC_RAND_SEED {
        flavor        data
        legal_values  0 to 0x7fffffff
        default_value 1
    }

    cdl_option CYGNUM_LIBC_RAND_TRACE_LEVEL {
        flavor        data
        legal_values  0 to 1
        default_value 0
    }
}

#define CYGPKG_LIBC_RAND 1

#define CYGSEM_LIBC_PER_THREAD_RAND 1

#define CYGNUM_LIBC_RAND_SEED 1
#define CYGNUM_LIBC_RAND_SEED_1
#define CYGNUM_LIBC_RAND_TRACE_LEVEL 0
#define CYGNUM_LIBC_RAND_TRACE_LEVEL_0

Ordinary Expressions

Expressions in CDL follow a conventional syntax, for example:

    default_value CYGGLO_CODESIZE > CYGGLO_SPEED
    default_value { (CYG_HAL_STARTUP == "RAM" &&
                     !CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS &&
                     !CYGINT_HAL_USE_ROM_MONITOR_UNSUPPORTED &&
                     !CYGSEM_HAL_POWERPC_COPY_VECTORS) ? 1 : 0 }
    default_value { "\"/dev/ser0\"" }

However there is a complication in that the various arguments to a default_value property will first get processed by a Tcl interpreter, so special characters like quotes and square brackets may get processed. Such problems can be avoided by enclosing non-trivial expressions in braces, as in the second example above. The way expression parsing actually works is as follows:

1. The Tcl interpreter splits the line or lines into a command and its arguments. In the first default_value expression above the command is default_value and there are three arguments, CYGGLO_CODESIZE, > and CYGGLO_SPEED. In the second and third examples there is just one argument, courtesy of the braces.

2. Next option processing takes place, so any initial arguments that begin with a hyphen will be interpreted as options. This can cause problems if the expression involves a negative number, so the special argument -- can be used to prevent option processing on the subsequent arguments.

3. All of the arguments are now concatenated, with a single space in between each one. Hence the following two expressions are equivalent, even though they will have been processed differently up to this point.

   default_value CYGGLO_CODESIZE > CYGGLO_SPEED default_value {CYGGLO_CODESIZE > CYGGLO_SPEED}

4. The expression parsing code now has a single string to process.

CDL expressions consist of four types of element: references to configuration options, constant strings, integers, and floating point numbers. These are combined using a conventional set of operators: the unary operators -, ~ and !; the arithmetic operators +, -, *, / and %; the shift operators << and >>; the comparison operators ==, !=, <, <=, > and >=; the bitwise operators &, ^ and |; the logical operators && and ||; the string concatenation operator .; and the ternary conditional operator A ? B : C. There is also support for some less widely available operators for logical equivalence and implication, and for a set of function-style operations. Bracketed sub-expressions are supported, and the operators have the usual precedence:

Function calls have the usual format of a name, an opening bracket, one or more arguments separated by commas, and a closing bracket. For example:

    requires { !is_substr(CYGBLD_GLOBAL_CFLAGS, " -fno-rtti") }

Functions will differ in the number of arguments and may impose restrictions on some or all of their arguments. For example it may be necessary for the first argument to be a reference to a configuration option. The available functions are described in the Section called Functions.

The logical xor operator evaluates to true if either the left hand side or the right hand side but not both evaluate to true The logical eqv operator evaluates to true if both the left and right hand sides evaluate to true, or if both evaluate to false. The implies operator evaluates to true either if the left hand side is false or if the right hand side is true, in other words A implies B has the same meaning as !A || B. An example use would be:

    requires { is_active(CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE) implies
                   (CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE >= (16 * 1024)) }

This constraint would be satisfied if either the support for a main stack size is disabled, or if that stack is at least 16K. However if such a stack were in use but was too small, a conflict would be raised.

A valid CDL identifier in an expression, for example CYGGLO_SPEED, will be interpreted as a reference to a configuration option by that name. The option does not have to be loaded into the current configuration. When the component framework evaluates the expression it will substitute in a suitable value that depends on whether or not the option is loaded, active, and enabled. The exact rules are described in the Section called Option Values.

A constant string is any sequence of characters enclosed in quotes. Care has to be taken that these quotes are not stripped off by the Tcl interpreter before the CDL expression parser sees them. Consider the following:

    default_value "RAM"

The quote marks will be stripped before the CDL expression parser sees the data, so the expression will be interpreted as a reference to a configuration option RAM. There is unlikely to be such an option, so the actual default value will be 0. Careful use of braces or other Tcl quoting mechanisms can be used to avoid such problems.

String constants consist of the data inside the quotes. If the data itself needs to contain quote characters then appropriate quoting is again necessary, for example:

    default_value { "\"/dev/ser0\"" }

An integer constant consists of a sequence of digits, optionally preceeded with the unary + or - operators. As usual the sequence 0x or 0X can be used for hexadecimal data, and a leading 0 indicates octal data. Internally the component framework uses 64-bit arithmetic for integer data. If a constant is too large then double precision arithmetic will be used instead. Traditional syntax is also used for double precision numbers, for example 3.141592 or -3E6.

Of course this is not completely accurate: CDL is not a typed language, all data is treated as if it were a string. For example the following two lines are equivalent:

    requires CYGNUM_UITRON_SEMAS > 10
    requires { CYGNUM_UITRON_SEMAS > "10" }

When an expression gets evaluated the operators will attempt appropriate conversions. The > comparison operator can be used on either integer or double precision numbers, so it will begin by attempting a string to integer conversion of both operands. If that fails it will attempt string to double conversions. If that fails as well then the component framework will report a conflict, an evaluation exception. If the conversions from string to integer are successful then the result will be either the string 0 or the string 1, both of which can be converted to integers or doubles as required.

It is worth noting that the expression CYGNUM_UITRON_SEMAS >10 is not ambiguous. CDL identifiers can never begin with a digit, so it is not possible for 10 to be misinterpreted as a reference to an identifier instead of as a string.

Of course the implementation is slightly different again. The CDL language definition is such that all data is treated as if it were a string, with conversions to integer, double or boolean as and when required. The implementation is allowed to avoid conversions until they are necessary. For example, given CYGNUM_UITRON_SEMAS > 10 the expression parsing code will perform an immediate conversion from string to integer, storing the integer representation, and there is no need for a conversion by the comparison operator when the expression gets evaluated. Given { CYGNUM_UITRON_SEMAS > "10" } the parsing code will store the string representation and a conversion happens the first time the expression is evaluated. All of this is an implementation detail, and does not affect the semantics of the language.

Different operators have different requirements, for example the bitwise or operator only makes sense if both operands have an integer representation. For operators which can work with either integer or double precision numbers, integer arithmetic will be preferred.

The following operators only accept integer operands: unary ~ (bitwise not), the shift operators << and >>, and the bitwise operators &, | and ^.

The following operators will attempt integer arithmetic first, then double precision arithmetic: unary -, the arithmetic operators +, -, *, /, and %; and the comparision operators <, <=, > and >=.

The equality == and inequality != operators will first attempt integer conversion and comparison. If that fails then double precision will be attempted (although arguably using these operators on double precision data is not sensible). As a last resort string comparison will be used.

The operators !, && and || all work with boolean data. Any string that can be converted to the integer 0 or the double 0.0 is treated as false, as is the empty string or the constant string false. Anything else is interpreted as true. The result is either 0 or 1.

The conditional operator ? : will interpret its first operand as a boolean. It does not perform any processing on the second or third operands.

In practice it is rarely necessary to worry about any of these details. In nearly every case CDL expressions just work as expected, and there is no need to understand the full details.

Functions

CDL expressions can contain calls to a set of built-in functions using the usual syntax, for example;

    requires { !is_substr(CYGBLD_GLOBAL_CFLAGS, "-fno-rtti") }

The available function calls are as follows:

Goal Expressions

The arguments to certain properties, notably requires and active_if, constitute a goal expression. As with an ordinary expression, all of the arguments get combined and then the expression parser takes over. The same care has to be taken with constant strings and anything else that may get processed by the Tcl interpreter, so often a goal expression is enclosed entirely in braces and the expression parsing code sees just a single argument.

A goal expression is basically just a sequence of ordinary expressions, for example:

    requires { CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS
               !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT
               !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT }

This consists of three separate expressions, all of which should evaluate to a non-zero result. The same expression could be written as:

    requires { CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS  &&
               !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT &&
               !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT }

Alternatively the following would have much the same effect:

    requires CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS
    requires !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT
    requires !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT

Selecting between these alternatives is largely a stylistic choice. The first is slightly more concise than the others. The second is more likely to appeal to mathematical purists. The third is more amenable to cutting and pasting.

The result of evaluating a goal expression is a boolean. If any part of the goal expression evaluates to the integer 0 or an equivalent string then the result is false, otherwise it is true.

The term “goal expression” relates to the component framework's inference engine: it is a description of a goal that should be satisfied for a conflict-free configuration. If a requires constraint is not satisfied then the inference engine will examine the goal expression: if there is some way of changing the configuration that does not introduce new conflicts and that will cause the goal expression to evaluate to true, the conflict can be resolved.

The inference engine works with one conflict and hence one goal expression at a time. This means that there can be slightly different behavior if a constraint is specified using a single requires property or several different ones. Given the above example, suppose that none of the three conditions are satisfied. If a single goal expression is used then the inference engine might be able to satisfy only two of the three parts, but since the conflict as a whole cannot be resolved no part of the solution will be applied. Instead the user will have to resolve the entire conflict. If three separate goal expressions are used then the inference engine might well find solutions to two of them, leaving less work for the user. On the other hand, if a single goal expression is used then the inference engine has a bit more information to work with, and it might well find a solution to the entire conflict where it would be unable to find separate solutions for the three parts. Things can get very complicated, and in general component writers should not worry about the subtleties of the inference engine and how to manipulate its behavior.

It is possible to write ambiguous goal expressions, for example:

    requires CYGNUM_LIBC_RAND_SEED -CYGNUM_LIBC_RAND_TRACE_LEVEL > 5

This could be parsed in two ways:

    requires ((CYGNUM_LIBC_RAND_SEED - CYGNUM_LIBC_RAND_TRACE_LEVEL) > 5)
    requires CYGNUM_LIBC_RAND_SEED && ((-CYGNUM_LIBC_RAND_TRACE_LEVEL) > 5)

The goal expression parsing code will always use the largest ordinary expression for each goal, so the first interpretation will be used. In such cases it is a good idea to use brackets and avoid possible confusion.

List Expressions

The arguments to the legal_values property constitute a goal expression. As with an ordinary and goal expressions, all of the arguments get combined and then the expression parser takes over. The same care has to be taken with constant strings and anything else that may get processed by the Tcl interpreter, so often a list expression is enclosed entirely in braces and the expression parsing code sees just a single argument.

Most list expressions take one of two forms:

    legal_values <expr1> <expr2> <expr3> ...
    legal_values <expr1> to <expr2>

expr1, expr2 and so on are ordinary expressions. Often these will be constants or references to calculated options in the architectural HAL package, but it is possible to use arbitrary expressions when necessary. The first syntax indicates a list of possible values, which need not be numerical. The second syntax indicates a numerical range: both sides of the to must evaluate to a numerical value; if either side involves a floating point number then any floating point number in that range is legal; otherwise only integer values are legal; ranges are inclusive, so 4 is a valid value given a list expression 1 to ; if one or both sides of the to does not evaluate to a numerical value then this will result in a run-time conflict. The following examples illustrate these possibilities:

    legal_values { "red" "green" "blue" }
    legal_values 1 2 4 8 16
    legal_values 1 to CYGARC_MAXINT
    legal_values 1.0 to 2.0

It is possible to combine the two syntaxes, for example:

    legal_values 1 2 4 to CYGARC_MAXINT -1024 -20.0 to -10

This indicates three legal values 1, 2 and -1024, one integer range 4 to CYGARC_MAXINT, and one floating point range -20.0 to -10.0. In practice such list expressions are rarely useful.

The identifier to is not reserved, so it is possible to have a configuration option with that name (although it violates every naming convention). Using that option in a list expression may however give unexpected results.

The graphical configuration tool uses the legal_values list expression to determine how best to let users manipulate the option's value. Different widgets will be appropriate for different lists, so { "red" "green" "blue" } might involve a pull-down option menu, and 1 to 16 could involve a spinner. The exact way in which legal_values lists get mapped on to GUI widgets is not defined and is subject to change at any time.

As with goal expressions, list expressions can be ambiguous. Consider the following hypothetical example:

    legal_values CYGNUM_LIBC_RAND_SEED -CYGNUM_LIBC_RAND_TRACE_LEVEL

This could be parsed in two ways:

    legal_values (CYGNUM_LIBC_RAND_SEED - CYGNUM_LIBC_RAND_TRACE_LEVEL)
    legal_values (CYGNUM_LIBC_RAND_SEED) (-CYGNUM_LIBC_RAND_TRACE_LEVEL)

Both are legal. The list expression parsing code will always use the largest ordinary expression for each element, so the first interpretation will be used. In cases like this it is a good idea to use brackets and avoid possible confusion.