RTEMS 4.8.0 On-Line Library

Configuring a System Sizing the RTEMS RAM Workspace

RTEMS C User's Guide

23.13: Sizing the RTEMS RAM Workspace

The RTEMS RAM Workspace is a user-specified block of memory reserved for use by RTEMS. The application should NOT modify this memory. This area consists primarily of the RTEMS data structures whose exact size depends upon the values specified in the Configuration Table. In addition, task stacks and floating point context areas are dynamically allocated from the RTEMS RAM Workspace.

The rtems/confdefs.h mechanism calcalutes the size of the RTEMS RAM Workspace automatically. It assumes that all tasks are floating point and that all will be allocated the miminum stack space. This calculation also automatically includes the memory that will be allocated for internal use by RTEMS. The following macros may be set by the application to make the calculation of memory required more accurate:

CONFIGURE_MEMORY_OVERHEAD
CONFIGURE_EXTRA_TASK_STACKS

The starting address of the RTEMS RAM Workspace must be aligned on a four-byte boundary. Failure to properly align the workspace area will result in the rtems_fatal_error_occurred directive being invoked with the RTEMS_INVALID_ADDRESS error code.

A worksheet is provided in the Memory Requirements chapter of the Applications Supplement document for a specific target processor to assist the user in calculating the minimum size of the RTEMS RAM Workspace for each application. The value calculated with this worksheet is the minimum value that should be specified as the work_space_size parameter of the Configuration Table.

The allocation of objects can operate in two modes. The default mode has an object number ceiling. No more than the specified number of objects can be allocated from the RTEMS RAM Workspace. The number of objects specified in the particular API Configuration table fields are allocated at initialisation. The second mode allows the number of objects to grow to use the available free memory in the RTEMS RAM Workspace.

The auto-extending mode can be enabled individually for each object type by using the macro rtems_resource_unlimited. This takes a value as a parameter, and is used to set the object maximum number field in an API Configuration table. The value is an allocation unit size. When RTEMS is required to grow the object table it is grown by this size. The kernel will return the object memory back to the RTEMS RAM Workspace when an object is destroyed. The kernel will only return an allocated block of objects to the RTEMS RAM Workspace if at least half the allocation size of free objects remain allocated. RTEMS always keeps one allocation block of objects allocated. Here is an example of using rtems_resource_unlimited:

#define CONFIGURE_MAXIMUM_TASKS rtems_resource_unlimited(5)

The user is cautioned that future versions of RTEMS may not have the same memory requirements per object. Although the value calculated is suficient for a particular target processor and release of RTEMS, memory usage is subject to change across versions and target processors. The user is advised to allocate somewhat more memory than the worksheet recommends to insure compatibility with future releases for a specific target processor and other target processors. To avoid problems, the user should recalculate the memory requirements each time one of the following events occurs:

a configuration parameter is modified,
task or interrupt stack requirements change,
task floating point attribute is altered,
RTEMS is upgraded, or
the target processor is changed.

Failure to provide enough space in the RTEMS RAM Workspace will result in the rtems_fatal_error_occurred directive being invoked with the appropriate error code.

RTEMS C User's Guide