RTEMS 4.9.2 On-Line Library

Configuring a System Configuration Table

RTEMS C User's Guide

23.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 C structure:

typedef struct {
  void                           *work_space_start;
  uint32_t                        work_space_size;
  uint32_t                        maximum_extensions;
  uint32_t                        microseconds_per_tick;
  uint32_t                        ticks_per_timeslice;
  void                          (*idle_task)( void );
  uint32_t                        idle_task_stack_size;
  uint32_t                        interrupt_stack_size;
  void *                        (*stack_allocate_hook)( uint32_t );
  void                          (*stack_free_hook)( void * );
  bool                            do_zero_of_workspace;
  uint32_t                        maximum_drivers;
  uint32_t                        number_of_device_drivers;
  rtems_driver_address_table     *Device_driver_table;
  uint32_t                        number_of_initial_extensions;
  rtems_extensions_table         *User_extension_table;
#if defined(RTEMS_MULTIPROCESSING)
  rtems_multiprocessing_table    *User_multiprocessing_table;
#endif
  rtems_api_configuration_table  *RTEMS_api_configuration;
  posix_api_configuration_table  *POSIX_api_configuration;
  itron_api_configuration        *ITRON_api_configuration;
} rtems_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 rtems/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 rtems/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 rtems/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 rtems/confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_TICKS_PER_TIMESLICE.

idle_task

is the address of the optional user provided routine which is used as the system's IDLE task. If this field is not NULL, then the RTEMS default IDLE task is not used. This field may be NULL to indicate that the default IDLE is to be used. When using the rtems/confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_IDLE_TASK_BODY.

idle_task_stack_size

is the size of the RTEMS idle task stack in bytes. If this number is less than the configured minimum stack size, then the idle task's stack will be set to the minimum. When using the rtems/confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_IDLE_TASK_STACK_SIZE.

interrupt_stack_size

is the size of the RTEMS interrupt stack in bytes. If this number is less than configured minimum stack size, then the interrupt stack will be set to the minimum. When using the rtems/confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_INTERRUPT_STACK_SIZE.

stack_allocate_hook

may point to a user provided routine to allocate task stacks. The default is to allocate task stacks from the RTEMS Workspace. When using the rtems/confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_TASK_STACK_ALLOCATOR.

stack_free_hook

may point to a user provided routine to free task stacks. The default is to allocate task stacks from the RTEMS Workspace. When using the rtems/confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_TASK_STACK_DEALLOCATOR.

do_zero_of_workspace

indicates whether RTEMS should zero the RTEMS Workspace and C Program Heap as part of its initialization. If set to TRUE, the Workspace is zeroed. Otherwise, it is not. When using the rtems/confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY.

maximum_drivers

is the maximum number of device drivers that can be registered. When using the rtems/confdefs.h mechanism for configuring an RTEMS application, the value for this field corresponds to the setting of the macro CONFIGURE_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 rtems/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 rtems/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 rtems/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 rtems/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 rtems/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 rtems/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 rtems/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 rtems/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 rtems/confdefs.h application configuration mechanism. The rtems/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 C User's Guide