eCosTM User’s Guide
Prev | Chapter 7. Manual configuration | Next

# Fine-grained Configuration

pkgconf.tcl only provides coarse-grained control over the configuration: the target hardware, the packages that should be built, and the desired start-up. Unlike the Configuration Tool, pkgconf.tcl does not provide any facilities for manipulating finer-grained configuration options such as how many priority levels the scheduler should support. There are hundreds of these options, and manipulating them by means of command line arguments would not be sensible.

In the current system the only effect a configuration option can have is to produce either a #define or a #undef in a C header file. System code written in C or C++ can #include the header file, and use the conventional C preprocessor conditionals #ifdef, #ifndef, and #if defined() to adapt to the settings in the current configuration. In future releases, a configuration option will be able to have other effects, such as controlling which files in a given package will actually get compiled. There will also be support for configuring languages other than C or C++, where the use of #define statements in a header file would be inappropriate.

The install tree generated by pkgconf.tcl contains a pkgconf subdirectory (`install/include/pkgconf`). You should not edit the files in this directory, because they are installed as part of the build process and any changes you make to these files will get overwritten during the next build.

The build tree generated by pkgconf.tcl also contains a `pkgconf` subdirectory, which contains a header file for every package that is part of the current configuration. Fine-grained configuration using command-line tools involves editing these header files using a suitable editor.

The build tree"s `pkgconf` directory contains a number of files that should not be edited: `makefile`, `pkgconf.mak` and `system.h`. These files are generated by pkgconf.tcl, and any changes made to these will be overwritten the next time that you invoke pkgconf.tcl. One file you can edit is `makevars`, which contains settings for the build process. This file is described in the next section.

A typical extract from a configuration header file, in this case `kernel.h`, would be:

    #define CYGSEM_KERNEL_SCHED_MLQUEUE
    #undef CYGSEM_KERNEL_SCHED_BITMAP
    #define CYGNUM_KERNEL_SCHED_PRIORITIES 32
    #define CYGSEM_KERNEL_SCHED_TIMESLICE
    #define CYGNUM_KERNEL_SCHED_TIMESLICE_TICKS 5

Each #define or #undef corresponds to a single configuration option. Three of the options shown above are boolean in nature: the option may be enabled, which means that there is a #define for the corresponding symbol but no value; or the option may be disabled, in which case there is a #undef for the symbol instead. The multilevel queue scheduler is enabled, which means that the bitmap scheduler has to be disabled because there can be only one scheduler in the system. Timeslicing is enabled.

The other two options are numerical in nature. There will always be a #define for the corresponding preprocessor symbols, and this #define will involve a value.

The header file contains additional information that may assist you while editing fine-grained configuration. For example, immediately above this block of #define directives the header file contains the following information:

     cdl_option CYGNUM_KERNEL_SCHED_TIMESLICE_TICKS {
     display "Number of clock ticks between timeslices"
     parent CYGPKG_KERNEL_SCHED
     type count
     legal_values 1 to 65535
     description "
     Assuming timeslicing is enabled, how frequently should it
     take place? The value of this option corresponds to the
     number of clock ticks that should occur before a timeslice
     takes place, so increasing the value reduces the frequency
     of timeslices."
     }

This information is part of a large comment block. It is, in fact, the information that is used by the Configuration Tool and allows it to provide a sensible user interface for all the options. The entity `CYGNUM_KERNEL_SCHED_TIMESLICE_TICKS` is described as an option, rather than as a larger entity such as a component or an entire package. There is a short textual description of the option. Its position within the overall option hierarchy is clearly identified. The type of the option is given as “count”, which means that it can only have numerical values. Bounds are placed on the value of the option: the lower bound of 1 means that a timeslice would occur for every single clock interrupt, which would mean 100 times per second if the default clock settings are used. The upper bound would result in a timeslice approximately every 11 minutes, which is unlikely to be useful for most applications. The information provided with the option also includes a fairly detailed description.

A very important property (but not present in this example) is the “requires” property. The option `CYGSEM_KERNEL_SCHED_TIMESLICE` contains the line “requires CYGVAR_KERNEL_COUNTERS_CLOCK”, which means that it is only possible to enable timeslicing if the kernel clock is enabled. This information is very useful when manipulating the timeslice option. However, the configuration data for `CYGVAR_KERNEL_COUNTERS_CLOCK` does not indicate that it is required by `CYGSEM_KERNEL_SCHED_TIMESLICE`. Programs such as the Configuration Tool can determine this very easily using the information provided, but it is a bit more difficult for users. Standard utilities such as `grep` will prove useful.

It should be noted that the configuration data currently present in the header files is there to support the current Configuration Tool. The location, syntax, and contents of the configuration data is likely to change significantly in future releases.

All the configuration options and their descriptions are listed in the eCos Reference Manual.

Prev | Home | Next
Coarse-grained configuration | Up | Make flags