26.24. Directives¶

This section details the directives of the Application Configuration Information. A subsection is dedicated to each of this manager’s directives and lists the calling sequence, parameters, description, return values, and notes of the directive.

26.24.1. rtems_get_build_label()¶

Gets the RTEMS build label.

CALLING SEQUENCE:

const char *rtems_get_build_label( void );

DESCRIPTION:

The build label is a user-provided string defined by the build configuration through the RTEMS_BUILD_LABEL build option. The format of the string is completely user-defined.

RETURN VALUES:

Returns a pointer to the RTEMS build label.

NOTES:

The build label can be used to distinguish test suite results obtained from different build configurations. A use case is to record test results with performance data to track performance regressions. For this a database of performance limits is required. The build label and the target hash obtained from rtems_get_target_hash() can be used as a key to obtain performance limits.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.2. rtems_get_copyright_notice()¶

Gets the RTEMS copyright notice.

CALLING SEQUENCE:

const char *rtems_get_copyright_notice( void );

RETURN VALUES:

Returns a pointer to the RTEMS copyright notice.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.3. rtems_get_target_hash()¶

Gets the RTEMS target hash.

CALLING SEQUENCE:

const char *rtems_get_target_hash( void );

DESCRIPTION:

The target hash is calculated from BSP-specific values which characterize a target system. The target hash is encoded as a base64url string. The target hash algorithm is unspecified.

RETURN VALUES:

Returns a pointer to the RTEMS target hash.

NOTES:

For example, the device tree, settings of the memory controller, processor and bus frequencies, a serial number of a chip may be used to calculate the target hash.

The target hash can be used to distinguish test suite results obtained from different target systems. See also rtems_get_build_label().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.4. rtems_get_version_string()¶

Gets the RTEMS version string.

CALLING SEQUENCE:

const char *rtems_get_version_string( void );

RETURN VALUES:

Returns a pointer to the RTEMS version string.

NOTES:

The version string has no particular format. Parsing the string may break across RTEMS releases.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.5. rtems_configuration_get_do_zero_of_workspace()¶

Indicates if the RTEMS Workspace is configured to be zeroed during system initialization for this application.

CALLING SEQUENCE:

bool rtems_configuration_get_do_zero_of_workspace( void );

RETURN VALUES:

Returns true, if the RTEMS Workspace is configured to be zeroed during system initialization for this application, otherwise false.

NOTES:

The setting is defined by the CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.6. rtems_configuration_get_idle_task_stack_size()¶

Gets the IDLE task stack size in bytes of this application.

CALLING SEQUENCE:

size_t rtems_configuration_get_idle_task_stack_size( void );

RETURN VALUES:

Returns the IDLE task stack size in bytes of this application.

NOTES:

The IDLE task stack size is defined by the CONFIGURE_IDLE_TASK_STACK_SIZE application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.7. rtems_configuration_get_idle_task()¶

Gets the IDLE task body of this application.

CALLING SEQUENCE:

void *( * )( uintptr_t ) rtems_configuration_get_idle_task( void );

RETURN VALUES:

Returns the IDLE task body of this application.

NOTES:

The IDLE task body is defined by the CONFIGURE_IDLE_TASK_BODY application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.8. rtems_configuration_get_interrupt_stack_size()¶

Gets the interrupt stack size in bytes of this application.

CALLING SEQUENCE:

size_t rtems_configuration_get_interrupt_stack_size( void );

RETURN VALUES:

Returns the interrupt stack size in bytes of this application.

NOTES:

The interrupt stack size is defined by the CONFIGURE_INTERRUPT_STACK_SIZE application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.9. rtems_configuration_get_maximum_barriers()¶

Gets the resource number of Barrier Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_barriers( void );

RETURN VALUES:

Returns the resource number of Barrier Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_BARRIERS application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.10. rtems_configuration_get_maximum_extensions()¶

Gets the resource number of User Extensions Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_extensions( void );

RETURN VALUES:

Returns the resource number of User Extensions Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_USER_EXTENSIONS application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.11. rtems_configuration_get_maximum_message_queues()¶

Gets the resource number of Message Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_message_queues( void );

RETURN VALUES:

Returns the resource number of Message Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.12. rtems_configuration_get_maximum_partitions()¶

Gets the resource number of Partition Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_partitions( void );

RETURN VALUES:

Returns the resource number of Partition Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_PARTITIONS application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.13. rtems_configuration_get_maximum_periods()¶

Gets the resource number of Rate Monotonic Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_periods( void );

RETURN VALUES:

Returns the resource number of Rate Monotonic Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_PERIODS application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.14. rtems_configuration_get_maximum_ports()¶

Gets the resource number of Dual-Ported Memory Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_ports( void );

