[PATCH] rtems: Add "Notes" paragraph header
Gedare Bloom
gedare at rtems.org
Tue Jan 26 15:42:58 UTC 2021
Looks fine to me.
Some of them don't add the @par notes, is there a rationale for when it
is/isn't there? (It looks like maybe that is for doxygen of macros.)
On Mon, Jan 25, 2021 at 1:32 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:
> 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 cc54a25d9e..a3eec39584 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 445f24cb78..f80d2cebe1 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 baea36aa9f..18a3820e0e 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 76a4a758b9..2a12c8f3cb 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 8aa115762d..a6d0a16f01 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 b711b119b6..559029d2da 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 aee6d5c3ed..b6aabe7c1e 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 5a747f428b..4979f8a987 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 35752442d9..872bb9b2b3 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 fe22eef39d..23a69b5b87 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 d017ffa96a..a98b80f0dd 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 ) \
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20210126/dc3c2c74/attachment-0001.html>
More information about the devel
mailing list