CDL Properties

Information-providing Properties

Users can only be expected to manipulate configuration options sensibly if they are given sufficient information about these options. There are three properties which serve to explain an option in plain text: the display property gives a textual alias for an option, which is usually more comprehensible than something like CYGPKG_LIBC_TIME_ZONES`; the description property gives a longer description, typically a paragraph or so; the doc property specifies the location of additional on-line documentation related to a configuration option. In the context of a graphical tool the display string will be the primary way for users to identify configuration options; the description paragraph will be visible whenever the option is selected; the on-line documentation will only be accessed when the user explicitly requests it.

cdl_package CYGPKG_UITRON {
    display       "uITRON compatibility layer"
    doc           ref/ecos-ref.a.html
    description   "
        eCos supports a uITRON Compatibility Layer, providing
        full Level S (Standard) compliance with Version 3.02 of
        the uITRON Standard, plus many Level E (Extended) features.
        uITRON is the premier Japanese embedded RTOS standard."
    …
}

All three properties take a single argument. For display and description this argument is just a string. For doc it should be a pointer to a suitable HTML file, optionally including an anchor within that page. If the directory layout conventions are observed then the component framework will look for the HTML file in the package's doc sub-directory, otherwise the doc filename will be treated as relative to the package's top-level directory.

The Configuration Hierarchy

There are two properties related to the hierarchical organization of components and options: parent and script.

The parent property can be used to move a CDL entity somewhere else in the hierarchy. The most common use is for packages, to avoid having all the packages appear at the top-level of the configuration hierarchy. For example an architectural HAL package such as CYGPKG_HAL_SH is placed below the common HAL package CYGPKG_HAL using a parent property.

cdl_package CYGPKG_HAL_SH {
    display       "SH architecture"
    parent        CYGPKG_HAL
    …
}

The parent property can also be used in the body of a cdl_component, cdl_option or cdl_interface, but this is less common. However care has to be taken since excessive re-parenting can be confusing. Care also has to be taken when reparenting below some other package that may not actually be loaded in a given configuration, since the resulting behavior is undefined.

As a special case, if the parent is the empty string then the CDL entity is placed at the root of the hierarchy. This is useful for global preferences, default compiler flags, and other settings that may affect every package.

The script property can only be used in the body of a cdl_component command. The property takes a single filename as argument, and this should be another CDL script containing additional options, sub-components and interfaces that should go below the current component in the hierarchy. If the directory layout conventions are observed then the component framework will look for the specified file relative to the cdl subdirectory of the package, otherwise the filename will be treated as relative to the package's top-level directory.

cdl_component CYGPKG_LIBC_STDIO {
    display       "Standard input/output functions"
    flavor        bool
    requires      CYGPKG_IO
    requires      CYGPKG_IO_SERIAL_HALDIAG
    default_value 1
    description   "
        This enables support for standard I/O functions from <stdio.h>."

    script        stdio.cdl
}

Value-related Properties

There are seven properties which are related to option values and state: flavor, calculated, default_value, legal_values, active_if, implements, and requires. More detailed information can be found in the Section called Values and Expressions.

In the context of configurability, the concept of an option's value is somewhat non-trivial. First an option may or may not be loaded: it is possible to build a configuration which has the math library but not the kernel; however the math library's CDL scripts still reference kernel options, for example CYGSEM_LIBM_THREAD_SAFE_COMPAT_MODE has a requires constraint on CYGVAR_KERNEL_THREADS_DATA. Even if an option is loaded it may or may not be active, depending on what is happening higher up in the hierarchy: if the C library's CYGPKG_LIBC_STDIO component is disabled then some other options such as CYGNUM_LIBC_STDIO_BUFSIZE become irrelevant. In addition each option has both a boolean enabled/disabled flag and a data part. For many options only the boolean flag is of interest, while for others only the data part is of interest. The flavor property can be used to control this:

For more details of CDL flavors and how a flavor affects expression evaluation, and other consequences, see the Section called Values and Expressions. The flavor property cannot be used for a package because packages always have the booldata flavor. Options and components have the bool flavor by default, since most configuration choices are simple yes-or-no choices. Interfaces have the data flavor by default.

The calculated property can be used for options which should not be user-modifiable, but which instead are fixed by the target hardware or determined from the current values of other options. In general calculated options should be avoided, since they can be confusing to users who need to figure out whether or not a particular option can actually be changed. There are a number of valid uses for calculated options, and quite a few invalid ones as well. The reference packages should be consulted for further details. The property takes an ordinary CDL expression as argument, for example:

# A constant on some target hardware, perhaps user-modifiable on other
# targets.
cdl_option CYGNUM_HAL_RTC_PERIOD {
    display       "Real-time clock period"
    flavor        data
    calculated    12500
}

The calculated property cannot be used for packages or interfaces. The value of a package always corresponds to the version of that package which is loaded, and this is under user control. Interfaces are implicitly calculated, based on the number of active and enabled implementors.

The default_value property is similar to calculated, but only specifies a default value which users can modify. Again this property is not relevant to packages or interfaces. A typical example would be:

cdl_option CYGDBG_HAL_DEBUG_GDB_THREAD_SUPPORT {
    display       "Include GDB multi-threading debug support"
    requires      CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
    default_value CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
    …
}

The legal_values property imposes a constraint on the possible values of the data part of an option. Hence it is only applicable to options with the data or booldata flavors. It cannot be used for a package since the only valid value for a package is its version number. The arguments to the legal_values property should constitute a CDL list expression.

cdl_option CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET {
    display       "Default Standard Time offset"
    flavor        data
    legal_values  -- -90000 to 90000
    default_value -- 0
    …
}

The active_if property does not relate directly to an option's value, but rather to its active state. Usually this is controlled via the configuration hierarchy: if the CYGPKG_LIBC_STDIO component is disabled then all options below it are inactive and do not have any consequences. In some cases the hierarchy does not provide sufficient control, for example an option should only be active if two disjoint sets of conditions are satisfied: the hierarchy could be used for one of these conditions, and an additional active_if property could be used for the other one. The arguments to active_if should constitute a CDL goal expression.

# Do not provide extra semaphore debugging if there are no semaphores
cdl_option CYGDBG_KERNEL_INSTRUMENT_BINSEM {
    active_if CYGPKG_KERNEL_SYNCH
    …
}

The implements property is related to the concept of CDL interfaces. If an option is active and enabled and it implements a particular interface then it contributes 1 to that interface's value.

cdl_package CYGPKG_NET_EDB7XXX_ETH_DRIVERS {
    display       "Cirrus Logic ethernet driver"
    implements    CYGHWR_NET_DRIVERS
    implements    CYGHWR_NET_DRIVER_ETH0
    …
}

The requires property is used to impose constraints on the user's choices. For example it is unreasonable to expect the C library to provide thread-safe implementations of certain functions if the underlying kernel support has been disabled, or even if the kernel is not being used at all.

cdl_option CYGSEM_LIBC_PER_THREAD_ERRNO {
    display       "Per-thread errno"
    doc           ref/ecos-ref.15.html
    requires      CYGVAR_KERNEL_THREADS_DATA
    default_value 1
    …
}

The arguments to the requires property should be a CDL goal expression.

Generating the Configuration Header Files

When creating or updating a build tree the component framework will also generate configuration header files, one per package. By default it will generate a #define for each option, component or interface that is active and enabled. For options with the data or booldata flavors the #define will use the option's data part, otherwise it will use the constant 1. Typical output would include:

#define CYGFUN_LIBC_TIME_POSIX 1
#define CYGNUM_LIBC_TIME_DST_DEFAULT_STATE -1

There are six properties which can be used to control the header file generation process: define_header, no_define, define_format, define, if_define, and define_proc.

By default the component framework will generate a configuration header file for each package based on the package's name: everything up to and including the first underscore is discarded, the rest of the name is lower-cased, and a .h suffix is appended. For example the configuration header file for the kernel package CYGPKG_KERNEL is pkgconf/kernel.h. The define_header property can be used to specify an alternative filename. This applies to all the components and options within a package, so it can only be used in the body of a cdl_package command. For example the following specifies that the configuration header file for the SPARClite HAL package is pkgconf/hal_sparclite.h.

cdl_package CYGPKG_HAL_SPARCLITE {
    display "SPARClite architecture"
    parent        CYGPKG_HAL
    hardware
    define_header hal_sparclite.h
    …
}

The no_define property is used to suppress the generation of the default #define. This can be useful if an option's consequences are all related to the build process or to constraints, and the option is never actually checked in any source code. It can also be useful in conjunction with the define, if_define or define_proc properties. The no_define property does not take any arguments.

cdl_component CYG_HAL_STARTUP {
    display       "Startup type"
    flavor        data
    legal_values  { "RAM" "ROM" }
    default_value {"RAM"}
    no_define
    define -file system.h CYG_HAL_STARTUP
    …
}

This example also illustrates the define property, which can be used to generate a #define in addition to the default one. It takes a single argument, the name of the symbol to be defined. It also takes options to control the configuration header file in which the symbol should be defined and the format to be used.

The define_format property can be used to control how the value part of the default #define gets formatted. For example a format string of "0x%04x" could be used to generate a four-digit hexadecimal number.

The if_define property is intended for use primarily to control assertions, tracing, and similar functionality. It supports a specific implementation model for these, allowing control at the grain of packages or even individual source files. The reference pages provide additional information.

The define_proc property provides an escape mechanism for those cases where something special has to happen at configuration header file generation time. It takes a single argument, a fragment of Tcl code, which gets executed when the header file is generated. This code can output arbitrary data to the header file, or perform any other actions that might be appropriate.

Controlling what gets Built

There are six properties which affect the build process: compile, make, make_object, library, include_dir, and include_files. The last three apply to a package as a whole, and can only occur in the body of a cdl_package command.

Most of the source files that go into a package should simply be compiled with the appropriate compiler, selected by the target architecture, and with the appropriate flags, with an additional set defined by the target hardware and possible modifications on a per-package basis. The resulting object files will go into the library libtarget.a, which can then be linked against application code. The compile property is used to list these source files:

cdl_package CYGPKG_ERROR {
    display       "Common error code support"
    compile       strerror.cxx
    include_dir   cyg/error
    …
}

The arguments to the compile property should be one or more source files. Typically most of the sources will be needed for the package as a whole, and hence they will be listed in one or more compile properties in the body of the cdl_package. Some sources may be specific to particular configuration options, in other words there is no point in compiling them unless that option is enabled, in which case the sources should be listed in a compile property in the corresponding cdl_option, cdl_component or cdl_interface body.

Some packages may have more complicated build requirements, for example they may involve a special target such as a linker script which should not end up in the usual library, or they may involve special build steps for generating an object file. The make and make_object properties provide support for such requirements, for example:

cdl_package CYGPKG_HAL_MN10300_AM33 {
    display       "MN10300 AM33 variant"
    …
    make {
        <PREFIX>/lib/target.ld: <PACKAGE>/src/mn10300_am33.ld
        $(CC) -E -P -Wp,-MD,target.tmp -DEXTRAS=1 -xc $(INCLUDE_PATH) \
            $(CFLAGS) -o $@ $<
        @echo $@ ": \\" > $(notdir $@).deps
        @tail +2 target.tmp >> $(notdir $@).deps
        @echo >> $(notdir $@).deps
        @rm target.tmp
    }
}

For full details of custom build steps and the build process generally, see Chapter 4.

By default all object files go into the library libtarget.a. It is possible to override this at the package level using the library property, but this should be avoided since it complicates application development: instead of just linking with a single library for all eCos-related packages, it suddenly becomes necessary to link with several libraries.

The include_dir and include_files properties relate to a package's exported header files. By default a package's header files will be exported to the install/include directory. This is the desired behavior for some packages like the C library, since headers like stdio.h should exist at that level. However if all header files were to end up in that directory then there would be a significant risk of a name clash. Instead it is better for packages to specify some sub-directory for their exported header files, for example:

cdl_package CYGPKG_INFRA {
    display       "Infrastructure"
    include_dir   cyg/infra
    …
}

The various header files exported by the infrastructure, for example cyg_ass.h and cyg_trac.h will now end up in the install/include/cyg/infra sub-directory, where a name clash is very unlikely.

For packages which follow the directory layout conventions the component framework will assume that the package's include sub-directory contains all exported header files. If this is not the case, for example because the package is sufficiently simple that the layout convention is inappropriate, then the exported header files can be listed explicitly in an include_files property.

Miscellaneous Properties

The hardware property is only relevant to packages. Some packages such as device drivers and HAL packages are hardware-specific, and generally it makes no sense to add such packages to a configuration unless the corresponding hardware is present on your target system. Typically hardware package selection happens automatically when you select your target. The hardware property should be used to identify a hardware-specific package, and does not take any arguments.

cdl_package CYGPKG_HAL_MIPS {
    display "MIPS architecture"
    parent        CYGPKG_HAL
    hardware
    include_dir   cyg/hal
    define_header hal_mips.h
    …
}

At present the hardware property is largely ignored by the component framework. This may change in future releases.