RETURN VALUES:

Returns the resource number of Dual-Ported Memory Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_PORTS application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.15. rtems_configuration_get_maximum_processors()¶

Gets the maximum number of processors configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_processors( void );

RETURN VALUES:

Returns the maximum number of processors configured for this application.

NOTES:

The actual number of processors available to the application is returned by rtems_scheduler_get_processor_maximum() which less than or equal to the configured maximum number of processors (CONFIGURE_MAXIMUM_PROCESSORS).

In uniprocessor configurations, this macro is a compile time constant which evaluates to one.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.16. rtems_configuration_get_maximum_regions()¶

Gets the resource number of Region Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_regions( void );

RETURN VALUES:

Returns the resource number of Region Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_REGIONS application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.17. rtems_configuration_get_maximum_semaphores()¶

Gets the resource number of Semaphore Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_semaphores( void );

RETURN VALUES:

Returns the resource number of Semaphore Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_SEMAPHORES application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.18. rtems_configuration_get_maximum_tasks()¶

Gets the resource number of Task Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_tasks( void );

RETURN VALUES:

Returns the resource number of Task Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_TASKS application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.19. rtems_configuration_get_maximum_timers()¶

Gets the resource number of Timer Manager objects configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_maximum_timers( void );

RETURN VALUES:

Returns the resource number of Timer Manager objects configured for this application.

NOTES:

The resource number is defined by the CONFIGURE_MAXIMUM_TIMERS application configuration option. See also rtems_resource_is_unlimited() and rtems_resource_maximum_per_allocation().

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.20. rtems_configuration_get_microseconds_per_tick()¶

Gets the number of microseconds per clock tick configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_microseconds_per_tick( void );

RETURN VALUES:

Returns the number of microseconds per clock tick configured for this application.

NOTES:

The number of microseconds per clock tick is defined by the CONFIGURE_MICROSECONDS_PER_TICK application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.21. rtems_configuration_get_milliseconds_per_tick()¶

Gets the number of milliseconds per clock tick configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_milliseconds_per_tick( void );

RETURN VALUES:

Returns the number of milliseconds per clock tick configured for this application.

NOTES:

The number of milliseconds per clock tick is defined by the CONFIGURE_MICROSECONDS_PER_TICK application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.22. rtems_configuration_get_nanoseconds_per_tick()¶

Gets the number of microseconds per clock tick configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_nanoseconds_per_tick( void );

RETURN VALUES:

Returns the number of microseconds per clock tick configured for this application.

NOTES:

The number of nanoseconds per clock tick is defined by the CONFIGURE_MICROSECONDS_PER_TICK application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.23. rtems_configuration_get_number_of_initial_extensions()¶

Gets the number of initial extensions configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_number_of_initial_extensions( void );

RETURN VALUES:

Returns the number of initial extensions configured for this application.

NOTES:

The number of initial extensions is defined by the CONFIGURE_INITIAL_EXTENSIONS application configuration option and related options.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.24. rtems_configuration_get_stack_allocate_for_idle_hook()¶

Gets the task stack allocator allocate hook used to allocate the stack of each IDLE task configured for this application.

CALLING SEQUENCE:

void *( * )( uint32_t, size_t * )
rtems_configuration_get_stack_allocate_for_idle_hook( void );

RETURN VALUES:

Returns the task stack allocator allocate hook used to allocate the stack of each IDLE task configured for this application.

NOTES:

The task stack allocator allocate hook for idle tasks is defined by the CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.25. rtems_configuration_get_stack_allocate_hook()¶

Gets the task stack allocator allocate hook configured for this application.

CALLING SEQUENCE:

void *( * )( size_t ) rtems_configuration_get_stack_allocate_hook( void );

RETURN VALUES:

Returns the task stack allocator allocate hook configured for this application.

NOTES:

The task stack allocator allocate hook is defined by the CONFIGURE_TASK_STACK_ALLOCATOR application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.26. rtems_configuration_get_stack_allocate_init_hook()¶

Gets the task stack allocator initialization hook configured for this application.

CALLING SEQUENCE:

void ( * )( size_t ) rtems_configuration_get_stack_allocate_init_hook( void );

RETURN VALUES:

Returns the task stack allocator initialization hook configured for this application.

NOTES:

The task stack allocator initialization hook is defined by the CONFIGURE_TASK_STACK_ALLOCATOR_INIT application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.27. rtems_configuration_get_stack_allocator_avoids_work_space()¶

Indicates if the task stack allocator is configured to avoid the RTEMS Workspace for this application.

CALLING SEQUENCE:

bool rtems_configuration_get_stack_allocator_avoids_work_space( void );

RETURN VALUES:

