[rtems commit] rtems: Add "Notes" paragraph header
Sebastian Huber
sebh at rtems.org
Wed Jan 27 05:02:06 UTC 2021
Module: rtems
Branch: master
Commit: b35ac9901caac823c5aa4aeeb81c4bb2c6bc58fd
Changeset: http://git.rtems.org/rtems/commit/?id=b35ac9901caac823c5aa4aeeb81c4bb2c6bc58fd
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Mon Jan 25 09:27:22 2021 +0100
rtems: Add "Notes" paragraph header
Place the paragraphs in the same order as the directive documentation in
the RTEMS Classic API Guide.
Update #3993.
---
cpukit/include/rtems/config.h | 105 +++++++++-------
cpukit/include/rtems/io.h | 128 +++++++++++---------
cpukit/include/rtems/rtems/attr.h | 8 ++
cpukit/include/rtems/rtems/config.h | 45 ++++---
cpukit/include/rtems/rtems/event.h | 76 ++++++------
cpukit/include/rtems/rtems/modes.h | 17 +--
cpukit/include/rtems/rtems/object.h | 188 ++++++++++++++++------------
cpukit/include/rtems/rtems/part.h | 222 ++++++++++++++++++----------------
cpukit/include/rtems/rtems/status.h | 5 +-
cpukit/include/rtems/rtems/timer.h | 207 +++++++++++++++++--------------
cpukit/include/rtems/score/basedefs.h | 16 +--
11 files changed, 577 insertions(+), 440 deletions(-)
diff --git a/cpukit/include/rtems/config.h b/cpukit/include/rtems/config.h
index cc54a25..a3eec39 100644
--- a/cpukit/include/rtems/config.h
+++ b/cpukit/include/rtems/config.h
@@ -112,10 +112,11 @@ const char *rtems_get_copyright_notice( void );
* @brief Indicates if the RTEMS Workspace is configured to be zeroed during
* system initialization for this application.
*
- * See #CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY.
- *
* @return Returns true, if the RTEMS Workspace is configured to be zeroed
* during system initialization for this application, otherwise false.
+ *
+ * @par Notes
+ * See #CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY.
*/
#define rtems_configuration_get_do_zero_of_workspace() _Memory_Zero_before_use
@@ -126,9 +127,10 @@ const char *rtems_get_copyright_notice( void );
*
* @brief Gets the IDLE task entry of this application.
*
- * See #CONFIGURE_IDLE_TASK_BODY.
- *
* @return Returns the IDLE task entry of this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_IDLE_TASK_BODY.
*/
#define rtems_configuration_get_idle_task() _Thread_Idle_body
@@ -139,9 +141,10 @@ const char *rtems_get_copyright_notice( void );
*
* @brief Gets the IDLE task stack size in bytes of this application.
*
- * See #CONFIGURE_IDLE_TASK_STACK_SIZE.
- *
* @return Returns the IDLE task stack size in bytes of this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_IDLE_TASK_STACK_SIZE.
*/
#define rtems_configuration_get_idle_task_stack_size() _Thread_Idle_stack_size
@@ -152,9 +155,10 @@ const char *rtems_get_copyright_notice( void );
*
* @brief Gets the interrupt stack size in bytes of this application.
*
- * See #CONFIGURE_INTERRUPT_STACK_SIZE.
- *
* @return Returns the interrupt stack size in bytes of this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_INTERRUPT_STACK_SIZE.
*/
#define rtems_configuration_get_interrupt_stack_size() \
((size_t) _ISR_Stack_size)
@@ -167,10 +171,11 @@ const char *rtems_get_copyright_notice( void );
* @brief Gets the maximum number of Classic API User Extensions configured for
* this application.
*
- * See #CONFIGURE_MAXIMUM_USER_EXTENSIONS.
- *
* @return Returns the maximum number of Classic API User Extensions configured
* for this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_USER_EXTENSIONS.
*/
uint32_t rtems_configuration_get_maximum_extensions( void );
@@ -182,15 +187,18 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Gets the maximum number of processors configured for this
* application.
*
+ * @return Returns the maximum number of processors configured for this
+ * application.
+ *
+ * @par Notes
+ * @parblock
* 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.
- *
- * @return Returns the maximum number of processors configured for this
- * application.
+ * @endparblock
*/
#define rtems_configuration_get_maximum_processors() \
_SMP_Processor_configured_maximum
@@ -203,10 +211,11 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Gets the number of microseconds per clock tick configured for this
* application.
*
- * See #CONFIGURE_MICROSECONDS_PER_TICK.
- *
* @return Returns the number of microseconds per clock tick configured for
* this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MICROSECONDS_PER_TICK.
*/
#define rtems_configuration_get_microseconds_per_tick() \
_Watchdog_Microseconds_per_tick
@@ -219,10 +228,11 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Gets the number of milliseconds per clock tick configured for this
* application.
*
- * See #CONFIGURE_MICROSECONDS_PER_TICK.
- *
* @return Returns the number of milliseconds per clock tick configured for
* this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MICROSECONDS_PER_TICK.
*/
#define rtems_configuration_get_milliseconds_per_tick() \
( _Watchdog_Microseconds_per_tick / 1000 )
@@ -235,10 +245,11 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Gets the number of microseconds per clock tick configured for this
* application.
*
- * See #CONFIGURE_MICROSECONDS_PER_TICK.
- *
* @return Returns the number of microseconds per clock tick configured for
* this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MICROSECONDS_PER_TICK.
*/
#define rtems_configuration_get_nanoseconds_per_tick() \
_Watchdog_Nanoseconds_per_tick
@@ -251,10 +262,11 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Gets the number of initial extensions configured for this
* application.
*
- * See #CONFIGURE_INITIAL_EXTENSIONS.
- *
* @return Returns the number of initial extensions configured for this
* application.
+ *
+ * @par Notes
+ * See #CONFIGURE_INITIAL_EXTENSIONS.
*/
#define rtems_configuration_get_number_of_initial_extensions() \
((uint32_t) _User_extensions_Initial_count)
@@ -267,10 +279,11 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Gets the thread stack allocator allocate hook configured for this
* application.
*
- * See #CONFIGURE_TASK_STACK_ALLOCATOR.
- *
* @return Returns the thread 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
@@ -282,10 +295,11 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Gets the thread stack allocator initialization hook configured for
* this application.
*
- * See #CONFIGURE_TASK_STACK_ALLOCATOR_INIT.
- *
* @return Returns the thread stack allocator initialization hook configured
* for this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_TASK_STACK_ALLOCATOR_INIT.
*/
#define rtems_configuration_get_stack_allocate_init_hook() \
_Stack_Allocator_initialize
@@ -298,10 +312,11 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Indicates if the thread stack allocator is configured to avoid the
* RTEMS Workspace for this application.
*
- * See #CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE.
- *
* @return Returns true, if the thread stack allocator is configured to avoid
* the RTEMS Workspace for this application, otherwise false.
+ *
+ * @par Notes
+ * See #CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE.
*/
#define rtems_configuration_get_stack_allocator_avoids_work_space() \
_Stack_Allocator_avoids_workspace
@@ -314,10 +329,11 @@ uint32_t rtems_configuration_get_maximum_extensions( void );
* @brief Gets the thread stack allocator free hook configured for this
* application.
*
- * See #CONFIGURE_TASK_STACK_DEALLOCATOR.
- *
* @return Returns the thread stack allocator free hook configured for this
* application.
+ *
+ * @par Notes
+ * See #CONFIGURE_TASK_STACK_DEALLOCATOR.
*/
#define rtems_configuration_get_stack_free_hook() _Stack_Allocator_free
@@ -341,10 +357,11 @@ uintptr_t rtems_configuration_get_stack_space_size( void );
*
* @brief Gets the clock ticks per timeslice configured for this application.
*
- * See #CONFIGURE_TICKS_PER_TIMESLICE.
- *
* @return Returns the clock ticks per timeslice configured for this
* application.
+ *
+ * @par Notes
+ * See #CONFIGURE_TICKS_PER_TIMESLICE.
*/
#define rtems_configuration_get_ticks_per_timeslice() \
_Watchdog_Ticks_per_timeslice
@@ -357,10 +374,11 @@ uintptr_t rtems_configuration_get_stack_space_size( void );
* @brief Indicates if the RTEMS Workspace and C Program Heap are configured to
* be unified for this application.
*
- * See #CONFIGURE_UNIFIED_WORK_AREAS.
- *
* @return Returns true, if the RTEMS Workspace and C Program Heap are
* configured to be unified for this application, otherwise false.
+ *
+ * @par Notes
+ * See #CONFIGURE_UNIFIED_WORK_AREAS.
*/
#define rtems_configuration_get_unified_work_area() _Workspace_Is_unified
@@ -438,12 +456,13 @@ const char *rtems_get_version_string( void );
*
* @brief Indicates if the resource is unlimited.
*
- * This function is implemented as a macro and can be used to define compile
- * time constants.
- *
* @param _resource is the resource number.
*
* @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.
*/
#define rtems_resource_is_unlimited( _resource ) \
_Objects_Is_unlimited( _resource )
@@ -455,12 +474,13 @@ const char *rtems_get_version_string( void );
*
* @brief Gets the maximum number per allocation of a resource number.
*
- * This function is implemented as a macro and can be used to define compile
- * time constants.
- *
* @param _resource is the resource number.
*
* @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 )
@@ -510,13 +530,14 @@ typedef Stack_Allocator_free rtems_stack_free_hook;
* @brief Augments the resource number so that it indicates an unlimited
* resource.
*
- * This function is implemented as a macro and can be used to define compile
- * time constants.
- *
* @param _resource is the resource number to augment.
*
* @return Returns the resource number augmented to indicate an unlimited
* resource.
+ *
+ * @par Notes
+ * This function is implemented as a macro and can be used to define compile
+ * time constants.
*/
#define rtems_resource_unlimited( _resource ) \
( ( _resource ) | RTEMS_UNLIMITED_OBJECTS )
diff --git a/cpukit/include/rtems/io.h b/cpukit/include/rtems/io.h
index 445f24c..f80d2ce 100644
--- a/cpukit/include/rtems/io.h
+++ b/cpukit/include/rtems/io.h
@@ -83,6 +83,7 @@ extern "C" {
* @brief This type shall be used in device driver entry declarations and
* definitions.
*
+ * @par Notes
* Device driver entries return an #rtems_status_code status code. This type
* definition helps to document device driver entries in the source code.
*/
@@ -95,6 +96,7 @@ typedef rtems_status_code rtems_device_driver;
*
* @brief This integer type represents the major number of devices.
*
+ * @par Notes
* The major number of a device is determined by rtems_io_register_driver() and
* the application configuration (see #CONFIGURE_MAXIMUM_DRIVERS) .
*/
@@ -107,6 +109,7 @@ typedef uint32_t rtems_device_major_number;
*
* @brief This integer type represents the minor number of devices.
*
+ * @par Notes
* The minor number of devices is managed by the device driver.
*/
typedef uint32_t rtems_device_minor_number;
@@ -186,13 +189,6 @@ typedef struct {
* @brief Registers and initializes the device with the specified device driver
* address table and device major number in the Device Driver Table.
*
- * If the device major number equals zero a device major number will be
- * obtained. The device major number of the registered driver will be
- * returned.
- *
- * After a successful registration, the rtems_io_initialize() directive will be
- * called to initialize the device.
- *
* @param major is the device major number. Use a value of zero to let the
* system obtain a device major number automatically.
*
@@ -221,6 +217,16 @@ typedef struct {
* context.
*
* @return Other status codes may be returned by rtems_io_initialize().
+ *
+ * @par Notes
+ * @parblock
+ * If the device major number equals zero a device major number will be
+ * obtained. The device major number of the registered driver will be
+ * returned.
+ *
+ * After a successful registration, the rtems_io_initialize() directive will be
+ * called to initialize the device.
+ * @endparblock
*/
rtems_status_code rtems_io_register_driver(
rtems_device_major_number major,
@@ -236,8 +242,6 @@ rtems_status_code rtems_io_register_driver(
* @brief Removes a device driver specified by the device major number from the
* Device Driver Table.
*
- * Currently no specific checks are made and the driver is not closed.
- *
* @param major is the major number of the device.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
@@ -246,6 +250,9 @@ rtems_status_code rtems_io_register_driver(
*
* @retval ::RTEMS_CALLED_FROM_ISR The directive was called from interrupt
* context.
+ *
+ * @par Notes
+ * Currently no specific checks are made and the driver is not closed.
*/
rtems_status_code rtems_io_unregister_driver(
rtems_device_major_number major
@@ -259,17 +266,6 @@ rtems_status_code rtems_io_unregister_driver(
* @brief Initializes the device specified by the device major and minor
* numbers.
*
- * This directive calls the device driver initialization entry registered in
- * the Device Driver Table for the specified device major number.
- *
- * This directive is automatically invoked for each device driver defined by
- * the application configuration during the system initialization and via the
- * rtems_io_register_driver() directive.
- *
- * A device driver initialization entry is responsible for initializing all
- * hardware and data structures associated with a device. If necessary, it can
- * allocate memory to be used during other operations.
- *
* @param major is the major number of the device.
*
* @param minor is the minor number of the device.
@@ -277,12 +273,26 @@ rtems_status_code rtems_io_unregister_driver(
* @param argument is the argument passed to the device driver initialization
* entry.
*
+ * This directive calls the device driver initialization entry registered in
+ * the Device Driver Table for the specified device major number.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
*
* @return Other status codes may be returned by the device driver
* initialization entry.
+ *
+ * @par Notes
+ * @parblock
+ * This directive is automatically invoked for each device driver defined by
+ * the application configuration during the system initialization and via the
+ * rtems_io_register_driver() directive.
+ *
+ * A device driver initialization entry is responsible for initializing all
+ * hardware and data structures associated with a device. If necessary, it can
+ * allocate memory to be used during other operations.
+ * @endparblock
*/
rtems_status_code rtems_io_initialize(
rtems_device_major_number major,
@@ -298,8 +308,6 @@ rtems_status_code rtems_io_initialize(
* @brief Registers the device specified by the device major and minor numbers
* in the file system under the specified name.
*
- * The device is registered as a character device.
- *
* @param device_name is the device name in the file system.
*
* @param major is the device major number.
@@ -310,6 +318,9 @@ rtems_status_code rtems_io_initialize(
*
* @retval ::RTEMS_TOO_MANY The name was already in use or other errors
* occurred.
+ *
+ * @par Notes
+ * The device is registered as a character device.
*/
rtems_status_code rtems_io_register_name(
const char *device_name,
@@ -324,23 +335,24 @@ rtems_status_code rtems_io_register_name(
*
* @brief Opens the device specified by the device major and minor numbers.
*
- * This directive calls the device driver open entry registered in the Device
- * Driver Table for the specified device major number.
- *
- * The open entry point is commonly used by device drivers to provide exclusive
- * access to a device.
- *
* @param major is the major number of the device.
*
* @param minor is the minor number of the device.
*
* @param argument is the argument passed to the device driver close entry.
*
+ * This directive calls the device driver open entry registered in the Device
+ * Driver Table for the specified device major number.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
*
* @return Other status codes may be returned by the device driver open entry.
+ *
+ * @par Notes
+ * The open entry point is commonly used by device drivers to provide exclusive
+ * access to a device.
*/
rtems_status_code rtems_io_open(
rtems_device_major_number major,
@@ -355,23 +367,24 @@ rtems_status_code rtems_io_open(
*
* @brief Closes the device specified by the device major and minor numbers.
*
- * This directive calls the device driver close entry registered in the Device
- * Driver Table for the specified device major number.
- *
- * The close entry point is commonly used by device drivers to relinquish
- * exclusive access to a device.
- *
* @param major is the major number of the device.
*
* @param minor is the minor number of the device.
*
* @param argument is the argument passed to the device driver close entry.
*
+ * This directive calls the device driver close entry registered in the Device
+ * Driver Table for the specified device major number.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
*
* @return Other status codes may be returned by the device driver close entry.
+ *
+ * @par Notes
+ * The close entry point is commonly used by device drivers to relinquish
+ * exclusive access to a device.
*/
rtems_status_code rtems_io_close(
rtems_device_major_number major,
@@ -387,24 +400,25 @@ rtems_status_code rtems_io_close(
* @brief Reads from the device specified by the device major and minor
* numbers.
*
- * This directive calls the device driver read entry registered in the Device
- * Driver Table for the specified device major number.
- *
- * Read operations typically require a buffer address as part of the argument
- * parameter block. The contents of this buffer will be replaced with data
- * from the device.
- *
* @param major is the major number of the device.
*
* @param minor is the minor number of the device.
*
* @param argument is the argument passed to the device driver read entry.
*
+ * This directive calls the device driver read entry registered in the Device
+ * Driver Table for the specified device major number.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
*
* @return Other status codes may be returned by the device driver read entry.
+ *
+ * @par Notes
+ * Read operations typically require a buffer address as part of the argument
+ * parameter block. The contents of this buffer will be replaced with data
+ * from the device.
*/
rtems_status_code rtems_io_read(
rtems_device_major_number major,
@@ -419,23 +433,24 @@ rtems_status_code rtems_io_read(
*
* @brief Writes to the device specified by the device major and minor numbers.
*
- * This directive calls the device driver write entry registered in the Device
- * Driver Table for the specified device major number.
- *
- * Write operations typically require a buffer address as part of the argument
- * parameter block. The contents of this buffer will be sent to the device.
- *
* @param major is the major number of the device.
*
* @param minor is the minor number of the device.
*
* @param argument is the argument passed to the device driver write entry.
*
+ * This directive calls the device driver write entry registered in the Device
+ * Driver Table for the specified device major number.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
*
* @return Other status codes may be returned by the device driver write entry.
+ *
+ * @par Notes
+ * Write operations typically require a buffer address as part of the argument
+ * parameter block. The contents of this buffer will be sent to the device.
*/
rtems_status_code rtems_io_write(
rtems_device_major_number major,
@@ -450,15 +465,6 @@ rtems_status_code rtems_io_write(
*
* @brief Controls the device specified by the device major and minor numbers.
*
- * This directive calls the device driver I/O control entry registered in the
- * Device Driver Table for the specified device major number.
- *
- * The exact functionality of the driver entry called by this directive is
- * driver dependent. It should not be assumed that the control entries of two
- * device drivers are compatible. For example, an RS-232 driver I/O control
- * operation may change the baud of a serial line, while an I/O control
- * operation for a floppy disk driver may cause a seek operation.
- *
* @param major is the major number of the device.
*
* @param minor is the minor number of the device.
@@ -466,12 +472,22 @@ rtems_status_code rtems_io_write(
* @param argument is the argument passed to the device driver I/O control
* entry.
*
+ * This directive calls the device driver I/O control entry registered in the
+ * Device Driver Table for the specified device major number.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_NUMBER The device major number was invalid.
*
* @return Other status codes may be returned by the device driver I/O control
* entry.
+ *
+ * @par Notes
+ * The exact functionality of the driver entry called by this directive is
+ * driver dependent. It should not be assumed that the control entries of two
+ * device drivers are compatible. For example, an RS-232 driver I/O control
+ * operation may change the baud of a serial line, while an I/O control
+ * operation for a floppy disk driver may cause a seek operation.
*/
rtems_status_code rtems_io_control(
rtems_device_major_number major,
diff --git a/cpukit/include/rtems/rtems/attr.h b/cpukit/include/rtems/rtems/attr.h
index baea36a..18a3820 100644
--- a/cpukit/include/rtems/rtems/attr.h
+++ b/cpukit/include/rtems/rtems/attr.h
@@ -88,6 +88,7 @@ extern "C" {
*
* @brief This type represents Classic API attributes.
*
+ * @par Notes
* Attributes are primarily used when creating objects.
*/
typedef uint32_t rtems_attribute;
@@ -162,6 +163,7 @@ typedef uint32_t rtems_attribute;
* by rtems_task_create() or rtems_task_construct() shall be able to use the
* floating point hardware.
*
+ * @par Notes
* On some architectures, there will be a floating point context associated
* with this task.
*/
@@ -175,6 +177,7 @@ typedef uint32_t rtems_attribute;
* @brief This attribute constant indicates that the Classic API object shall
* be a global resource in a multiprocessing network.
*
+ * @par Notes
* This attribute does not refer to SMP systems.
*/
#define RTEMS_GLOBAL 0x00000002
@@ -188,6 +191,7 @@ typedef uint32_t rtems_attribute;
* created by rtems_semaphore_create() shall use the Priority Inheritance
* Protocol.
*
+ * @par Notes
* The semaphore shall be a binary semaphore (#RTEMS_BINARY_SEMAPHORE).
*/
#define RTEMS_INHERIT_PRIORITY 0x00000040
@@ -200,6 +204,7 @@ typedef uint32_t rtems_attribute;
* @brief This attribute constant indicates that the Classic API object shall
* be a local resource in a multiprocessing network.
*
+ * @par Notes
* This attribute does not refer to SMP systems.
*/
#define RTEMS_LOCAL 0x00000000
@@ -213,6 +218,7 @@ typedef uint32_t rtems_attribute;
* created by rtems_semaphore_create() shall use the Multiprocessor Resource
* Sharing Protocol.
*
+ * @par Notes
* The semaphore shall be a binary semaphore (#RTEMS_BINARY_SEMAPHORE).
*/
#define RTEMS_MULTIPROCESSOR_RESOURCE_SHARING 0x00000100
@@ -226,6 +232,7 @@ typedef uint32_t rtems_attribute;
* by rtems_task_create() or rtems_task_construct() will not use the floating
* point hardware.
*
+ * @par Notes
* If the architecture permits it, then the FPU will be disabled when the task
* is executing.
*/
@@ -283,6 +290,7 @@ typedef uint32_t rtems_attribute;
* created by rtems_semaphore_create() shall use the Priority Ceiling
* Protocol.
*
+ * @par Notes
* The semaphore shall be a binary semaphore (#RTEMS_BINARY_SEMAPHORE).
*/
#define RTEMS_PRIORITY_CEILING 0x00000080
diff --git a/cpukit/include/rtems/rtems/config.h b/cpukit/include/rtems/rtems/config.h
index 76a4a75..2a12c8f 100644
--- a/cpukit/include/rtems/rtems/config.h
+++ b/cpukit/include/rtems/rtems/config.h
@@ -190,10 +190,11 @@ rtems_configuration_get_rtems_api_configuration( void );
* @brief Gets the maximum number of Classic API Barriers configured for this
* application.
*
- * See #CONFIGURE_MAXIMUM_BARRIERS.
- *
* @return Returns the maximum number of Classic API Barriers configured for
* this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_BARRIERS.
*/
uint32_t rtems_configuration_get_maximum_barriers( void );
@@ -205,10 +206,11 @@ uint32_t rtems_configuration_get_maximum_barriers( void );
* @brief Gets the maximum number of Classic API Message Queues configured for
* this application.
*
- * See #CONFIGURE_MAXIMUM_MESSAGE_QUEUES.
- *
* @return Returns the maximum number of Classic API Message Queues configured
* for this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_MESSAGE_QUEUES.
*/
uint32_t rtems_configuration_get_maximum_message_queues( void );
@@ -220,10 +222,11 @@ uint32_t rtems_configuration_get_maximum_message_queues( void );
* @brief Gets the maximum number of Classic API Partitions configured for this
* application.
*
- * See #CONFIGURE_MAXIMUM_PARTITIONS.
- *
* @return Returns the maximum number of Classic API Partitions configured for
* this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_PARTITIONS.
*/
uint32_t rtems_configuration_get_maximum_partitions( void );
@@ -235,10 +238,11 @@ uint32_t rtems_configuration_get_maximum_partitions( void );
* @brief Gets the maximum number of Classic API Rate Monotonic Periods
* configured for this application.
*
- * See #CONFIGURE_MAXIMUM_PERIODS.
- *
* @return Returns the maximum number of Classic API Rate Monotonic Periods
* configured for this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_PERIODS.
*/
uint32_t rtems_configuration_get_maximum_periods( void );
@@ -250,10 +254,11 @@ uint32_t rtems_configuration_get_maximum_periods( void );
* @brief Gets the maximum number of Classic API Dual-Ported Memories
* configured for this application.
*
- * See #CONFIGURE_MAXIMUM_PORTS.
- *
* @return Returns the maximum number of Classic API Dual-Ported Memories
* configured for this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_PORTS.
*/
uint32_t rtems_configuration_get_maximum_ports( void );
@@ -265,10 +270,11 @@ uint32_t rtems_configuration_get_maximum_ports( void );
* @brief Gets the maximum number of Classic API Regions configured for this
* application.
*
- * See #CONFIGURE_MAXIMUM_REGIONS.
- *
* @return Returns the maximum number of Classic API Regions configured for
* this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_REGIONS.
*/
uint32_t rtems_configuration_get_maximum_regions( void );
@@ -280,10 +286,11 @@ uint32_t rtems_configuration_get_maximum_regions( void );
* @brief Gets the maximum number of Classic API Semaphores configured for this
* application.
*
- * See #CONFIGURE_MAXIMUM_SEMAPHORES.
- *
* @return Returns the maximum number of Classic API Semaphores configured for
* this application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_SEMAPHORES.
*/
uint32_t rtems_configuration_get_maximum_semaphores( void );
@@ -295,10 +302,11 @@ uint32_t rtems_configuration_get_maximum_semaphores( void );
* @brief Gets the maximum number of Classic API Tasks configured for this
* application.
*
- * See #CONFIGURE_MAXIMUM_TASKS.
- *
* @return Returns the maximum number of Classic API Tasks configured for this
* application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_TASKS.
*/
uint32_t rtems_configuration_get_maximum_tasks( void );
@@ -310,10 +318,11 @@ uint32_t rtems_configuration_get_maximum_tasks( void );
* @brief Gets the maximum number of Classic API Timers configured for this
* application.
*
- * See #CONFIGURE_MAXIMUM_TIMERS.
- *
* @return Returns the maximum number of Classic API Timers configured for this
* application.
+ *
+ * @par Notes
+ * See #CONFIGURE_MAXIMUM_TIMERS.
*/
uint32_t rtems_configuration_get_maximum_timers( void );
diff --git a/cpukit/include/rtems/rtems/event.h b/cpukit/include/rtems/rtems/event.h
index 8aa1157..a6d0a16 100644
--- a/cpukit/include/rtems/rtems/event.h
+++ b/cpukit/include/rtems/rtems/event.h
@@ -464,10 +464,6 @@ typedef uint32_t rtems_event_set;
/**
* @brief Receives or gets a system event set from the executing task.
*
- * This directive performs the same actions as the rtems_event_receive()
- * directive except that it operates with a different set of events for each
- * task.
- *
* @param event_in is the event set of interest. Use #RTEMS_PENDING_EVENTS to
* get the pending events.
*
@@ -479,6 +475,10 @@ typedef uint32_t rtems_event_set;
* @param event_out is the pointer to an event set. The received or pending
* events are stored in the referenced event set if the operation was
* successful.
+ *
+ * This directive performs the same actions as the rtems_event_receive()
+ * directive except that it operates with a different set of events for each
+ * task.
*/
rtems_status_code rtems_event_system_receive(
rtems_event_set event_in,
@@ -585,6 +585,10 @@ static inline rtems_status_code rtems_event_transient_send( rtems_id id )
*
* @brief Sends the event set to the task.
*
+ * @param id is the identifier of the target task to receive the event set.
+ *
+ * @param event_in is the event set to send.
+ *
* This directive sends the event set, ``event_in``, to the target task
* identified by ``id``. Based upon the state of the target task, one of the
* following situations applies:
@@ -600,6 +604,13 @@ static inline rtems_status_code rtems_event_transient_send( rtems_id id )
* * The target task is not waiting for events, then the event set is posted
* and left pending.
*
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
+ * specified by ``id``.
+ *
+ * @par Notes
+ * @parblock
* Events can be sent by tasks or an ISR.
*
* Specifying #RTEMS_SELF for ``id`` results in the event set being sent to the
@@ -619,15 +630,7 @@ static inline rtems_status_code rtems_event_transient_send( rtems_id id )
* Sending an event set to a global task which does not reside on the local
* node will generate a request telling the remote node to send the event set
* to the appropriate task.
- *
- * @param id is the identifier of the target task to receive the event set.
- *
- * @param event_in is the event set to send.
- *
- * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
- *
- * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
- * specified by ``id``.
+ * @endparblock
*/
rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in );
@@ -638,6 +641,18 @@ rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in );
*
* @brief Receives or gets an event set from the calling task.
*
+ * @param event_in is the event set of interest. Use #RTEMS_PENDING_EVENTS to
+ * get the pending events.
+ *
+ * @param option_set is the option set.
+ *
+ * @param ticks is the timeout in clock ticks if the #RTEMS_WAIT option is set.
+ * Use #RTEMS_NO_TIMEOUT to wait potentially forever.
+ *
+ * @param event_out is the pointer to an event set. The received or pending
+ * events are stored in the referenced event set if the operation was
+ * successful.
+ *
* This directive can be used to
*
* * get the pending events of the calling task, or
@@ -680,6 +695,18 @@ rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in );
* * Receiving **any** of the input events is selected by the #RTEMS_EVENT_ANY
* option.
*
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``event_out`` parameter was NULL.
+ *
+ * @retval ::RTEMS_UNSATISFIED The events of interest were not immediately
+ * available.
+ *
+ * @retval ::RTEMS_TIMEOUT The events of interest were not available within the
+ * specified timeout interval.
+ *
+ * @par Notes
+ * @parblock
* This directive shall be called by a task. Calling this directive from
* interrupt context is undefined behaviour.
*
@@ -697,28 +724,7 @@ rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in );
* ``option_set`` parameter. The pending events are returned and the event set
* of the task is cleared. If no events are pending then the
* ::RTEMS_UNSATISFIED status code will be returned.
- *
- * @param event_in is the event set of interest. Use #RTEMS_PENDING_EVENTS to
- * get the pending events.
- *
- * @param option_set is the option set.
- *
- * @param ticks is the timeout in clock ticks if the #RTEMS_WAIT option is set.
- * Use #RTEMS_NO_TIMEOUT to wait potentially forever.
- *
- * @param event_out is the pointer to an event set. The received or pending
- * events are stored in the referenced event set if the operation was
- * successful.
- *
- * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
- *
- * @retval ::RTEMS_INVALID_ADDRESS The ``event_out`` parameter was NULL.
- *
- * @retval ::RTEMS_UNSATISFIED The events of interest were not immediately
- * available.
- *
- * @retval ::RTEMS_TIMEOUT The events of interest were not available within the
- * specified timeout interval.
+ * @endparblock
*/
rtems_status_code rtems_event_receive(
rtems_event_set event_in,
diff --git a/cpukit/include/rtems/rtems/modes.h b/cpukit/include/rtems/rtems/modes.h
index b711b11..559029d 100644
--- a/cpukit/include/rtems/rtems/modes.h
+++ b/cpukit/include/rtems/rtems/modes.h
@@ -135,15 +135,16 @@ extern "C" {
* @brief Maps the interrupt level to the associated processor-dependent task
* mode interrupt level.
*
- * The Classic API supports 256 interrupt levels using the least significant
- * eight bits of the mode set. On any particular processor variant, fewer than
- * 256 levels may be supported. At least level 0 (all interrupts enabled) and
- * level 1 (interrupts disabled, on most architectures) are supported.
- *
* @param _interrupt_level is the interrupt level to map.
*
* @return Returns the processor-dependent task mode interrupt level associated
* with the interrupt level.
+ *
+ * @par Notes
+ * The Classic API supports 256 interrupt levels using the least significant
+ * eight bits of the mode set. On any particular processor variant, fewer than
+ * 256 levels may be supported. At least level 0 (all interrupts enabled) and
+ * level 1 (interrupts disabled, on most architectures) are supported.
*/
#define RTEMS_INTERRUPT_LEVEL( _interrupt_level ) \
( ( _interrupt_level ) & RTEMS_INTERRUPT_MASK )
@@ -155,6 +156,7 @@ extern "C" {
*
* @brief This task mode constant has the same value as #RTEMS_INTERRUPT_MASK.
*
+ * @par Notes
* This task mode constant is used by bindings from languages other than C and
* C++.
*/
@@ -177,11 +179,12 @@ typedef uint32_t rtems_mode;
* @brief Maps the interrupt level to the associated processor-dependent task
* mode interrupt level.
*
- * This function is used by bindings from languages other than C and C++.
- *
* @param level is the interrupt level to map.
*
* @return Returns RTEMS_INTERRUPT_LEVEL() for the interrupt level.
+ *
+ * @par Notes
+ * This function is used by bindings from languages other than C and C++.
*/
rtems_mode rtems_interrupt_level_body( uint32_t level );
diff --git a/cpukit/include/rtems/rtems/object.h b/cpukit/include/rtems/rtems/object.h
index aee6d5c..b6aabe7 100644
--- a/cpukit/include/rtems/rtems/object.h
+++ b/cpukit/include/rtems/rtems/object.h
@@ -145,8 +145,6 @@ typedef struct {
* @brief Builds the object identifier with the lowest index from the API,
* class, and MPCI node components.
*
- * This directive is strictly local and does not impact task scheduling.
- *
* @param _api is the API of the object identifier to build.
*
* @param _class is the class of the object identifier to build.
@@ -155,6 +153,9 @@ typedef struct {
*
* @return Returns the object identifier with the lowest index built from the
* API, class, and MPCI node components.
+ *
+ * @par Notes
+ * This directive is strictly local and does not impact task scheduling.
*/
#define RTEMS_OBJECT_ID_INITIAL( _api, _class, _node ) \
OBJECTS_ID_INITIAL( _api, _class, _node )
@@ -217,8 +218,6 @@ typedef struct {
* @brief Builds the object identifier from the API, class, MPCI node, and
* index components.
*
- * This directive is strictly local and does not impact task scheduling.
- *
* @param _api is the API of the object identifier to build.
*
* @param _class is the class of the object identifier to build.
@@ -229,6 +228,9 @@ typedef struct {
*
* @return Returns the object identifier built from the API, class, MPCI node,
* and index components.
+ *
+ * @par Notes
+ * This directive is strictly local and does not impact task scheduling.
*/
#define rtems_build_id( _api, _class, _node, _index ) \
_Objects_Build_id( _api, _class, _node, _index )
@@ -240,12 +242,6 @@ typedef struct {
*
* @brief Builds the object name composed of the four characters.
*
- * This directive takes the four characters provided as arguments and composes
- * a 32-bit object name with ``_c1`` in the most significant 8-bits and ``_c4``
- * in the least significant 8-bits.
- *
- * This directive is strictly local and does not impact task scheduling.
- *
* @param _c1 is the first character of the name.
*
* @param _c2 is the second character of the name.
@@ -254,7 +250,14 @@ typedef struct {
*
* @param _c4 is the fourth character of the name.
*
+ * This directive takes the four characters provided as arguments and composes
+ * a 32-bit object name with ``_c1`` in the most significant 8-bits and ``_c4``
+ * in the least significant 8-bits.
+ *
* @return Returns the object name composed of the four characters.
+ *
+ * @par Notes
+ * This directive is strictly local and does not impact task scheduling.
*/
#define rtems_build_name( _c1, _c2, _c3, _c4 ) \
_Objects_Build_name( _c1, _c2, _c3, _c4 )
@@ -266,8 +269,6 @@ typedef struct {
*
* @brief Gets the object name associated with the object identifier.
*
- * This directive is strictly local and does not impact task scheduling.
- *
* @param id is the object identifier to get the name.
*
* @param[out] name is the pointer to an object name variable. The object name
@@ -286,6 +287,9 @@ typedef struct {
*
* @retval ::RTEMS_INVALID_ID There was no object associated with the object
* identifier.
+ *
+ * @par Notes
+ * This directive is strictly local and does not impact task scheduling.
*/
rtems_status_code rtems_object_get_classic_name(
rtems_id id,
@@ -300,6 +304,12 @@ rtems_status_code rtems_object_get_classic_name(
* @brief Gets the object name associated with the object identifier as a
* string.
*
+ * @param id is the object identifier to get the name.
+ *
+ * @param length is the buffer length in bytes.
+ *
+ * @param[out] name is the pointer to a buffer of the specified length.
+ *
* The object name is stored in the name buffer. If the name buffer length is
* greater than zero, then the stored object name will be ``NUL`` terminated.
* The stored object name may be truncated to fit the length. There is no
@@ -307,15 +317,6 @@ rtems_status_code rtems_object_get_classic_name(
* as a printable string even if the object has the Classic API 32-bit integer
* style name.
*
- * This directive may cause the calling task to be preempted due to an obtain
- * and release of the object allocator mutex.
- *
- * @param id is the object identifier to get the name.
- *
- * @param length is the buffer length in bytes.
- *
- * @param[out] name is the pointer to a buffer of the specified length.
- *
* @retval NULL The ``length`` parameter was 0.
*
* @retval NULL The ``name`` parameter was NULL.
@@ -327,6 +328,10 @@ rtems_status_code rtems_object_get_classic_name(
*
* @return Returns the ``name`` parameter value, if there is an object name
* associated with the object identifier.
+ *
+ * @par Notes
+ * This directive may cause the calling task to be preempted due to an obtain
+ * and release of the object allocator mutex.
*/
char *rtems_object_get_name( rtems_id id, size_t length, char *name );
@@ -338,27 +343,12 @@ char *rtems_object_get_name( rtems_id id, size_t length, char *name );
* @brief Sets the object name of the object associated with the object
* identifier.
*
- * This directive will set the object name based upon the user string.
- *
- * This directive may cause the calling task to be preempted due to an obtain
- * and release of the object allocator mutex.
- *
- * This directive can be used to set the name of objects which do not have a
- * naming scheme per their API.
- *
- * If the object specified by ``id`` is of a class that has a string name, this
- * directive will free the existing name to the RTEMS Workspace and allocate
- * enough memory from the RTEMS Workspace to make a copy of the string located
- * at ``name``.
- *
- * If the object specified by ``id`` is of a class that has a 32-bit integer
- * style name, then the first four characters in ``name`` will be used to
- * construct the name.
- *
* @param id is the object identifier of the object to set the name.
*
* @param name is the object name to set.
*
+ * This directive will set the object name based upon the user string.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_ADDRESS The ``name`` parameter was NULL.
@@ -371,6 +361,24 @@ char *rtems_object_get_name( rtems_id id, size_t length, char *name );
*
* @retval ::RTEMS_NO_MEMORY There was no memory available to duplicate the
* name.
+ *
+ * @par Notes
+ * @parblock
+ * This directive may cause the calling task to be preempted due to an obtain
+ * and release of the object allocator mutex.
+ *
+ * This directive can be used to set the name of objects which do not have a
+ * naming scheme per their API.
+ *
+ * If the object specified by ``id`` is of a class that has a string name, this
+ * directive will free the existing name to the RTEMS Workspace and allocate
+ * enough memory from the RTEMS Workspace to make a copy of the string located
+ * at ``name``.
+ *
+ * If the object specified by ``id`` is of a class that has a 32-bit integer
+ * style name, then the first four characters in ``name`` will be used to
+ * construct the name.
+ * @endparblock
*/
rtems_status_code rtems_object_set_name( rtems_id id, const char *name );
@@ -381,15 +389,18 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name );
*
* @brief Gets the API component of the object identifier.
*
+ * @param _id is the object identifier with the API component to get.
+ *
+ * @return Returns the API component of the object identifier.
+ *
+ * @par Notes
+ * @parblock
* This directive is strictly local and does not impact task scheduling.
*
* This directive does not validate the object identifier provided in ``_id``.
*
* A body is also provided.
- *
- * @param _id is the object identifier with the API component to get.
- *
- * @return Returns the API component of the object identifier.
+ * @endparblock
*/
#define rtems_object_id_get_api( _id ) _Objects_Get_API( _id )
@@ -400,15 +411,18 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name );
*
* @brief Gets the class component of the object identifier.
*
+ * @param _id is the object identifier with the class component to get.
+ *
+ * @return Returns the class component of the object identifier.
+ *
+ * @par Notes
+ * @parblock
* This directive is strictly local and does not impact task scheduling.
*
* This directive does not validate the object identifier provided in ``_id``.
*
* A body is also provided.
- *
- * @param _id is the object identifier with the class component to get.
- *
- * @return Returns the class component of the object identifier.
+ * @endparblock
*/
#define rtems_object_id_get_class( _id ) _Objects_Get_class( _id )
@@ -419,15 +433,18 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name );
*
* @brief Gets the MPCI node component of the object identifier.
*
+ * @param _id is the object identifier with the MPCI node component to get.
+ *
+ * @return Returns the MPCI node component of the object identifier.
+ *
+ * @par Notes
+ * @parblock
* This directive is strictly local and does not impact task scheduling.
*
* This directive does not validate the object identifier provided in ``_id``.
*
* A body is also provided.
- *
- * @param _id is the object identifier with the MPCI node component to get.
- *
- * @return Returns the MPCI node component of the object identifier.
+ * @endparblock
*/
#define rtems_object_id_get_node( _id ) _Objects_Get_node( _id )
@@ -438,15 +455,18 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name );
*
* @brief Gets the index component of the object identifier.
*
+ * @param _id is the object identifier with the index component to get.
+ *
+ * @return Returns the index component of the object identifier.
+ *
+ * @par Notes
+ * @parblock
* This directive is strictly local and does not impact task scheduling.
*
* This directive does not validate the object identifier provided in ``_id``.
*
* A body is also provided.
- *
- * @param _id is the object identifier with the index component to get.
- *
- * @return Returns the index component of the object identifier.
+ * @endparblock
*/
#define rtems_object_id_get_index( _id ) _Objects_Get_index( _id )
@@ -458,12 +478,15 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name );
* @brief Gets the lowest valid value for the API component of an object
* identifier.
*
+ * @return Returns the lowest valid value for the API component of an object
+ * identifier.
+ *
+ * @par Notes
+ * @parblock
* This directive is strictly local and does not impact task scheduling.
*
* A body is also provided.
- *
- * @return Returns the lowest valid value for the API component of an object
- * identifier.
+ * @endparblock
*/
#define rtems_object_id_api_minimum() OBJECTS_INTERNAL_API
@@ -475,12 +498,15 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name );
* @brief Gets the highest valid value for the API component of an object
* identifier.
*
+ * @return Returns the highest valid value for the API component of an object
+ * identifier.
+ *
+ * @par Notes
+ * @parblock
* This directive is strictly local and does not impact task scheduling.
*
* A body is also provided.
- *
- * @return Returns the highest valid value for the API component of an object
- * identifier.
+ * @endparblock
*/
#define rtems_object_id_api_maximum() OBJECTS_APIS_LAST
@@ -491,13 +517,14 @@ rtems_status_code rtems_object_set_name( rtems_id id, const char *name );
*
* @brief Gets the lowest valid class value of the object API.
*
- * This directive is strictly local and does not impact task scheduling.
- *
* @param api is the object API to get the lowest valid class value.
*
* @retval -1 The object API was invalid.
*
* @return Returns the lowest valid class value of the object API.
+ *
+ * @par Notes
+ * This directive is strictly local and does not impact task scheduling.
*/
int rtems_object_api_minimum_class( int api );
@@ -508,13 +535,14 @@ int rtems_object_api_minimum_class( int api );
*
* @brief Gets the highest valid class value of the object API.
*
- * This directive is strictly local and does not impact task scheduling.
- *
* @param api is the object API to get the highest valid class value.
*
* @retval 0 The object API was invalid.
*
* @return Returns the highest valid class value of the object API.
+ *
+ * @par Notes
+ * This directive is strictly local and does not impact task scheduling.
*/
int rtems_object_api_maximum_class( int api );
@@ -525,15 +553,18 @@ int rtems_object_api_maximum_class( int api );
*
* @brief Gets a descriptive name of the object API.
*
- * This directive is strictly local and does not impact task scheduling.
- *
- * The string returned is from constant space. Do not modify or free it.
- *
* @param api is the object API to get the name.
*
* @retval "BAD API" The API was invalid.
*
* @return Returns a descriptive name of the API, if the API was valid.
+ *
+ * @par Notes
+ * @parblock
+ * This directive is strictly local and does not impact task scheduling.
+ *
+ * The string returned is from constant space. Do not modify or free it.
+ * @endparblock
*/
const char *rtems_object_get_api_name( int api );
@@ -544,10 +575,6 @@ const char *rtems_object_get_api_name( int api );
*
* @brief Gets a descriptive name of the object class of the object API.
*
- * This directive is strictly local and does not impact task scheduling.
- *
- * The string returned is from constant space. Do not modify or free it.
- *
* @param the_api is the object API of the object class.
*
* @param the_class is the object class of the object API to get the name.
@@ -558,6 +585,13 @@ const char *rtems_object_get_api_name( int api );
*
* @return Returns a descriptive name of the class of the API, if the class of
* the API and the API were valid.
+ *
+ * @par Notes
+ * @parblock
+ * This directive is strictly local and does not impact task scheduling.
+ *
+ * The string returned is from constant space. Do not modify or free it.
+ * @endparblock
*/
const char *rtems_object_get_api_class_name( int the_api, int the_class );
@@ -569,8 +603,6 @@ const char *rtems_object_get_api_class_name( int the_api, int the_class );
* @brief Gets the object class information of the object class of the object
* API.
*
- * This directive is strictly local and does not impact task scheduling.
- *
* @param the_api is the object API of the object class.
*
* @param the_class is the object class of the object API to get the class
@@ -585,6 +617,9 @@ const char *rtems_object_get_api_class_name( int the_api, int the_class );
* @retval ::RTEMS_INVALID_ADDRESS The ``info`` parameter was NULL.
*
* @retval ::RTEMS_INVALID_NUMBER The class of the API or the API was invalid.
+ *
+ * @par Notes
+ * This directive is strictly local and does not impact task scheduling.
*/
rtems_status_code rtems_object_get_class_information(
int the_api,
@@ -599,9 +634,10 @@ rtems_status_code rtems_object_get_class_information(
*
* @brief Gets the local MPCI node number.
*
- * This directive is strictly local and does not impact task scheduling.
- *
* @return Returns the local MPCI node number.
+ *
+ * @par Notes
+ * This directive is strictly local and does not impact task scheduling.
*/
static inline uint16_t rtems_object_get_local_node( void )
{
diff --git a/cpukit/include/rtems/rtems/part.h b/cpukit/include/rtems/rtems/part.h
index 5a747f4..4979f8a 100644
--- a/cpukit/include/rtems/rtems/part.h
+++ b/cpukit/include/rtems/rtems/part.h
@@ -86,6 +86,7 @@ extern "C" {
* @brief This constant defines the minimum alignment of a partition buffer in
* bytes.
*
+ * @par Notes
* Use it with RTEMS_ALIGNED() to define the alignment of partition buffer
* types or statically allocated partition buffer areas.
*/
@@ -98,6 +99,23 @@ extern "C" {
*
* @brief Creates a partition.
*
+ * @param name is the name of the partition.
+ *
+ * @param starting_address is the starting address of the buffer area used by
+ * the partition.
+ *
+ * @param length is the length in bytes of the buffer area used by the
+ * partition.
+ *
+ * @param buffer_size is the size in bytes of a buffer managed by the
+ * partition.
+ *
+ * @param attribute_set is the attribute set of the partition.
+ *
+ * @param[out] id is the pointer to an object identifier variable. The
+ * identifier of the created partition object will be stored in this
+ * variable, in case of a successful operation.
+ *
* This directive creates a partition of fixed size buffers from a physically
* contiguous memory space which starts at ``starting_address`` and is
* ``length`` bytes in size. Each allocated buffer is to be of ``buffer_size``
@@ -120,6 +138,34 @@ extern "C" {
* The memory space used for the partition must reside in shared memory.
* Setting the global attribute in a single node system has no effect.
*
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NAME The partition name was invalid.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The ``length`` parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The ``buffer_size`` parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The ``length`` parameter was less than the
+ * ``buffer_size`` parameter.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The ``buffer_size`` parameter was not an
+ * integral multiple of the pointer size.
+ *
+ * @retval ::RTEMS_INVALID_SIZE The ``buffer_size`` parameter was less than two
+ * times the pointer size.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``starting_address`` parameter was not
+ * on a pointer size boundary.
+ *
+ * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
+ * new partition. The number of partitions available to the application is
+ * configured through the #CONFIGURE_MAXIMUM_PARTITIONS configuration option.
+ *
+ * @par Notes
+ * @parblock
* This directive may cause the calling task to be preempted due to an obtain
* and release of the object allocator mutex.
*
@@ -151,49 +197,7 @@ extern "C" {
* The total number of global objects, including partitions, is limited by the
* value of the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration
* option.
- *
- * @param name is the name of the partition.
- *
- * @param starting_address is the starting address of the buffer area used by
- * the partition.
- *
- * @param length is the length in bytes of the buffer area used by the
- * partition.
- *
- * @param buffer_size is the size in bytes of a buffer managed by the
- * partition.
- *
- * @param attribute_set is the attribute set of the partition.
- *
- * @param[out] id is the pointer to an object identifier variable. The
- * identifier of the created partition object will be stored in this
- * variable, in case of a successful operation.
- *
- * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
- *
- * @retval ::RTEMS_INVALID_NAME The partition name was invalid.
- *
- * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
- *
- * @retval ::RTEMS_INVALID_SIZE The ``length`` parameter was 0.
- *
- * @retval ::RTEMS_INVALID_SIZE The ``buffer_size`` parameter was 0.
- *
- * @retval ::RTEMS_INVALID_SIZE The ``length`` parameter was less than the
- * ``buffer_size`` parameter.
- *
- * @retval ::RTEMS_INVALID_SIZE The ``buffer_size`` parameter was not an
- * integral multiple of the pointer size.
- *
- * @retval ::RTEMS_INVALID_SIZE The ``buffer_size`` parameter was less than two
- * times the pointer size.
- *
- * @retval ::RTEMS_INVALID_ADDRESS The ``starting_address`` parameter was not
- * on a pointer size boundary.
- *
- * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
- * new partition. The number of partitions available to the application is
- * configured through the #CONFIGURE_MAXIMUM_PARTITIONS configuration option.
+ * @endparblock
*/
rtems_status_code rtems_partition_create(
rtems_name name,
@@ -211,6 +215,14 @@ rtems_status_code rtems_partition_create(
*
* @brief Identifies a partition by the object name.
*
+ * @param name is the object name to look up.
+ *
+ * @param node is the node or node set to search for a matching object.
+ *
+ * @param[out] id is the pointer to an object identifier variable. The object
+ * identifier of an object with the specified name will be stored in this
+ * variable, in case of a successful operation.
+ *
* This directive obtains a partition identifier associated with the partition
* name specified in ``name``.
*
@@ -225,6 +237,20 @@ rtems_status_code rtems_partition_create(
* * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the
* local node.
*
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ * the specified nodes.
+ *
+ * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the
+ * specified node was invalid.
+ *
+ * @par Notes
+ * @parblock
* If the partition name is not unique, then the partition identifier will
* match the first partition with that name in the search order. However, this
* partition identifier is not guaranteed to correspond to the desired
@@ -240,26 +266,7 @@ rtems_status_code rtems_partition_create(
*
* This directive does not generate activity on remote nodes. It accesses only
* the local copy of the global object table.
- *
- * @param name is the object name to look up.
- *
- * @param node is the node or node set to search for a matching object.
- *
- * @param[out] id is the pointer to an object identifier variable. The object
- * identifier of an object with the specified name will be stored in this
- * variable, in case of a successful operation.
- *
- * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
- *
- * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
- *
- * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
- *
- * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
- * the specified nodes.
- *
- * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the
- * specified node was invalid.
+ * @endparblock
*/
rtems_status_code rtems_partition_ident(
rtems_name name,
@@ -274,9 +281,24 @@ rtems_status_code rtems_partition_ident(
*
* @brief Deletes the partition.
*
+ * @param id is the partition identifier.
+ *
* This directive deletes the partition specified by the ``id`` parameter. The
* partition cannot be deleted if any of its buffers are still allocated.
*
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no partition associated with the
+ * identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The partition resided on a remote
+ * node.
+ *
+ * @retval ::RTEMS_RESOURCE_IN_USE There were buffers of the partition still in
+ * use.
+ *
+ * @par Notes
+ * @parblock
* This directive may cause the calling task to be preempted due to an obtain
* and release of the object allocator mutex.
*
@@ -291,19 +313,7 @@ rtems_status_code rtems_partition_ident(
*
* The partition must reside on the local node, even if the partition was
* created with the #RTEMS_GLOBAL attribute.
- *
- * @param id is the partition identifier.
- *
- * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
- *
- * @retval ::RTEMS_INVALID_ID There was no partition associated with the
- * identifier specified by ``id``.
- *
- * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The partition resided on a remote
- * node.
- *
- * @retval ::RTEMS_RESOURCE_IN_USE There were buffers of the partition still in
- * use.
+ * @endparblock
*/
rtems_status_code rtems_partition_delete( rtems_id id );
@@ -314,27 +324,16 @@ rtems_status_code rtems_partition_delete( rtems_id id );
*
* @brief Tries to get a buffer from the partition.
*
- * This directive allows a buffer to be obtained from the partition specified
- * in the ``id`` parameter. The address of the allocated buffer is returned
- * through the ``buffer`` parameter.
- *
- * This directive will not cause the running task to be preempted.
- *
- * The buffer start alignment is determined by the memory area and buffer size
- * used to create the partition.
- *
- * A task cannot wait on a buffer to become available.
- *
- * Getting a buffer from a global partition which does not reside on the local
- * node will generate a request telling the remote node to allocate a buffer
- * from the partition.
- *
* @param id is the partition identifier.
*
* @param[out] buffer is the pointer to a buffer pointer variable. The pointer
* to the allocated buffer will be stored in this variable, in case of a
* successful operation.
*
+ * This directive allows a buffer to be obtained from the partition specified
+ * in the ``id`` parameter. The address of the allocated buffer is returned
+ * through the ``buffer`` parameter.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_ID There was no partition associated with the
@@ -344,6 +343,20 @@ rtems_status_code rtems_partition_delete( rtems_id id );
*
* @retval ::RTEMS_UNSATISFIED There was no free buffer available to allocate
* and return.
+ *
+ * @par Notes
+ * @parblock
+ * This directive will not cause the running task to be preempted.
+ *
+ * The buffer start alignment is determined by the memory area and buffer size
+ * used to create the partition.
+ *
+ * A task cannot wait on a buffer to become available.
+ *
+ * Getting a buffer from a global partition which does not reside on the local
+ * node will generate a request telling the remote node to allocate a buffer
+ * from the partition.
+ * @endparblock
*/
rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer );
@@ -354,22 +367,13 @@ rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer );
*
* @brief Returns the buffer to the partition.
*
- * This directive returns the buffer specified by ``buffer`` to the partition
- * specified by ``id``.
- *
- * This directive will not cause the running task to be preempted.
- *
- * Returning a buffer to a global partition which does not reside on the local
- * node will generate a request telling the remote node to return the buffer to
- * the partition.
- *
- * Returning a buffer multiple times is an error. It will corrupt the internal
- * state of the partition.
- *
* @param id is the partition identifier.
*
* @param buffer is the pointer to the buffer to return.
*
+ * This directive returns the buffer specified by ``buffer`` to the partition
+ * specified by ``id``.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_ID There was no partition associated with the
@@ -377,6 +381,18 @@ rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer );
*
* @retval ::RTEMS_INVALID_ADDRESS The buffer referenced by ``buffer`` was not
* in the partition.
+ *
+ * @par Notes
+ * @parblock
+ * This directive will not cause the running task to be preempted.
+ *
+ * Returning a buffer to a global partition which does not reside on the local
+ * node will generate a request telling the remote node to return the buffer to
+ * the partition.
+ *
+ * Returning a buffer multiple times is an error. It will corrupt the internal
+ * state of the partition.
+ * @endparblock
*/
rtems_status_code rtems_partition_return_buffer( rtems_id id, void *buffer );
diff --git a/cpukit/include/rtems/rtems/status.h b/cpukit/include/rtems/rtems/status.h
index 3575244..872bb9b 100644
--- a/cpukit/include/rtems/rtems/status.h
+++ b/cpukit/include/rtems/rtems/status.h
@@ -252,6 +252,7 @@ typedef enum {
* This is referred to as proxying operations and this status indicates that
* the operation could not be completed immediately and the proxy is blocking.
*
+ * @par Notes
* This status will not be returned to the user.
*/
RTEMS_PROXY_BLOCKING = 29
@@ -364,10 +365,10 @@ static inline bool rtems_is_status_successful( rtems_status_code status_code )
*
* @brief Maps the status code to a descriptive text.
*
- * The text for each status code is the enumerator constant.
- *
* @param status_code is the status code.
*
+ * The text for each status code is the enumerator constant.
+ *
* @retval "?" The status code is invalid.
*
* @return Returns a text describing the status code, if the status code is
diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h
index fe22eef..23a69b5 100644
--- a/cpukit/include/rtems/rtems/timer.h
+++ b/cpukit/include/rtems/rtems/timer.h
@@ -190,22 +190,23 @@ typedef struct {
*
* @brief Gets information about the timer.
*
- * This directive returns information about the timer.
- *
- * This directive will not cause the running task to be preempted.
- *
* @param id is the timer identifier.
*
* @param[out] the_info is the pointer to a timer information variable. The
* information about the timer will be stored in this variable, in case of a
* successful operation.
*
+ * This directive returns information about the timer.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL.
*
* @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
* specified by ``id``.
+ *
+ * @par Notes
+ * This directive will not cause the running task to be preempted.
*/
rtems_status_code rtems_timer_get_information(
rtems_id id,
@@ -254,26 +255,16 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem
*
* @brief Creates a timer.
*
- * This directive creates a timer. The assigned object identifier is returned
- * in ``id``. This identifier is used to access the timer with other timer
- * related directives.
- *
- * This directive may cause the calling task to be preempted due to an obtain
- * and release of the object allocator mutex.
- *
- * For control and maintenance of the timer, RTEMS allocates a TMCB from the
- * local TMCB free pool and initializes it.
- *
- * In SMP configurations, the processor of the currently executing thread
- * determines the processor used for the created timer. During the life-time
- * of the timer this processor is used to manage the timer internally.
- *
* @param name is the name of the timer.
*
* @param[out] id is the pointer to an object identifier variable. The
* identifier of the created timer object will be stored in this variable, in
* case of a successful operation.
*
+ * This directive creates a timer. The assigned object identifier is returned
+ * in ``id``. This identifier is used to access the timer with other timer
+ * related directives.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_NAME The timer name was invalid.
@@ -283,6 +274,19 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem
* @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
* new timer. The number of timers available to the application is
* configured through the #CONFIGURE_MAXIMUM_TIMERS configuration option.
+ *
+ * @par Notes
+ * @parblock
+ * This directive may cause the calling task to be preempted due to an obtain
+ * and release of the object allocator mutex.
+ *
+ * For control and maintenance of the timer, RTEMS allocates a TMCB from the
+ * local TMCB free pool and initializes it.
+ *
+ * In SMP configurations, the processor of the currently executing thread
+ * determines the processor used for the created timer. During the life-time
+ * of the timer this processor is used to manage the timer internally.
+ * @endparblock
*/
rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );
@@ -293,23 +297,15 @@ rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );
*
* @brief Identifies a timer by the object name.
*
- * This directive obtains the timer identifier associated with the timer name
- * specified in ``name``.
- *
- * If the timer name is not unique, then the timer identifier will match the
- * first timer with that name in the search order. However, this timer
- * identifier is not guaranteed to correspond to the desired timer. The timer
- * identifier is used with other timer related directives to access the timer.
- *
- * The objects are searched from lowest to the highest index. Only the local
- * node is searched.
- *
* @param name is the object name to look up.
*
* @param[out] id is the pointer to an object identifier variable. The object
* identifier of an object with the specified name will be stored in this
* variable, in case of a successful operation.
*
+ * This directive obtains the timer identifier associated with the timer name
+ * specified in ``name``.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
@@ -318,6 +314,17 @@ rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );
*
* @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
* the local node.
+ *
+ * @par Notes
+ * @parblock
+ * If the timer name is not unique, then the timer identifier will match the
+ * first timer with that name in the search order. However, this timer
+ * identifier is not guaranteed to correspond to the desired timer. The timer
+ * identifier is used with other timer related directives to access the timer.
+ *
+ * The objects are searched from lowest to the highest index. Only the local
+ * node is searched.
+ * @endparblock
*/
rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id );
@@ -328,19 +335,20 @@ rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id );
*
* @brief Cancels the timer.
*
+ * @param id is the timer identifier.
+ *
* This directive cancels the timer specified in the ``id`` parameter. This
* timer will be reinitiated by the next invocation of rtems_timer_reset(),
* rtems_timer_fire_after(), or rtems_timer_fire_when() with the same timer
* identifier.
*
- * This directive will not cause the running task to be preempted.
- *
- * @param id is the timer identifier.
- *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
* specified by ``id``.
+ *
+ * @par Notes
+ * This directive will not cause the running task to be preempted.
*/
rtems_status_code rtems_timer_cancel( rtems_id id );
@@ -351,9 +359,18 @@ rtems_status_code rtems_timer_cancel( rtems_id id );
*
* @brief Deletes the timer.
*
+ * @param id is the timer identifier.
+ *
* This directive deletes the timer specified by the ``id`` parameter. If the
* timer is running, it is automatically canceled.
*
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
+ * specified by ``id``.
+ *
+ * @par Notes
+ * @parblock
* This directive may cause the calling task to be preempted due to an obtain
* and release of the object allocator mutex.
*
@@ -361,13 +378,7 @@ rtems_status_code rtems_timer_cancel( rtems_id id );
*
* A timer can be deleted by a task other than the task which created the
* timer.
- *
- * @param id is the timer identifier.
- *
- * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
- *
- * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
- * specified by ``id``.
+ * @endparblock
*/
rtems_status_code rtems_timer_delete( rtems_id id );
@@ -378,15 +389,6 @@ rtems_status_code rtems_timer_delete( rtems_id id );
*
* @brief Fires the timer after the interval.
*
- * This directive initiates the timer specified by ``id``. If the timer is
- * running, it is automatically canceled before being initiated. The timer is
- * scheduled to fire after an interval of clock ticks has passed specified by
- * ``ticks``. When the timer fires, the timer service routine ``routine`` will
- * be invoked with the argument ``user_data`` in the context of the clock tick
- * ISR.
- *
- * This directive will not cause the running task to be preempted.
- *
* @param id is the timer identifier.
*
* @param ticks is the interval until the routine is fired in clock ticks.
@@ -395,6 +397,13 @@ rtems_status_code rtems_timer_delete( rtems_id id );
*
* @param user_data is the argument passed to the routine when it is fired.
*
+ * This directive initiates the timer specified by ``id``. If the timer is
+ * running, it is automatically canceled before being initiated. The timer is
+ * scheduled to fire after an interval of clock ticks has passed specified by
+ * ``ticks``. When the timer fires, the timer service routine ``routine`` will
+ * be invoked with the argument ``user_data`` in the context of the clock tick
+ * ISR.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INVALID_NUMBER The ``ticks`` parameter was 0.
@@ -403,6 +412,9 @@ rtems_status_code rtems_timer_delete( rtems_id id );
*
* @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
* specified by ``id``.
+ *
+ * @par Notes
+ * This directive will not cause the running task to be preempted.
*/
rtems_status_code rtems_timer_fire_after(
rtems_id id,
@@ -418,14 +430,6 @@ rtems_status_code rtems_timer_fire_after(
*
* @brief Fires the timer at the time of day.
*
- * This directive initiates the timer specified by ``id``. If the timer is
- * running, it is automatically canceled before being initiated. The timer is
- * scheduled to fire at the time of day specified by ``wall_time``. When the
- * timer fires, the timer service routine ``routine`` will be invoked with the
- * argument ``user_data`` in the context of the clock tick ISR.
- *
- * This directive will not cause the running task to be preempted.
- *
* @param id is the timer identifier.
*
* @param wall_time is the time of day when the routine is fired.
@@ -434,6 +438,12 @@ rtems_status_code rtems_timer_fire_after(
*
* @param user_data is the argument passed to the routine when it is fired.
*
+ * This directive initiates the timer specified by ``id``. If the timer is
+ * running, it is automatically canceled before being initiated. The timer is
+ * scheduled to fire at the time of day specified by ``wall_time``. When the
+ * timer fires, the timer service routine ``routine`` will be invoked with the
+ * argument ``user_data`` in the context of the clock tick ISR.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_NOT_DEFINED The system date and time was not set.
@@ -446,6 +456,9 @@ rtems_status_code rtems_timer_fire_after(
*
* @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
* specified by ``id``.
+ *
+ * @par Notes
+ * This directive will not cause the running task to be preempted.
*/
rtems_status_code rtems_timer_fire_when(
rtems_id id,
@@ -461,22 +474,16 @@ rtems_status_code rtems_timer_fire_when(
*
* @brief Initiates the Timer Server.
*
- * This directive initiates the Timer Server task. This task is responsible
- * for executing all timers initiated via the rtems_timer_server_fire_after()
- * or rtems_timer_server_fire_when() directives.
- *
- * This directive may cause the calling task to be preempted due to an obtain
- * and release of the object allocator mutex.
- *
- * The Timer Server task is created using the rtems_task_create() directive and
- * must be accounted for when configuring the system.
- *
* @param priority is the task priority.
*
* @param stack_size is the task stack size in bytes.
*
* @param attribute_set is the task attribute set.
*
+ * This directive initiates the Timer Server task. This task is responsible
+ * for executing all timers initiated via the rtems_timer_server_fire_after()
+ * or rtems_timer_server_fire_when() directives.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INCORRECT_STATE The Timer Server was already initiated.
@@ -492,6 +499,15 @@ rtems_status_code rtems_timer_fire_when(
*
* @retval ::RTEMS_UNSATISFIED One of the task create extensions failed to
* create the Timer Server task.
+ *
+ * @par Notes
+ * @parblock
+ * This directive may cause the calling task to be preempted due to an obtain
+ * and release of the object allocator mutex.
+ *
+ * The Timer Server task is created using the rtems_task_create() directive and
+ * must be accounted for when configuring the system.
+ * @endparblock
*/
rtems_status_code rtems_timer_initiate_server(
rtems_task_priority priority,
@@ -506,15 +522,6 @@ rtems_status_code rtems_timer_initiate_server(
*
* @brief Fires the timer after the interval using the Timer Server.
*
- * This directive initiates the timer specified by ``id``. If the timer is
- * running, it is automatically canceled before being initiated. The timer is
- * scheduled to fire after an interval of clock ticks has passed specified by
- * ``ticks``. When the timer fires, the timer service routine ``routine`` will
- * be invoked with the argument ``user_data`` in the context of the Timer
- * Server task.
- *
- * This directive will not cause the running task to be preempted.
- *
* @param id is the timer identifier.
*
* @param ticks is the interval until the routine is fired in clock ticks.
@@ -523,6 +530,13 @@ rtems_status_code rtems_timer_initiate_server(
*
* @param user_data is the argument passed to the routine when it is fired.
*
+ * This directive initiates the timer specified by ``id``. If the timer is
+ * running, it is automatically canceled before being initiated. The timer is
+ * scheduled to fire after an interval of clock ticks has passed specified by
+ * ``ticks``. When the timer fires, the timer service routine ``routine`` will
+ * be invoked with the argument ``user_data`` in the context of the Timer
+ * Server task.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated.
@@ -533,6 +547,9 @@ rtems_status_code rtems_timer_initiate_server(
*
* @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
* specified by ``id``.
+ *
+ * @par Notes
+ * This directive will not cause the running task to be preempted.
*/
rtems_status_code rtems_timer_server_fire_after(
rtems_id id,
@@ -548,14 +565,6 @@ rtems_status_code rtems_timer_server_fire_after(
*
* @brief Fires the timer at the time of day using the Timer Server.
*
- * This directive initiates the timer specified by ``id``. If the timer is
- * running, it is automatically canceled before being initiated. The timer is
- * scheduled to fire at the time of day specified by ``wall_time``. When the
- * timer fires, the timer service routine ``routine`` will be invoked with the
- * argument ``user_data`` in the context of the Timer Server task.
- *
- * This directive will not cause the running task to be preempted.
- *
* @param id is the timer identifier.
*
* @param wall_time is the time of day when the routine is fired.
@@ -564,6 +573,12 @@ rtems_status_code rtems_timer_server_fire_after(
*
* @param user_data is the argument passed to the routine when it is fired.
*
+ * This directive initiates the timer specified by ``id``. If the timer is
+ * running, it is automatically canceled before being initiated. The timer is
+ * scheduled to fire at the time of day specified by ``wall_time``. When the
+ * timer fires, the timer service routine ``routine`` will be invoked with the
+ * argument ``user_data`` in the context of the Timer Server task.
+ *
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
* @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated.
@@ -578,6 +593,9 @@ rtems_status_code rtems_timer_server_fire_after(
*
* @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
* specified by ``id``.
+ *
+ * @par Notes
+ * This directive will not cause the running task to be preempted.
*/
rtems_status_code rtems_timer_server_fire_when(
rtems_id id,
@@ -593,6 +611,8 @@ rtems_status_code rtems_timer_server_fire_when(
*
* @brief Resets the timer.
*
+ * @param id is the timer identifier.
+ *
* This directive resets the timer specified by ``id``. This timer must have
* been previously initiated with either the rtems_timer_fire_after() or
* rtems_timer_server_fire_after() directive. If active the timer is canceled,
@@ -600,6 +620,15 @@ rtems_status_code rtems_timer_server_fire_when(
* service routine which the original rtems_timer_fire_after() or
* rtems_timer_server_fire_after() directive used.
*
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
+ * specified by ``id``.
+ *
+ * @retval ::RTEMS_NOT_DEFINED The timer was not of the interval class.
+ *
+ * @par Notes
+ * @parblock
* This directive will not cause the running task to be preempted.
*
* If the timer has not been used or the last usage of this timer was by a
@@ -608,15 +637,7 @@ rtems_status_code rtems_timer_server_fire_when(
*
* Restarting a cancelled after timer results in the timer being reinitiated
* with its previous timer service routine and interval.
- *
- * @param id is the timer identifier.
- *
- * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
- *
- * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
- * specified by ``id``.
- *
- * @retval ::RTEMS_NOT_DEFINED The timer was not of the interval class.
+ * @endparblock
*/
rtems_status_code rtems_timer_reset( rtems_id id );
diff --git a/cpukit/include/rtems/score/basedefs.h b/cpukit/include/rtems/score/basedefs.h
index d017ffa..a98b80f 100644
--- a/cpukit/include/rtems/score/basedefs.h
+++ b/cpukit/include/rtems/score/basedefs.h
@@ -293,10 +293,10 @@ extern "C" {
*
* @brief Declares a global symbol with the name.
*
- * This macro must be placed at file scope.
- *
* @param _name is the name of the global symbol. It shall be a valid
* designator.
+ *
+ * This macro must be placed at file scope.
*/
#define RTEMS_DECLARE_GLOBAL_SYMBOL( _name ) extern char _name[]
@@ -354,12 +354,12 @@ extern "C" {
*
* @brief Gets the pointer reference type.
*
- * The reference type idea is based on libHX by Jan Engelhardt.
- *
* @param _level is the pointer indirection level expressed in *.
*
* @param _target is the reference target type.
*
+ * The reference type idea is based on libHX by Jan Engelhardt.
+ *
* @return Returns the type of a pointer reference of the specified level to
* the specified type.
*/
@@ -601,9 +601,9 @@ extern "C" {
* @brief Obfuscates the variable so that the compiler cannot perform
* optimizations based on the variable value.
*
- * The variable must be simple enough to fit into a register.
- *
* @param _var is the variable to obfuscate.
+ *
+ * The variable must be simple enough to fit into a register.
*/
#if defined(__GNUC__)
#define RTEMS_OBFUSCATE_VARIABLE( _var ) __asm__( "" : "+r" ( _var ) )
@@ -917,8 +917,6 @@ extern "C" {
*
* @brief Defines a global symbol with the name and value.
*
- * This macro shall be placed at file scope.
- *
* @param _name is the user defined name of the symbol. The name shall be a
* valid designator. On the name a macro expansion is performed and
* afterwards it is stringified.
@@ -926,6 +924,8 @@ extern "C" {
* @param _value is the value of the symbol. On the value a macro expansion is
* performed and afterwards it is stringified. It shall expand to an integer
* expression understood by the assembler.
+ *
+ * This macro shall be placed at file scope.
*/
#if defined(__USER_LABEL_PREFIX__)
#define RTEMS_DEFINE_GLOBAL_SYMBOL( _name, _value ) \
More information about the vc
mailing list