From cc43dc3e22b21ddf902b7748fb27f16c9aee3719 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 4 Oct 2022 10:44:10 +0200 Subject: rtems: Clarify application config info API Update #3993. --- cpukit/include/rtems/config.h | 630 ++++++++++++++++++++++++++---------- cpukit/include/rtems/rtems/config.h | 216 +++++++++---- 2 files changed, 625 insertions(+), 221 deletions(-) (limited to 'cpukit/include') diff --git a/cpukit/include/rtems/config.h b/cpukit/include/rtems/config.h index 6fc0924f4f..3d51fd6b5d 100644 --- a/cpukit/include/rtems/config.h +++ b/cpukit/include/rtems/config.h @@ -10,8 +10,8 @@ */ /* - * Copyright (C) 2021 On-Line Applications Research Corporation (OAR) * Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -91,10 +91,146 @@ extern "C" { * @brief The application configuration information group provides an API to * get the configuration of an application. * - * Some interfaces of this API are also used to define application - * configuration option values, for example rtems_resource_unlimited(). + * RTEMS must be configured for an application. This configuration encompasses + * a variety of information including the length of each clock tick, the + * maximum number of each information RTEMS object that can be created, the + * application initialization tasks, the task scheduling algorithm to be used, + * and the device drivers in the application. + * + * Although this information is contained in data structures that are used by + * RTEMS at system initialization time, the data structures themselves must not + * be generated by hand. RTEMS provides a set of macros system which provides a + * simple standard mechanism to automate the generation of these structures. + * + * The RTEMS header file ```` is at the core of the automatic + * generation of system configuration. It is based on the idea of setting + * macros which define configuration parameters of interest to the application + * and defaulting or calculating all others. This variety of macros can + * automatically produce all of the configuration data required for an RTEMS + * application. The term ``confdefs`` is shorthand for a *Configuration + * Defaults*. + * + * As a general rule, application developers only specify values for the + * configuration parameters of interest to them. They define what resources or + * features they require. In most cases, when a parameter is not specified, it + * defaults to zero (0) instances, a standards compliant value, or disabled as + * appropriate. For example, by default there will be 256 task priority levels + * but this can be lowered by the application. This number of priority levels + * is required to be compliant with the RTEID/ORKID standards upon which the + * Classic API is based. There are similar cases where the default is selected + * to be compliant with the POSIX standard. + * + * For each configuration parameter in the configuration tables, the macro + * corresponding to that field is discussed. The RTEMS Maintainers expect that + * all systems can be easily configured using the ```` + * mechanism and that using this mechanism will avoid internal RTEMS + * configuration changes impacting applications. + * + * Some application configuration settings and other system parameters can be + * queried by the application. */ +/* Generated from spec:/rtems/config/if/unlimited-objects */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief This flag is used in augment a resource number so that it indicates + * an unlimited resource. + */ +#define RTEMS_UNLIMITED_OBJECTS OBJECTS_UNLIMITED_OBJECTS + +/* Generated from spec:/rtems/config/if/get-stack-allocator-avoids-work-space */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief Indicates if the task stack allocator is configured to avoid the + * RTEMS Workspace for this application. + * + * @return Returns true, if the task stack allocator is configured to avoid the + * RTEMS Workspace for this application, otherwise false. + * + * @par Notes + * The setting is defined by the + * #CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE application configuration + * option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock + */ +#define rtems_configuration_get_stack_allocator_avoids_work_space() \ + _Stack_Allocator_avoids_workspace + +/* Generated from spec:/rtems/config/if/get-stack-space-size */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief Gets the configured size in bytes of the memory space used to + * allocate thread stacks for this application. + * + * @return Returns the configured size in bytes of the memory space used to + * allocate thread stacks for this application. + * + * @par Notes + * The size takes only threads and tasks into account with are known at the + * application configuration time. + * + * @par Constraints + * @parblock + * 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. + * @endparblock + */ +uintptr_t rtems_configuration_get_stack_space_size( void ); + +/* Generated from spec:/rtems/config/if/has-hardware-fp */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief This constant evaluates to #TRUE, if this processor variant has + * hardware floating point support, otherwise to #FALSE. + */ +#define RTEMS_HAS_HARDWARE_FP CPU_HARDWARE_FP + +/* Generated from spec:/rtems/config/if/stack-allocate-hook */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief A thread stack allocator allocate handler shall have this type. + */ +typedef Stack_Allocator_allocate rtems_stack_allocate_hook; + +/* Generated from spec:/rtems/config/if/stack-allocate-init-hook */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief A task stack allocator initialization handler shall have this type. + */ +typedef Stack_Allocator_initialize rtems_stack_allocate_init_hook; + +/* Generated from spec:/rtems/config/if/stack-free-hook */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief A task stack allocator free handler shall have this type. + */ +typedef Stack_Allocator_free rtems_stack_free_hook; + /* Generated from spec:/rtems/config/if/get-build-label */ /** @@ -102,10 +238,11 @@ extern "C" { * * @brief Gets the RTEMS build label. * - * The build label is a user-provided string defined by the build - * configuration. + * 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 Returns the pointer to the RTEMS build label. + * @return Returns a pointer to the RTEMS build label. * * @par Notes * The build label can be used to distinguish test suite results obtained from @@ -133,10 +270,77 @@ const char *rtems_get_build_label( void ); * * @brief Gets the RTEMS copyright notice. * - * @return Returns the pointer to the RTEMS copyright notice. + * @return Returns a pointer to the RTEMS copyright notice. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ const char *rtems_get_copyright_notice( void ); +/* Generated from spec:/rtems/config/if/get-target-hash */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief Gets the RTEMS target hash. + * + * 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 Returns a pointer to the RTEMS target hash. + * + * @par Notes + * @parblock + * 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(). + * @endparblock + * + * @par Constraints + * @parblock + * 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. + * @endparblock + */ +const char *rtems_get_target_hash( void ); + +/* Generated from spec:/rtems/config/if/get-version-string */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief Gets the RTEMS version string. + * + * @return Returns a pointer to the RTEMS version string. + * + * @par Notes + * The version string has no particular format. Parsing the string may break + * across RTEMS releases. + * + * @par Constraints + * @parblock + * 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. + * @endparblock + */ +const char *rtems_get_version_string( void ); + /* Generated from spec:/rtems/config/if/get-do-zero-of-workspace */ /** @@ -149,37 +353,67 @@ const char *rtems_get_copyright_notice( void ); * during system initialization for this application, otherwise false. * * @par Notes - * See #CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY. + * The setting is defined by the #CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY + * application configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_do_zero_of_workspace() _Memory_Zero_before_use -/* Generated from spec:/rtems/config/if/get-idle-task */ +/* Generated from spec:/rtems/config/if/get-idle-task-stack-size */ /** * @ingroup RTEMSAPIConfig * - * @brief Gets the IDLE task entry of this application. + * @brief Gets the IDLE task stack size in bytes of this application. * - * @return Returns the IDLE task entry of this application. + * @return Returns the IDLE task stack size in bytes of this application. * * @par Notes - * See #CONFIGURE_IDLE_TASK_BODY. + * The IDLE task stack size is defined by the #CONFIGURE_IDLE_TASK_STACK_SIZE + * application configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -#define rtems_configuration_get_idle_task() _Thread_Idle_body +#define rtems_configuration_get_idle_task_stack_size() _Thread_Idle_stack_size -/* Generated from spec:/rtems/config/if/get-idle-task-stack-size */ +/* Generated from spec:/rtems/config/if/get-idle-task */ /** * @ingroup RTEMSAPIConfig * - * @brief Gets the IDLE task stack size in bytes of this application. + * @brief Gets the IDLE task body of this application. * - * @return Returns the IDLE task stack size in bytes of this application. + * @return Returns the IDLE task body of this application. * * @par Notes - * See #CONFIGURE_IDLE_TASK_STACK_SIZE. + * The IDLE task body is defined by the #CONFIGURE_IDLE_TASK_BODY application + * configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ -#define rtems_configuration_get_idle_task_stack_size() _Thread_Idle_stack_size +#define rtems_configuration_get_idle_task() _Thread_Idle_body /* Generated from spec:/rtems/config/if/get-interrupt-stack-size */ @@ -191,7 +425,17 @@ const char *rtems_get_copyright_notice( void ); * @return Returns the interrupt stack size in bytes of this application. * * @par Notes - * See #CONFIGURE_INTERRUPT_STACK_SIZE. + * The interrupt stack size is defined by the #CONFIGURE_INTERRUPT_STACK_SIZE + * application configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_interrupt_stack_size() \ ((size_t) _ISR_Stack_size) @@ -201,14 +445,25 @@ const char *rtems_get_copyright_notice( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API User Extensions configured for - * this application. + * @brief Gets the resource number of @ref RTEMSAPIClassicUserExt objects + * configured for this application. * - * @return Returns the maximum number of Classic API User Extensions configured - * for this application. + * @return Returns the resource number of @ref RTEMSAPIClassicUserExt objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_USER_EXTENSIONS. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_extensions( void ); @@ -232,6 +487,15 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * In uniprocessor configurations, this macro is a compile time constant which * evaluates to one. * @endparblock + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_maximum_processors() \ _SMP_Processor_configured_maximum @@ -248,7 +512,17 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * this application. * * @par Notes - * See #CONFIGURE_MICROSECONDS_PER_TICK. + * The number of microseconds per clock tick is defined by the + * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_microseconds_per_tick() \ _Watchdog_Microseconds_per_tick @@ -265,7 +539,17 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * this application. * * @par Notes - * See #CONFIGURE_MICROSECONDS_PER_TICK. + * The number of milliseconds per clock tick is defined by the + * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_milliseconds_per_tick() \ ( _Watchdog_Microseconds_per_tick / 1000 ) @@ -282,7 +566,17 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * this application. * * @par Notes - * See #CONFIGURE_MICROSECONDS_PER_TICK. + * The number of nanoseconds per clock tick is defined by the + * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_nanoseconds_per_tick() \ _Watchdog_Nanoseconds_per_tick @@ -299,7 +593,18 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * application. * * @par Notes - * See #CONFIGURE_INITIAL_EXTENSIONS. + * The number of initial extensions is defined by the + * #CONFIGURE_INITIAL_EXTENSIONS application configuration option and related + * options. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_number_of_initial_extensions() \ ((uint32_t) _User_extensions_Initial_count) @@ -309,14 +614,24 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the thread stack allocator allocate hook used to allocate the + * @brief Gets the task stack allocator allocate hook used to allocate the * stack of each IDLE task configured for this application. * - * @return Returns the thread stack allocator allocate hook used to allocate - * the stack of each IDLE task configured for this application. + * @return Returns the task stack allocator allocate hook used to allocate the + * stack of each IDLE task configured for this application. * * @par Notes - * See #CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE. + * The task stack allocator allocate hook for idle tasks is defined by the + * #CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE application configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_stack_allocate_for_idle_hook() \ _Stack_Allocator_allocate_for_idle @@ -326,101 +641,68 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the thread stack allocator allocate hook configured for this + * @brief Gets the task stack allocator allocate hook configured for this * application. * - * @return Returns the thread stack allocator allocate hook configured for this + * @return Returns the task stack allocator allocate hook configured for this * application. * * @par Notes - * See #CONFIGURE_TASK_STACK_ALLOCATOR. - */ -#define rtems_configuration_get_stack_allocate_hook() _Stack_Allocator_allocate - -/* Generated from spec:/rtems/config/if/get-stack-allocate-init-hook */ - -/** - * @ingroup RTEMSAPIConfig + * The task stack allocator allocate hook is defined by the + * #CONFIGURE_TASK_STACK_ALLOCATOR application configuration option. * - * @brief Gets the thread stack allocator initialization hook configured for - * this application. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @return Returns the thread stack allocator initialization hook configured - * for this application. + * * The directive may be called from within any runtime context. * - * @par Notes - * See #CONFIGURE_TASK_STACK_ALLOCATOR_INIT. + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -#define rtems_configuration_get_stack_allocate_init_hook() \ - _Stack_Allocator_initialize +#define rtems_configuration_get_stack_allocate_hook() _Stack_Allocator_allocate -/* Generated from spec:/rtems/config/if/get-stack-allocator-avoids-work-space */ +/* Generated from spec:/rtems/config/if/get-stack-allocate-init-hook */ /** * @ingroup RTEMSAPIConfig * - * @brief Indicates if the thread stack allocator is configured to avoid the - * RTEMS Workspace for this application. + * @brief Gets the task stack allocator initialization hook configured for this + * application. * - * @return Returns true, if the thread stack allocator is configured to avoid - * the RTEMS Workspace for this application, otherwise false. + * @return Returns the task stack allocator initialization hook configured for + * this application. * * @par Notes - * See #CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE. - */ -#define rtems_configuration_get_stack_allocator_avoids_work_space() \ - _Stack_Allocator_avoids_workspace - -/* Generated from spec:/rtems/config/if/get-stack-free-hook */ - -/** - * @ingroup RTEMSAPIConfig + * The task stack allocator initialization hook is defined by the + * #CONFIGURE_TASK_STACK_ALLOCATOR_INIT application configuration option. * - * @brief Gets the thread stack allocator free hook configured for this - * application. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @return Returns the thread stack allocator free hook configured for this - * application. + * * The directive may be called from within any runtime context. * - * @par Notes - * See #CONFIGURE_TASK_STACK_DEALLOCATOR. + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -#define rtems_configuration_get_stack_free_hook() _Stack_Allocator_free +#define rtems_configuration_get_stack_allocate_init_hook() \ + _Stack_Allocator_initialize -/* Generated from spec:/rtems/config/if/get-stack-space-size */ +/* Generated from spec:/rtems/config/if/get-stack-free-hook */ /** * @ingroup RTEMSAPIConfig * - * @brief Gets the thread stack space size in bytes of configured for this + * @brief Gets the task stack allocator free hook configured for this * application. * - * @return Returns the thread stack space size in bytes of configured for this + * @return Returns the task stack allocator free hook configured for this * application. - */ -uintptr_t rtems_configuration_get_stack_space_size( void ); - -/* Generated from spec:/rtems/config/if/get-target-hash */ - -/** - * @ingroup RTEMSAPIConfig - * - * @brief Gets the RTEMS target hash. - * - * The target hash is calculated from BSP-specific values which characterize a - * target system. - * - * @return Returns the pointer to the RTEMS target hash. * * @par Notes - * @parblock - * 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(). - * @endparblock + * The task stack allocator free hook is defined by the + * #CONFIGURE_TASK_STACK_DEALLOCATOR application configuration option. * * @par Constraints * @parblock @@ -431,7 +713,7 @@ uintptr_t rtems_configuration_get_stack_space_size( void ); * * The directive will not cause the calling task to be preempted. * @endparblock */ -const char *rtems_get_target_hash( void ); +#define rtems_configuration_get_stack_free_hook() _Stack_Allocator_free /* Generated from spec:/rtems/config/if/get-ticks-per-timeslice */ @@ -444,7 +726,17 @@ const char *rtems_get_target_hash( void ); * application. * * @par Notes - * See #CONFIGURE_TICKS_PER_TIMESLICE. + * The clock ticks per timeslice is defined by the + * #CONFIGURE_TICKS_PER_TIMESLICE application configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_ticks_per_timeslice() \ _Watchdog_Ticks_per_timeslice @@ -461,7 +753,17 @@ const char *rtems_get_target_hash( void ); * configured to be unified for this application, otherwise false. * * @par Notes - * See #CONFIGURE_UNIFIED_WORK_AREAS. + * The setting is defined by the #CONFIGURE_UNIFIED_WORK_AREAS application + * configuration option. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_unified_work_area() _Workspace_Is_unified @@ -472,8 +774,17 @@ const char *rtems_get_target_hash( void ); * * @brief Gets the initial extensions table configured for this application. * - * @return Returns the pointer to the initial extensions table configured for + * @return Returns a pointer to the initial extensions table configured for * this application. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_user_extension_table() \ _User_extensions_Initial_extensions @@ -485,8 +796,17 @@ const char *rtems_get_target_hash( void ); * * @brief Gets the MPCI configuration table configured for this application. * - * @return Returns the pointer to the MPCI configuration table configured for + * @return Returns a pointer to the MPCI configuration table configured for * this application. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #if defined(RTEMS_MULTIPROCESSING) #define rtems_configuration_get_user_multiprocessing_table() \ @@ -495,17 +815,6 @@ const char *rtems_get_target_hash( void ); #define rtems_configuration_get_user_multiprocessing_table() NULL #endif -/* Generated from spec:/rtems/config/if/get-version-string */ - -/** - * @ingroup RTEMSAPIConfig - * - * @brief Gets the RTEMS version string. - * - * @return Returns the pointer to the RTEMS version string. - */ -const char *rtems_get_version_string( void ); - /* Generated from spec:/rtems/config/if/get-work-space-size */ /** @@ -516,22 +825,21 @@ const char *rtems_get_version_string( void ); * * @return Returns the RTEMS Workspace size in bytes configured for this * application. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_configuration_get_work_space_size() \ ( _Workspace_Size + \ ( rtems_configuration_get_stack_allocator_avoids_work_space() ? \ 0 : rtems_configuration_get_stack_space_size() ) ) -/* Generated from spec:/rtems/config/if/has-hardware-fp */ - -/** - * @ingroup RTEMSAPIConfig - * - * @brief This constant evaluates to #TRUE, if this processor variant has - * hardware floating point support, otherwise to #FALSE. - */ -#define RTEMS_HAS_HARDWARE_FP CPU_HARDWARE_FP - /* Generated from spec:/rtems/config/if/resource-is-unlimited */ /** @@ -543,9 +851,16 @@ const char *rtems_get_version_string( void ); * * @return Returns true, if the resource is unlimited, otherwise false. * - * @par Notes - * This function is implemented as a macro and can be used to define compile - * time constants. + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_resource_is_unlimited( _resource ) \ _Objects_Is_unlimited( _resource ) @@ -561,49 +876,19 @@ const char *rtems_get_version_string( void ); * * @return Returns the maximum number per allocation of a resource number. * - * @par Notes - * This function is implemented as a macro and can be used to define compile - * time constants. - */ -#define rtems_resource_maximum_per_allocation( _resource ) \ - _Objects_Maximum_per_allocation( _resource ) - -/* Generated from spec:/rtems/config/if/stack-allocate-hook */ - -/** - * @ingroup RTEMSAPIConfig - * - * @brief A thread stack allocator allocate handler shall have this type. - */ -typedef Stack_Allocator_allocate rtems_stack_allocate_hook; - -/* Generated from spec:/rtems/config/if/stack-allocate-init-hook */ - -/** - * @ingroup RTEMSAPIConfig - * - * @brief A thread stack allocator initialization handler shall have this type. - */ -typedef Stack_Allocator_initialize rtems_stack_allocate_init_hook; - -/* Generated from spec:/rtems/config/if/stack-free-hook */ - -/** - * @ingroup RTEMSAPIConfig + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @brief A thread stack allocator free handler shall have this type. - */ -typedef Stack_Allocator_free rtems_stack_free_hook; - -/* Generated from spec:/rtems/config/if/unlimited-objects */ - -/** - * @ingroup RTEMSAPIConfig + * * 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. * - * @brief This flag is used in augment a resource number so that it indicates - * an unlimited resource. + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -#define RTEMS_UNLIMITED_OBJECTS OBJECTS_UNLIMITED_OBJECTS +#define rtems_resource_maximum_per_allocation( _resource ) \ + _Objects_Maximum_per_allocation( _resource ) /* Generated from spec:/rtems/config/if/resource-unlimited */ @@ -619,8 +904,19 @@ typedef Stack_Allocator_free rtems_stack_free_hook; * resource. * * @par Notes - * This function is implemented as a macro and can be used to define compile - * time constants. + * This directive should be used to configure unlimited objects, see Unlimited + * Objects. + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ #define rtems_resource_unlimited( _resource ) \ ( ( _resource ) | RTEMS_UNLIMITED_OBJECTS ) diff --git a/cpukit/include/rtems/rtems/config.h b/cpukit/include/rtems/rtems/config.h index 3d813c55b6..4a6e6c8e2e 100644 --- a/cpukit/include/rtems/rtems/config.h +++ b/cpukit/include/rtems/rtems/config.h @@ -171,32 +171,30 @@ typedef struct { const rtems_initialization_tasks_table *User_initialization_tasks_table; } rtems_api_configuration_table; -/* Generated from spec:/rtems/config/if/get-api-configuration */ - -/** - * @ingroup RTEMSAPIConfig - * - * @brief Gets the Classic API Configuration Table of this application. - * - * @return Returns the pointer to the Classic API Configuration Table of this - * application. - */ -const rtems_api_configuration_table * -rtems_configuration_get_rtems_api_configuration( void ); - /* Generated from spec:/rtems/config/if/get-maximum-barriers */ /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Barriers configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicBarrier objects + * configured for this application. * - * @return Returns the maximum number of Classic API Barriers configured for - * this application. + * @return Returns the resource number of @ref RTEMSAPIClassicBarrier objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_BARRIERS. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_barriers( void ); @@ -205,14 +203,25 @@ uint32_t rtems_configuration_get_maximum_barriers( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Message Queues configured for - * this application. + * @brief Gets the resource number of @ref RTEMSAPIClassicMessage objects + * configured for this application. * - * @return Returns the maximum number of Classic API Message Queues configured - * for this application. + * @return Returns the resource number of @ref RTEMSAPIClassicMessage objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_MESSAGE_QUEUES. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_message_queues( void ); @@ -221,14 +230,25 @@ uint32_t rtems_configuration_get_maximum_message_queues( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Partitions configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicPart objects + * configured for this application. * - * @return Returns the maximum number of Classic API Partitions configured for - * this application. + * @return Returns the resource number of @ref RTEMSAPIClassicPart objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_PARTITIONS. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_partitions( void ); @@ -237,14 +257,25 @@ uint32_t rtems_configuration_get_maximum_partitions( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Rate Monotonic Periods + * @brief Gets the resource number of @ref RTEMSAPIClassicRatemon objects * configured for this application. * - * @return Returns the maximum number of Classic API Rate Monotonic Periods + * @return Returns the resource number of @ref RTEMSAPIClassicRatemon objects * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_PERIODS. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_periods( void ); @@ -253,14 +284,25 @@ uint32_t rtems_configuration_get_maximum_periods( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Dual-Ported Memories + * @brief Gets the resource number of @ref RTEMSAPIClassicDPMem objects * configured for this application. * - * @return Returns the maximum number of Classic API Dual-Ported Memories + * @return Returns the resource number of @ref RTEMSAPIClassicDPMem objects * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_PORTS. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_ports( void ); @@ -269,14 +311,25 @@ uint32_t rtems_configuration_get_maximum_ports( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Regions configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicRegion objects + * configured for this application. * - * @return Returns the maximum number of Classic API Regions configured for - * this application. + * @return Returns the resource number of @ref RTEMSAPIClassicRegion objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_REGIONS. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_regions( void ); @@ -285,14 +338,25 @@ uint32_t rtems_configuration_get_maximum_regions( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Semaphores configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicSem objects + * configured for this application. * - * @return Returns the maximum number of Classic API Semaphores configured for - * this application. + * @return Returns the resource number of @ref RTEMSAPIClassicSem objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_SEMAPHORES. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_semaphores( void ); @@ -301,14 +365,25 @@ uint32_t rtems_configuration_get_maximum_semaphores( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Tasks configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicTasks objects + * configured for this application. * - * @return Returns the maximum number of Classic API Tasks configured for this - * application. + * @return Returns the resource number of @ref RTEMSAPIClassicTasks objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_TASKS. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_tasks( void ); @@ -317,17 +392,50 @@ uint32_t rtems_configuration_get_maximum_tasks( void ); /** * @ingroup RTEMSAPIConfig * - * @brief Gets the maximum number of Classic API Timers configured for this - * application. + * @brief Gets the resource number of @ref RTEMSAPIClassicTimer objects + * configured for this application. * - * @return Returns the maximum number of Classic API Timers configured for this - * application. + * @return Returns the resource number of @ref RTEMSAPIClassicTimer objects + * configured for this application. * * @par Notes - * See #CONFIGURE_MAXIMUM_TIMERS. + * 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(). + * + * @par Constraints + * @parblock + * 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. + * @endparblock */ uint32_t rtems_configuration_get_maximum_timers( void ); +/* Generated from spec:/rtems/config/if/get-api-configuration */ + +/** + * @ingroup RTEMSAPIConfig + * + * @brief Gets the Classic API Configuration Table of this application. + * + * @return Returns a pointer to the Classic API Configuration Table of this + * application. + * + * @par Constraints + * @parblock + * 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. + * @endparblock + */ +const rtems_api_configuration_table * +rtems_configuration_get_rtems_api_configuration( void ); + #ifdef __cplusplus } #endif -- cgit v1.2.3