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:
resourceThis 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:
resourceThis 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:
resourceThis 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.