The eCos Component Writer's Guide
Prev |  | Next

# legal_values

## Name

Property legal_values -- Impose constraints on the possible values for an option.

## Synopsis

    cdl_option <name> {
        legal_values <list expression>
        …
    }

## Description

Options with the `data` or `booldata` flavors can have an arbitrary sequence of characters as their data. In nearly all cases some restrictions have to be imposed, for example the data should correspond to a number within a certain range, or it should be one of a small number of constants. The legal_values property can be used to impose such constraints. The arguments to the property should be a CDL list expression, see the Section called List Expressions in Chapter 3 for the syntactic details. Common examples include:

        legal_values 0 to 0x7fff
        legal_values 9600 19200 38400
        legal_values { "RAM" "ROM" }

The legal_values property can only be used for options with the `data` or `booldata` flavors, since it makes little sense to further constrain the legal values of a boolean option. An option can have at most one legal_values property.

> Tip: If the first entry in a legal_values list expression is a negative number, for example `legal_values -1 to 1` then this can be misinterpreted as an option instead of as part of the expression. Currently the legal_values property does not take any options, but this may change in future. Option processing halts at the sequence `--`, so the desired range can be expressed safely using `legal_values -- -1 to 1`

> Note: Architectural HAL packages should provide constants which can be used in legal_values list expressions. For example it should be possible to specify a numeric range such as `0 to CYGARC_MAXINT`, rather than hard-wiring numbers such as `0x7fffffff` which may not be valid on all targets. Current HAL packages do not define such constants.

> Note: The legal_values property is restricted mainly to numerical ranges and simple enumerations, and cannot cope with more complicated data items. Future versions of the configuration system will provide additional data validation facilities, for example a `check_proc` property which specifies a Tcl script that can be used to perform the validation.

## Example

    cdl_option CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET {
        display       "Default Standard Time offset"
        flavor        data
        legal_values  -- -90000 to 90000
        default_value -- 0
        description   "
            This option controls the offset from UTC in
            seconds when in local Standard Time. This
            value can be positive or negative. It
            can also be set at run time using the
            cyg_libc_time_setzoneoffsets() function."
    }

## See Also

Properties calculated, default_value, and flavor.

Prev | Home | Next
include_files | Up | library