RTEMS 4.6.2 On-Line Library

Configuring a System Configuration Table

RTEMS Ada User's Guide

22.3: Configuration Table

The RTEMS Configuration Table is used to tailor an application for its specific needs. For example, the user can configure the number of device drivers or which APIs may be used. THe address of the user-defined Configuration Table is passed as an argument to the rtems.initialize_executive directive, which MUST be the first RTEMS directive called. The RTEMS Configuration Table is defined in the following Ada record:

type Configuration_Table is
   record
       Work_Space_Start             : RTEMS.Address;
       Work_Space_Size              : RTEMS.Unsigned32;
       Maximum_Extensions           : RTEMS.Unsigned32;
       Microseconds_Per_Tick        : RTEMS.Unsigned32;
       Ticks_Per_Timeslice          : RTEMS.Unsigned32;
       Maximum_Devices              : RTEMS.Unsigned32;
       Number_Of_Device_Drivers     : RTEMS.Unsigned32;
       Device_Driver_Table          :
            RTEMS.Driver_Address_Table_Pointer;
       Number_Of_Initial_Extensions : RTEMS.Unsigned32;
       User_Extension_Table         : RTEMS.Extensions_Table_Pointer;
       User_Multiprocessing_Table   :
            RTEMS.Multiprocessing_Table_Pointer;
       RTEMS_API_Configuration      :
            RTEMS.API_Configuration_Table_Pointer;
       POSIX_API_Configuration      :
            RTEMS.POSIX_API_Configuration_Table_Pointer;
   end record;

type Configuration_Table_Pointer is access all Configuration_Table;

work_space_start

is the address of the RTEMS RAM Workspace. This area contains items such as the various object control blocks (TCBs, QCBs, ...) and task stacks. If the address is not aligned on a four-word boundary, then RTEMS will invoke the fatal error handler during rtems.initialize_executive. When using the confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_EXECUTIVE_RAM_WORK_AREA which defaults to NULL. Normally, this field should be configured as NULL as BSPs will assign memory for the RTEMS RAM Workspace as part of system initialization.

work_space_size

is the calculated size of the RTEMS RAM Workspace. The section Sizing the RTEMS RAM Workspace details how to arrive at this number. When using the confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_EXECUTIVE_RAM_SIZE and is calculated based on the other system configuration settings.

microseconds_per_tick

is number of microseconds per clock tick. When using the confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_MICROSECONDS_PER_TICK. If not defined by the application, then the CONFIGURE_MICROSECONDS_PER_TICK macro defaults to 10000 (10 milliseconds).

ticks_per_timeslice

is the number of clock ticks for a timeslice. When using the confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_TICKS_PER_TIMESLICE.

maximum_devices

is the maximum number of devices that can be registered. When using the confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_MAXIMUM_DEVICES.

maximum_drivers

is the maximum number of device drivers that can be registered. When using the confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_MAXIMUM_DRIVERS. This value is set to maximum_devices if it is greater than maximum_drivers.

number_of_device_drivers

is the number of device drivers for the system. There should be the same number of entries in the Device Driver Table. If this field is zero, then the User_driver_address_table entry should be NULL. When using the confdefs.h mechanism for configuring an RTEMS application, the value for this field is calculated automatically based on the number of entries in the Device Driver Table. This calculation is based on the assumption that the Device Driver Table is named Device_drivers and defined in C. This table may be generated automatically for simple applications using only the device drivers that correspond to the following macros:

CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
CONFIGURE_APPLICATION_NEEDS_TIMER_DRIVER
CONFIGURE_APPLICATION_NEEDS_RTC_DRIVER
CONFIGURE_APPLICATION_NEEDS_STUB_DRIVER

Note that network device drivers are not configured in the Device Driver Table.

Device_driver_table

is the address of the Device Driver Table. This table contains the entry points for each device driver. If the number_of_device_drivers field is zero, then this entry should be NULL. The format of this table will be discussed below. When using the confdefs.h mechanism for configuring an RTEMS application, the Device Driver Table is assumed to be named Device_drivers and defined in C. If the application is providing its own Device Driver Table, then the macro CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE must be defined to indicate this and prevent confdefs.h from generating the table.

number_of_initial_extensions

is the number of initial user extensions. There should be the same number of entries as in the User_extension_table. If this field is zero, then the User_driver_address_table entry should be NULL. When using the confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_NUMBER_OF_INITIAL_EXTENSIONS which is set automatically by confdefs.h based on the size of the User Extensions Table.

User_extension_table

is the address of the User Extension Table. This table contains the entry points for the static set of optional user extensions. If no user extensions are configured, then this entry should be NULL. The format of this table will be discussed below. When using the confdefs.h mechanism for configuring an RTEMS application, the User Extensions Table is named Configuration_Initial_Extensions and defined in confdefs.h. It is initialized based on the following macros:

CONFIGURE_INITIAL_EXTENSIONS
STACK_CHECKER_EXTENSION

The application may configure one or more initial user extension sets by setting the CONFIGURE_INITIAL_EXTENSIONS macro. By defining the STACK_CHECKER_EXTENSION macro, the task stack bounds checking user extension set is automatically included in the application.

User_multiprocessing_table

is the address of the Multiprocessor Configuration Table. This table contains information needed by RTEMS only when used in a multiprocessor configuration. This field must be NULL when RTEMS is used in a single processor configuration. When using the confdefs.h mechanism for configuring an RTEMS application, the Multiprocessor Configuration Table is automatically generated when the CONFIGURE_MP_APPLICATION is defined. If CONFIGURE_MP_APPLICATION is not defined, the this entry is set to NULL. The generated table has the name Multiprocessing_configuration.

RTEMS_api_configuration

is the address of the RTEMS API Configuration Table. This table contains information needed by the RTEMS API. This field should be NULL if the RTEMS API is not used. [NOTE: Currently the RTEMS API is required to support support components such as BSPs and libraries which use this API.] This table is built automatically and this entry filled in, if using the confdefs.h application configuration mechanism. The generated table has the name Configuration_RTEMS_API.

POSIX_api_configuration

is the address of the POSIX API Configuration Table. This table contains information needed by the POSIX API. This field should be NULL if the POSIX API is not used. This table is built automatically and this entry filled in, if using the confdefs.h application configuration mechanism. The confdefs.h application mechanism will fill this field in with the address of the Configuration_POSIX_API table of POSIX API is configured and NULL if the POSIX API is not configured.

RTEMS Ada User's Guide