From b35ac9901caac823c5aa4aeeb81c4bb2c6bc58fd Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 25 Jan 2021 09:27:22 +0100 Subject: 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(-) (limited to 'cpukit') 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 ) \ -- cgit v1.2.3