Returns true, if the task stack allocator is configured to avoid the RTEMS Workspace for this application, otherwise false.

NOTES:

The setting is defined by the CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.28. rtems_configuration_get_stack_free_hook()¶

Gets the task stack allocator free hook configured for this application.

CALLING SEQUENCE:

void ( * )( void * ) rtems_configuration_get_stack_free_hook( void );

RETURN VALUES:

Returns the task stack allocator free hook configured for this application.

NOTES:

The task stack allocator free hook is defined by the CONFIGURE_TASK_STACK_DEALLOCATOR application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.29. rtems_configuration_get_stack_space_size()¶

Gets the configured size in bytes of the memory space used to allocate thread stacks for this application.

CALLING SEQUENCE:

uintptr_t rtems_configuration_get_stack_space_size( void );

RETURN VALUES:

Returns the configured size in bytes of the memory space used to allocate thread stacks for this application.

NOTES:

The size takes only threads and tasks into account with are known at the application configuration time.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.30. rtems_configuration_get_ticks_per_timeslice()¶

Gets the clock ticks per timeslice configured for this application.

CALLING SEQUENCE:

uint32_t rtems_configuration_get_ticks_per_timeslice( void );

RETURN VALUES:

Returns the clock ticks per timeslice configured for this application.

NOTES:

The clock ticks per timeslice is defined by the CONFIGURE_TICKS_PER_TIMESLICE application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.31. rtems_configuration_get_unified_work_area()¶

Indicates if the RTEMS Workspace and C Program Heap are configured to be unified for this application.

CALLING SEQUENCE:

bool rtems_configuration_get_unified_work_area( void );

RETURN VALUES:

Returns true, if the RTEMS Workspace and C Program Heap are configured to be unified for this application, otherwise false.

NOTES:

The setting is defined by the CONFIGURE_UNIFIED_WORK_AREAS application configuration option.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.32. rtems_configuration_get_user_extension_table()¶

Gets the initial extensions table configured for this application.

CALLING SEQUENCE:

const rtems_extensions_table *rtems_configuration_get_user_extension_table(
  void
);

RETURN VALUES:

Returns a pointer to the initial extensions table configured for this application.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.33. rtems_configuration_get_user_multiprocessing_table()¶

Gets the MPCI configuration table configured for this application.

CALLING SEQUENCE:

const MPCI_Configuration *rtems_configuration_get_user_multiprocessing_table(
  void
);

RETURN VALUES:

Returns a pointer to the MPCI configuration table configured for this application.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.34. rtems_configuration_get_work_space_size()¶

Gets the RTEMS Workspace size in bytes configured for this application.

CALLING SEQUENCE:

uintptr_t rtems_configuration_get_work_space_size( void );

RETURN VALUES:

Returns the RTEMS Workspace size in bytes configured for this application.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.35. rtems_configuration_get_rtems_api_configuration()¶

Gets the Classic API Configuration Table of this application.

CALLING SEQUENCE:

const rtems_api_configuration_table *
rtems_configuration_get_rtems_api_configuration( void );

RETURN VALUES:

Returns a pointer to the Classic API Configuration Table of this application.

CONSTRAINTS:

The following constraints apply to this directive:

The directive may be called from within any runtime context.
The directive will not cause the calling task to be preempted.

26.24.36. rtems_resource_is_unlimited()¶

Indicates if the resource is unlimited.

CALLING SEQUENCE:

bool rtems_resource_is_unlimited( uint32_t resource );

PARAMETERS:

resource: This parameter is the resource number.

RETURN VALUES:

Returns true, if the resource is unlimited, otherwise false.

CONSTRAINTS:

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

26.24.37. rtems_resource_maximum_per_allocation()¶

Gets the maximum number per allocation of a resource number.

CALLING SEQUENCE:

uint32_t rtems_resource_maximum_per_allocation( uint32_t resource );

PARAMETERS:

resource: This parameter is the resource number.

RETURN VALUES:

Returns the maximum number per allocation of a resource number.

CONSTRAINTS:

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.

26.24.38. rtems_resource_unlimited()¶

Augments the resource number so that it indicates an unlimited resource.

CALLING SEQUENCE:

uint32_t rtems_resource_unlimited( uint32_t resource );

PARAMETERS:

resource: This parameter is the resource number to augment.

RETURN VALUES:

Returns the resource number augmented to indicate an unlimited resource.

NOTES:

This directive should be used to configure unlimited objects, see Unlimited Objects.

CONSTRAINTS:

The following constraints apply to this directive:

The directive is implemented by a macro and may be called from within C/C++ constant expressions. In addition, a function implementation of the directive exists for bindings to other programming languages.
The directive will not cause the calling task to be preempted.