diff options
| author | Joel Sherrill <joel.sherrill@oarcorp.com> | 2013-02-02 15:19:01 -0600 |
|---|---|---|
| committer | Joel Sherrill <joel.sherrill@oarcorp.com> | 2013-02-02 15:19:01 -0600 |
| commit | dd7b83550dfb73f5ec1b7dec3b21d730779ddeb2 (patch) | |
| tree | 3db0eac5b55ed5edcf985baed9f19736c931de47 /cpukit/score/include/rtems | |
| parent | Merge branch 'master' of ssh://git.rtems.org/data/git/rtems (diff) | |
| parent | fstests/fsrdwr: Free allocated memory (diff) | |
| download | rtems-dd7b83550dfb73f5ec1b7dec3b21d730779ddeb2.tar.bz2 | |
Merge branch 'master' of ssh://git.rtems.org/data/git/rtems
Diffstat (limited to 'cpukit/score/include/rtems')
54 files changed, 796 insertions, 591 deletions
diff --git a/cpukit/score/include/rtems/bspsmp.h b/cpukit/score/include/rtems/bspsmp.h index 9c040efeda..d0681ca8f2 100644 --- a/cpukit/score/include/rtems/bspsmp.h +++ b/cpukit/score/include/rtems/bspsmp.h @@ -1,9 +1,11 @@ /** * @file rtems/bspsmp.h * + * @brief Interface Between RTEMS and an SMP Aware BSP + * * This include file defines the interface between RTEMS and an * SMP aware BSP. These methods will only be used when RTEMS - * is configured with SMP support enabled. + * is configured with SMP support enabled. */ /* @@ -24,8 +26,10 @@ /** * @defgroup RTEMS BSP SMP Interface * + * @ingroup Score + * * This defines the interface between RTEMS and the BSP for - * SMP support. The interface uses the term primary + * SMP support. The interface uses the term primary * to refer to the "boot" processor and secondary to refer * to the "application" processors. Different architectures * use different terminology. @@ -45,15 +49,15 @@ extern "C" { #ifndef ASM /** - * @brief Maximum Number of CPUs in SMP System + * @brief Maximum number of CPUs in SMP system. * * This variable is set during the SMP initialization sequence to * indicate the Maximum number of CPUs in this system. */ extern uint32_t rtems_configuration_smp_maximum_processors; - + /** - * @brief Initialize Secondary CPUs + * @brief Initialize secondary CPUs. * * This method is invoked by RTEMS during initialization to bring the * secondary CPUs out of reset. @@ -61,7 +65,7 @@ extern uint32_t rtems_configuration_smp_maximum_processors; * @param [in] maximum is the maximum number of CPU cores that RTEMS * can handle * - * @return This method returns the number of cores available in the + * @retval This method returns the number of cores available in the * system. */ int bsp_smp_initialize( @@ -69,17 +73,17 @@ int bsp_smp_initialize( ); /** - * @brief Obtain Current CPU Index + * @brief Obtain current CPU index. * * This method is invoked by RTEMS when it needs to know the index * of the CPU it is executing on. * - * @return This method returns the current CPU index. + * @retval This method returns the current CPU index. */ int bsp_smp_processor_id(void) RTEMS_COMPILER_PURE_ATTRIBUTE; /** - * @brief Make Request of Another CPU + * @brief Make request of another CPU. * * This method is invoked by RTEMS when it needs to make a request * of another CPU. It should be implemented using some type of @@ -94,21 +98,21 @@ void rtems_smp_send_message( ); /** - * @brief Generate a Interprocessor Broadcast Interrupt + * @brief Generate an interprocessor broadcast interrupt. * * This method is invoked when RTEMS wants to let all of the other - * CPUs know that it has sent them message. CPUs not including + * CPUs know that it has sent them message. CPUs not including * the originating CPU should receive the interrupt. * - * @note On CPUs without the capability to generate a broadcast + * @note On CPUs without the capability to generate a broadcast * to all other CPUs interrupt, this can be implemented by * a loop of sending interrupts to specific CPUs. */ void bsp_smp_broadcast_interrupt(void); /** - * @brief Generate a Interprocessor Interrupt + * @brief Generate a interprocessor interrupt. * * This method is invoked by RTEMS to let @a cpu know that it * has sent it a message. @@ -120,7 +124,7 @@ void bsp_smp_interrupt_cpu( ); /** - * @brief Obtain CPU Core Number + * @brief Obtain CPU core number. * * This method is invoked by RTEMS when it needs to know which core * number it is executing on. This is used when it needs to perform @@ -128,7 +132,7 @@ void bsp_smp_interrupt_cpu( * the other cores. For example, it may need to realize it needs to * preempt a thread on another node. * - * @return This method returns the Id of the current CPU core. + * @retval This method returns the Id of the current CPU core. */ int bsp_smp_processor_id( void ); @@ -143,7 +147,7 @@ int bsp_smp_processor_id( void ); void bsp_smp_secondary_cpu_initialize(int cpu); /** - * @brief RTEMS SMP Secondary CPU Initialize + * @brief Initialize secondary CPU and coordinates. * * This method is the C entry point which secondary CPUs should * arrange to call. It performs OS initialization for the secondary @@ -152,7 +156,7 @@ void bsp_smp_secondary_cpu_initialize(int cpu); * @note This is provided by RTEMS. */ void rtems_smp_secondary_cpu_initialize(void); - + /** * This method is invoked by the BSP to initialize the per CPU structure * for the specified @a cpu while it is bringing the secondary CPUs @@ -164,10 +168,10 @@ void rtems_smp_secondary_cpu_initialize(void); void rtems_smp_initialize_per_cpu(int cpu); /** - * @brief RTEMS SMP Proccess Interrupt + * @brief Process the incoming interprocessor request. * * This is the method called by the BSP's interrupt handler - * to process the incoming interprocessor request. + * to process the incoming interprocessor request. */ void rtems_smp_process_interrupt(void); @@ -184,9 +188,10 @@ void bsp_smp_wait_for( #endif #else - #define bsp_smp_processor_id() 0 + #define bsp_smp_processor_id() 0 #endif +/**@}*/ #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/debug.h b/cpukit/score/include/rtems/debug.h index 101aea1478..3abec5f22a 100644 --- a/cpukit/score/include/rtems/debug.h +++ b/cpukit/score/include/rtems/debug.h @@ -22,6 +22,13 @@ #include <rtems/score/basedefs.h> +/** + * @defgroup ScoreDebug Debug Information + * + * @ingroup Score + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -47,26 +54,26 @@ typedef uint32_t rtems_debug_control; SCORE_EXTERN rtems_debug_control _Debug_Level; /** - * @brief Initialize Debug Manager + * @brief Initialize debug manager. */ void _Debug_Manager_initialization( void ); /** - * @brief Enable Debugging + * @brief Enable debugging. */ void rtems_debug_enable( rtems_debug_control to_be_enabled ); /** - * @brief Disable Debugging + * @brief Disable debugging. */ void rtems_debug_disable( rtems_debug_control to_be_disabled ); /** - * @brief Check if Debug is Enabled + * @brief Check if debug is enabled. * * This routine returns TRUE if the requested debug level is * enabled, and FALSE otherwise. @@ -79,5 +86,6 @@ bool rtems_debug_is_enabled( } #endif +/**@}*/ #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/address.h b/cpukit/score/include/rtems/score/address.h index a09d63821c..85658b55b0 100644 --- a/cpukit/score/include/rtems/score/address.h +++ b/cpukit/score/include/rtems/score/address.h @@ -1,6 +1,8 @@ /** * @file rtems/score/address.h * + * @brief Information Required to Manipulate Physical Addresses + * * This include file contains the information required to manipulate * physical addresses. */ diff --git a/cpukit/score/include/rtems/score/apiext.h b/cpukit/score/include/rtems/score/apiext.h index db77a8b9c8..54b8049241 100644 --- a/cpukit/score/include/rtems/score/apiext.h +++ b/cpukit/score/include/rtems/score/apiext.h @@ -1,6 +1,8 @@ /** * @file rtems/score/apiext.h * + * @brief API Extensions Handler + * * This is the API Extensions Handler. */ @@ -106,14 +108,14 @@ SCORE_EXTERN Chain_Control _API_extensions_List; SCORE_EXTERN Chain_Control _API_extensions_Post_switch_list; /** - * @brief Initialize the API Extensions Handler + * @brief Initialize the API extensions handler. * * This routine initializes the API extension handler. */ void _API_extensions_Initialization( void ); /** - * @brief Add Extension Set to the Active Set + * @brief Add extension set to the active set. * * This routine adds @a the_extension to the active set of API extensions. * @@ -142,7 +144,7 @@ void _API_extensions_Add_post_switch( #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API) /** - * @brief Execute all Pre-Driver Extensions + * @brief Execute all pre-driver extensions. * * This routine executes all of the predriver callouts. */ @@ -150,7 +152,7 @@ void _API_extensions_Add_post_switch( #endif /** - * @brief Execute all Post-Driver Extensions + * @brief Execute all post-driver extensions. * * This routine executes all of the postdriver callouts. */ diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h index 13b0dddd65..60c21ad29c 100644 --- a/cpukit/score/include/rtems/score/apimutex.h +++ b/cpukit/score/include/rtems/score/apimutex.h @@ -3,7 +3,7 @@ * * @ingroup ScoreAPIMutex * - * @brief API Mutex Handler API. + * @brief API Mutex Handler API */ /* @@ -28,9 +28,8 @@ extern "C" { * @ingroup Score * * @brief Provides routines to ensure mutual exclusion on API level. - * - * @{ */ +/**@{**/ #include <rtems/score/coremutex.h> #include <rtems/score/isr.h> @@ -62,7 +61,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; * The value @a maximum_mutexes is the maximum number of API mutexes that may * exist at any time. * - * @param[in] Maximum_mutexex is the maximum number of API mutexes. + * @param[in] maximum_mutexes is the maximum number of API mutexes. */ void _API_Mutex_Initialization( uint32_t maximum_mutexes ); @@ -76,11 +75,11 @@ void _API_Mutex_Allocate( API_Mutex_Control **mutex ); * @brief Acquires the specified API mutex. */ void _API_Mutex_Lock( - API_Mutex_Control *mutex + API_Mutex_Control *mutex ); /** - * @brief Releases the Specified API Mutex + * @brief Releases the specified API mutex. * * Releases the specified @a mutex. * @@ -100,12 +99,11 @@ void _API_Mutex_Unlock( API_Mutex_Control *mutex ); * When the APIs all use this for allocation and deallocation protection, then * this possibly should be renamed and moved to a higher level in the * hierarchy. - * - * @{ */ +/**@{**/ /** - * @brief Memory Allocation Mutex + * @brief Memory allocation mutex. * * This points to the API Mutex instance used to ensure that only * one thread at a time is allocating or freeing memory. @@ -113,7 +111,7 @@ void _API_Mutex_Unlock( API_Mutex_Control *mutex ); SCORE_EXTERN API_Mutex_Control *_RTEMS_Allocator_Mutex; /** - * @brief Macro to Ease Locking the Allocator Mutex + * @brief Macro to ease locking the allocator mutex. * * This macro makes it explicit that one is locking the allocator mutex. */ @@ -121,7 +119,7 @@ SCORE_EXTERN API_Mutex_Control *_RTEMS_Allocator_Mutex; _API_Mutex_Lock( _RTEMS_Allocator_Mutex ) /** - * @brief Macro to Ease Unlocking the Allocator Mutex + * @brief Macro to ease unlocking the allocator mutex. * * This macro makes it explicit that one is unlocking the allocator mutex. */ diff --git a/cpukit/score/include/rtems/score/basedefs.h b/cpukit/score/include/rtems/score/basedefs.h index e91467d84d..d6b5e24e64 100644 --- a/cpukit/score/include/rtems/score/basedefs.h +++ b/cpukit/score/include/rtems/score/basedefs.h @@ -3,7 +3,7 @@ * * @ingroup Score * - * @brief Basic definitions. + * @brief Basic Definitions */ /* @@ -20,6 +20,13 @@ #ifndef _RTEMS_BASEDEFS_H #define _RTEMS_BASEDEFS_H +/** + * @defgroup ScoreBaseDefs Basic Definitions + * + * @ingroup Score + */ +/**@{*/ + #include <rtems/score/cpuopts.h> #ifndef ASM @@ -189,4 +196,6 @@ typedef void * proc_ptr; #endif +/**@}*/ + #endif /* _RTEMS_BASEDEFS_H */ diff --git a/cpukit/score/include/rtems/score/bitfield.h b/cpukit/score/include/rtems/score/bitfield.h index cfb9bf8753..caa289adf0 100644 --- a/cpukit/score/include/rtems/score/bitfield.h +++ b/cpukit/score/include/rtems/score/bitfield.h @@ -1,7 +1,9 @@ /** - * @file rtems/score/bitfield.h + * @file rtems/score/bitfield.h * - * This include file contains all bit field manipulation routines. + * @brief Bit Field Manipulation Routines + * + * This include file contains all bit field manipulation routines. */ /* @@ -64,6 +66,8 @@ const unsigned char __log2table[256] = { #endif /** + * @brief Gets the @a _bit_number of the first bit set in the specified value. + * * This routine returns the @a _bit_number of the first bit set * in the specified value. The correspondence between @a _bit_number * and actual bit position is processor dependent. The search for diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h index f0a837f379..4b2a449823 100644 --- a/cpukit/score/include/rtems/score/chain.h +++ b/cpukit/score/include/rtems/score/chain.h @@ -3,7 +3,7 @@ * * @ingroup ScoreChain * - * @brief Chain Handler API. + * @brief Chain Handler API */ /* @@ -107,7 +107,7 @@ typedef union { Chain_Control name = CHAIN_INITIALIZER_EMPTY(name) /** - * @brief Initialize a Chain Header + * @brief Initialize a chain header. * * This routine initializes @a the_chain structure to manage the * contiguous array of @a number_nodes nodes which starts at @@ -127,7 +127,7 @@ void _Chain_Initialize( ); /** - * @brief Extract the specified node from a chain + * @brief Extract the specified node from a chain. * * This routine extracts @a the_node from the chain on which it resides. * It disables interrupts to ensure the atomicity of the extract operation. @@ -142,12 +142,12 @@ void _Chain_Extract( ); /** - * @brief Obtain the first node on a chain + * @brief Obtain the first node on a chain. * * This function removes the first node from @a the_chain and returns * a pointer to that node. If @a the_chain is empty, then NULL is returned. * - * @return This method returns a pointer a node. If a node was removed, + * @retval This method returns a pointer a node. If a node was removed, * then a pointer to that node is returned. If @a the_chain was * empty, then NULL is returned. * @@ -158,14 +158,14 @@ Chain_Node *_Chain_Get( ); /** - * @brief Insert a node on a chain + * @brief Insert a node on a chain. * * This routine inserts @a the_node on a chain immediately following * @a after_node. * * @param[in] after_node is the pointer to the node in chain to be * inserted after - * @param[in] node is the pointer to the node to be inserted + * @param[in] the_node is the pointer to the node to be inserted * * @note It disables interrupts to ensure the atomicity * of the insert operation. @@ -179,7 +179,7 @@ void _Chain_Insert( ); /** - * @brief Append a node on the end of a chain + * @brief Append a node on the end of a chain. * * This routine appends @a the_node onto the end of @a the_chain. * @@ -262,7 +262,7 @@ bool _Chain_Get_with_empty_check( * @note It does NOT disable interrupts to ensure the atomicity of the * operation. * - * @return The node count of the chain. + * @retval The node count of the chain. */ size_t _Chain_Node_count_unprotected( const Chain_Control *chain ); diff --git a/cpukit/score/include/rtems/score/context.h b/cpukit/score/include/rtems/score/context.h index 96e3f15191..02bcf156dd 100644 --- a/cpukit/score/include/rtems/score/context.h +++ b/cpukit/score/include/rtems/score/context.h @@ -1,6 +1,8 @@ /** * @file rtems/score/context.h * + * @brief Information About Each Thread's Context + * * This include file contains all information about each thread's context. */ @@ -36,7 +38,7 @@ extern "C" { #include <rtems/score/cpu.h> /** - * @brief Size of Floating Point Context Area + * @brief Size of floating point context area. * * This constant defines the number of bytes required * to store a full floating point context. @@ -44,7 +46,7 @@ extern "C" { #define CONTEXT_FP_SIZE CPU_CONTEXT_FP_SIZE /** - * @brief Initialize Context Area + * @brief Initialize context area. * * This routine initializes @a _the_context such that the stack * pointer, interrupt level, and entry point are correct for the @@ -79,7 +81,7 @@ extern "C" { #endif /** - * @brief Perform Context Switch + * @brief Perform context switch. * * This routine saves the current context into the @a _executing * context record and restores the context specified by @a _heir. @@ -91,7 +93,7 @@ extern "C" { _CPU_Context_switch( _executing, _heir ) /** - * @brief Restart Currently Executing Thread + * @brief Restart currently executing thread. * * This routine restarts the calling thread by restoring its initial * stack pointer and returning to the thread's entry point. @@ -103,7 +105,7 @@ extern "C" { #if defined(RTEMS_SMP) /* - * @brief Switch to First Task on Secondary Core + * @brief Switch to first task on secondary core. * * This routine is only used to switch to the first task on a * secondary core in an SMP configuration. Since the switch @@ -119,7 +121,7 @@ extern "C" { #endif /** - * @brief Return Starting Address of Floating Point Context + * @brief Return starting address of floating point context. * * This function returns the starting address of the floating * point context save area. It is assumed that the are reserved @@ -129,13 +131,13 @@ extern "C" { * context save area. * @param[in] _offset is the offset into the floating point area * - * @return the initial FP context pointer + * @retval the initial FP context pointer */ #define _Context_Fp_start( _base, _offset ) \ _CPU_Context_Fp_start( (_base), (_offset) ) /** - * @brief Initialize Floating Point Context Area + * @brief Initialize floating point context area. * * This routine initializes the floating point context save * area to contain an initial known state. @@ -147,7 +149,7 @@ extern "C" { _CPU_Context_Initialize_fp( _fp_area ) /** - * @brief Restore Floating Point Context Area + * @brief Restore floating point context area. * * This routine restores the floating point context contained * in the @a _fp area. It is assumed that the current @@ -160,7 +162,7 @@ extern "C" { _CPU_Context_restore_fp( _fp ) /** - * @brief Save Floating Point Context Area + * @brief Save floating point context area. * * This routine saves the current floating point context * in the @a _fp area. diff --git a/cpukit/score/include/rtems/score/copyrt.h b/cpukit/score/include/rtems/score/copyrt.h index 87e652026b..cc66f5cf52 100644 --- a/cpukit/score/include/rtems/score/copyrt.h +++ b/cpukit/score/include/rtems/score/copyrt.h @@ -1,6 +1,8 @@ /** * @file rtems/score/copyrt.h * + * @brief Copyright Notice for RTEMS + * * This include file contains the copyright notice for RTEMS * which is included in every binary copy of the executive. */ @@ -17,6 +19,13 @@ #ifndef _RTEMS_SCORE_COPYRT_H #define _RTEMS_SCORE_COPYRT_H +/** + * @defgroup SuperCoreCopyright RTEMS Copyright Notice + * + * @ingroup Score + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -36,5 +45,6 @@ extern const char _Copyright_Notice[]; } #endif +/**@}*/ #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/corebarrier.h b/cpukit/score/include/rtems/score/corebarrier.h index 8072ec1e39..1f7c826b79 100644 --- a/cpukit/score/include/rtems/score/corebarrier.h +++ b/cpukit/score/include/rtems/score/corebarrier.h @@ -1,5 +1,7 @@ /** - * @file rtems/score/corebarrier.h + * @file rtems/score/corebarrier.h + * + * @brief Constants and Structures Associated with the Barrier Handler * * This include file contains all the constants and structures associated * with the Barrier Handler. @@ -82,7 +84,7 @@ typedef enum { } CORE_barrier_Status; /** - * @brief Core Barrier Last Status + * @brief Core barrier last status value. * * This is the last status value. */ @@ -121,7 +123,7 @@ typedef struct { } CORE_barrier_Control; /** - * @brief Initialize CORE Barrier + * @brief Initialize core barrier. * * This routine initializes the barrier based on the parameters passed. * @@ -134,7 +136,8 @@ void _CORE_barrier_Initialize( ); /** - * @brief Wait For The Barrier + * @brief Wait for the barrier. + * * This routine wait for the barrier to be released. If the barrier * is set to automatic and this is the appropriate thread, then it returns * immediately. Otherwise, the calling thread is blocked until the barrier @@ -159,7 +162,7 @@ void _CORE_barrier_Wait( ); /** - * @brief Manually releases the barrier + * @brief Manually release the barrier. * * This routine manually releases the barrier. All of the threads waiting * for the barrier will be readied. @@ -169,7 +172,7 @@ void _CORE_barrier_Wait( * @param[in] api_barrier_mp_support is the routine to invoke if the * thread unblocked is remote * - * @return the number of unblocked threads + * @retval the number of unblocked threads */ uint32_t _CORE_barrier_Release( CORE_barrier_Control *the_barrier, diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h index 0f468c83bf..d022391182 100644 --- a/cpukit/score/include/rtems/score/coremsg.h +++ b/cpukit/score/include/rtems/score/coremsg.h @@ -1,6 +1,8 @@ /** * @file rtems/score/coremsg.h * + * @brief Constants and Structures Associated with the Message Queue Handler. + * * This include file contains all the constants and structures associated * with the Message queue Handler. */ @@ -64,7 +66,7 @@ extern "C" { #endif /** - * @brief Message Queue MP Callback Prototype + * @brief Callout provides to support global/multiprocessor operations. * * The following type defines the callout which the API provides * to support global/multiprocessor operations on message_queues. @@ -75,7 +77,7 @@ typedef void ( *CORE_message_queue_API_mp_support_callout )( ); /** - * @brief Message Buffer Contents Management Structure + * @brief Data types needed to manipulate the contents of message buffers. * * The following defines the data types needed to manipulate * the contents of message buffers. @@ -91,7 +93,7 @@ typedef struct { } CORE_message_queue_Buffer; /** - * @brief Message Structure + * @brief The organization of a message buffer. * * The following records define the organization of a message * buffer. @@ -108,7 +110,7 @@ typedef struct { } CORE_message_queue_Buffer_control; /** - * @brief Message Queue Blocking Disciplines + * @brief The possible blocking disciplines for a message queue. * * This enumerated types defines the possible blocking disciplines * for a message queue. @@ -121,7 +123,7 @@ typedef enum { } CORE_message_queue_Disciplines; /** - * @brief Message Priority for Appending + * @brief Used when appending messages onto a message queue. * * This is the priority constant used when appending messages onto * a message queue. @@ -129,7 +131,7 @@ typedef enum { #define CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX /** - * @brief Message Priority for Prepending + * @brief Used when prepending messages onto a message queue. * * This is the priority constant used when prepending messages onto * a message queue. @@ -137,7 +139,7 @@ typedef enum { #define CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN /** - * @brief Message Insertion Operation Types + * @brief The modes in which a message may be submitted to a message queue. * * The following type details the modes in which a message * may be submitted to a message queue. The message may be posted @@ -149,7 +151,7 @@ typedef enum { typedef int CORE_message_queue_Submit_types; /** - * @brief Core Message Queue Return Statuses + * @brief The possible set of Core Message Queue handler return statuses. * * This enumerated type defines the possible set of Core Message * Queue handler return statuses. @@ -178,14 +180,14 @@ typedef enum { } CORE_message_queue_Status; /** - * @brief Core Message Queue Last Status + * @brief Core message queue last status value. * * This is the last status value. */ #define CORE_MESSAGE_QUEUE_STATUS_LAST CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT /** - * @brief Message Queue Attributes Type + * @brief Control block used to manage the attributes of each message queue. * * The following defines the control block used to manage the * attributes of each message queue. @@ -197,7 +199,7 @@ typedef struct { #if defined(RTEMS_SCORE_COREMSG_ENABLE_NOTIFICATION) /** - * @brief Message Queue Notification Callback Prototype + * @brief Type for a notification handler. * * The following defines the type for a Notification handler. A * notification handler is invoked when the message queue makes a @@ -207,10 +209,10 @@ typedef struct { #endif /** - * @brief Core Message Queue Control Structure + * @brief Control block used to manage each message queue. * * The following defines the control block used to manage each - * Message Queue + * Message Queue. */ typedef struct { /** This field is the Waiting Queue used to manage the set of tasks @@ -256,15 +258,15 @@ typedef struct { } CORE_message_queue_Control; /** - * @brief Initialize a Message Queue - * + * @brief Initialize a message queue. + * * DESCRIPTION: * * This package is the implementation of the CORE Message Queue Handler. * This core object provides task synchronization and communication functions * via messages passed to queue objects. * - * This routine initializes @a the_message_queue + * This routine initializes @a the_message_queue * based on the parameters passed. * * @param[in] the_message_queue points to the message queue to initialize @@ -275,7 +277,7 @@ typedef struct { * @param[in] maximum_message_size is the size of largest message that * may be sent to this message queue instance * - * @return true if the message queue can be initialized. In general, + * @retval true if the message queue can be initialized. In general, * false will only be returned if memory for the pending * messages cannot be allocated. */ @@ -287,8 +289,8 @@ bool _CORE_message_queue_Initialize( ); /** - * @brief Close a Message Queue - * + * @brief Close a message queue. + * * DESCRIPTION: * This package is the implementation of the CORE Message Queue Handler. * This core object provides task synchronization and communication functions @@ -310,8 +312,8 @@ void _CORE_message_queue_Close( ); /** - * @brief Flush Pending Messages - * + * @brief Flush pending messages. + * * DESCRIPTION: * This package is the implementation of the CORE Message Queue Handler. * This core object provides task synchronization and communication functions @@ -322,21 +324,21 @@ void _CORE_message_queue_Close( * * @param[in] the_message_queue points to the message queue to flush * - * @return This method returns the number of message pending messages flushed. + * @retval This method returns the number of message pending messages flushed. */ uint32_t _CORE_message_queue_Flush( CORE_message_queue_Control *the_message_queue ); /** - * @brief Flush Messages Support Routine + * @brief Flush all outstanding messages. * * This routine flushes all outstanding messages and returns * them to the inactive message chain. * * @param[in] the_message_queue points to the message queue to flush * - * @return This method returns the number of pending messages flushed. + * @retval This method returns the number of pending messages flushed. * * - INTERRUPT LATENCY: * + single case @@ -347,15 +349,15 @@ uint32_t _CORE_message_queue_Flush_support( #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API) /** - * @brief Flush Waiting Threads. + * @brief Flush waiting threads. * * This function flushes the threads which are blocked on * @a the_message_queue's pending message queue. They are - * unblocked whether blocked sending or receiving. It returns + * unblocked whether blocked sending or receiving. It returns * the number of messages flushed from the queue. * * @param[in] the_message_queue points to the message queue to flush - * @return number of messages flushed from the queue + * @retval number of messages flushed from the queue */ void _CORE_message_queue_Flush_waiting_threads( CORE_message_queue_Control *the_message_queue @@ -363,8 +365,8 @@ uint32_t _CORE_message_queue_Flush_support( #endif /** - * @brief Broadcast a Message to the Message Queue - * + * @brief Broadcast a message to the message queue. + * * DESCRIPTION: * This package is the implementation of the CORE Message Queue Handler. * This core object provides task synchronization and communication functions @@ -382,8 +384,8 @@ uint32_t _CORE_message_queue_Flush_support( * a thread that is unblocked is actually a remote thread. * @param[out] count points to the variable that will contain the * number of tasks that are sent this message - * @return @a *count will contain the number of messages sent - * @return indication of the successful completion or reason for failure + * @retval @a *count will contain the number of messages sent + * @retval indication of the successful completion or reason for failure */ CORE_message_queue_Status _CORE_message_queue_Broadcast( CORE_message_queue_Control *the_message_queue, @@ -395,7 +397,7 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast( ); /** - * @brief Submit a Message to the Message Queue + * @brief Submit a message to the message queue. * * This routine implements the send and urgent message functions. It * processes a message that is to be submitted to the designated @@ -417,7 +419,7 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast( * if the message queue is full. * @param[in] timeout is the maximum number of clock ticks that the calling * thread is willing to block if the message queue is full. - * @return indication of the successful completion or reason for failure + * @retval indication of the successful completion or reason for failure */ CORE_message_queue_Status _CORE_message_queue_Submit( CORE_message_queue_Control *the_message_queue, @@ -431,8 +433,8 @@ CORE_message_queue_Status _CORE_message_queue_Submit( ); /** - * @brief Size a Message from the Message Queue - * + * @brief Size a message from the message queue. + * * DESCRIPTION: * This package is the implementation of the CORE Message Queue Handler. * This core object provides task synchronization and communication functions @@ -448,16 +450,19 @@ CORE_message_queue_Status _CORE_message_queue_Submit( * It is used when unblocking a remote thread. * @param[in] buffer is the starting address of the message buffer to * to be filled in with a message - * @param[in] size is the size of the @a buffer and indicates the maximum - * size message that the caller can receive. + * @param[in] size_p is a pointer to the size of the @a buffer and + * indicates the maximum size message that the caller can receive. * @param[in] wait indicates whether the calling thread is willing to block * if the message queue is empty. * @param[in] timeout is the maximum number of clock ticks that the calling * thread is willing to block if the message queue is empty. * - * @return indication of the successful completion or reason for failure - * @note Returns message priority via return are in TCB. - * + * @retval indication of the successful completion or reason for failure. + * On success, the location pointed to @a size_p will contain the + * size of the received message. + * + * @note Returns message priority via return area in TCB. + * * - INTERRUPT LATENCY: * + available * + wait @@ -472,8 +477,8 @@ void _CORE_message_queue_Seize( ); /** - * @brief Insert a Message into the Message Queue - * + * @brief Insert a message into the message queue. + * * This kernel routine inserts the specified message into the * message queue. It is assumed that the message has been filled * in before this routine is called. @@ -482,7 +487,7 @@ void _CORE_message_queue_Seize( * @param[in] the_message is the message to enqueue * @param[in] submit_type determines whether the message is prepended, * appended, or enqueued in priority order. - * + * * - INTERRUPT LATENCY: * + insert */ diff --git a/cpukit/score/include/rtems/score/coremutex.h b/cpukit/score/include/rtems/score/coremutex.h index 9c0fce34cc..69babb9b09 100644 --- a/cpukit/score/include/rtems/score/coremutex.h +++ b/cpukit/score/include/rtems/score/coremutex.h @@ -1,6 +1,8 @@ /** * @file rtems/score/coremutex.h * + * @brief Constants and Structures Associated with the Mutex Handler + * * This include file contains all the constants and structures associated * with the Mutex Handler. A mutex is an enhanced version of the standard * Dijkstra binary semaphore used to provide synchronization and mutual @@ -40,7 +42,7 @@ extern "C" { #include <rtems/score/sysstate.h> /** - * @brief MP Support Callback Prototype + * @brief Callout which provides to support global/multiprocessor operations. * * The following type defines the callout which the API provides * to support global/multiprocessor operations on mutexes. @@ -51,7 +53,7 @@ typedef void ( *CORE_mutex_API_mp_support_callout )( ); /** - * @brief Blocking Disciplines Enumerated Type + * @brief The blocking disciplines for a mutex. * * This enumerated type defines the blocking disciplines for a mutex. */ @@ -71,7 +73,7 @@ typedef enum { } CORE_mutex_Disciplines; /** - * @brief Mutex method return statuses + * @brief The possible Mutex handler return statuses. * * This enumerated type defines the possible Mutex handler return statuses. */ @@ -118,14 +120,14 @@ typedef enum { } CORE_mutex_Status; /** - * @brief Core Mutex Last Status + * @brief The last status value. * * This is the last status value. */ #define CORE_MUTEX_STATUS_LAST CORE_MUTEX_STATUS_CEILING_VIOLATED /** - * @brief Mutex Lock Nesting Behavior Enumeration + * @brief The possible behaviors for lock nesting. * * This enumerated type defines the possible behaviors for * lock nesting. @@ -170,7 +172,7 @@ typedef enum { #define CORE_MUTEX_LOCKED 0 /** - * @brief Core Mutex Attributes + * @brief The control block used to manage attributes of each mutex. * * The following defines the control block used to manage the * attributes of each mutex. @@ -195,7 +197,8 @@ typedef struct { } CORE_mutex_Attributes; #ifdef __RTEMS_STRICT_ORDER_MUTEX__ -/*@brief Core Mutex Lock_Chain Struct +/** + * @brief The control block to manage lock chain of priority inheritance mutex. * * The following defines the control block used to manage lock chain of * priority inheritance mutex. @@ -214,7 +217,7 @@ typedef struct { #endif /** - * @brief Core Mutex Control Structure + * @brief Control block used to manage each mutex. * * The following defines the control block used to manage each mutex. */ @@ -251,7 +254,7 @@ typedef struct { } CORE_mutex_Control; /** - * @brief Initialize a Core Mutex + * @brief Initializes the mutex based on the parameters passed. * * This routine initializes the mutex based on the parameters passed. * @@ -260,7 +263,7 @@ typedef struct { * mutex instance * @param[in] initial_lock is the initial value of the mutex * - * @return This method returns CORE_MUTEX_STATUS_SUCCESSFUL if successful. + * @retval This method returns CORE_MUTEX_STATUS_SUCCESSFUL if successful. */ CORE_mutex_Status _CORE_mutex_Initialize( CORE_mutex_Control *the_mutex, @@ -270,7 +273,7 @@ CORE_mutex_Status _CORE_mutex_Initialize( #ifndef __RTEMS_APPLICATION__ /** - * @brief Seize Mutex with Quick Success Path + * @brief Attempt to receive a unit from the_mutex. * * This routine attempts to receive a unit from the_mutex. * If a unit is available or if the wait flag is false, then the routine @@ -280,7 +283,7 @@ CORE_mutex_Status _CORE_mutex_Initialize( * @param[in] the_mutex is the mutex to attempt to lock * @param[in] level_p is the interrupt level holder * - * @return This routine returns 0 if "trylock" can resolve whether or not + * @retval This routine returns 0 if "trylock" can resolve whether or not * the mutex is immediately obtained or there was an error attempting to * get it. It returns 1 to indicate that the caller cannot obtain * the mutex and will have to block to do so. @@ -296,7 +299,8 @@ RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock_body( #if defined(__RTEMS_DO_NOT_INLINE_CORE_MUTEX_SEIZE__) /** - * @brief Trylock CORE Mutex Seize Interrupt + * @brief Interrupt trylock CORE mutex seize. + * * When doing test coverage analysis or trying to minimize the code * space for RTEMS, it is often helpful to not inline this method * multiple times. It is fairly large and has a high branch complexity @@ -322,7 +326,7 @@ RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock_body( #endif /** - * @brief Seize Mutex with Blocking + * @brief Performs the blocking portion of a mutex obtain. * * This routine performs the blocking portion of a mutex obtain. * It is an actual subroutine and is not implemented as something @@ -336,13 +340,13 @@ void _CORE_mutex_Seize_interrupt_blocking( Watchdog_Interval timeout ); /** - * @brief Sieze Interrupt Wrapper + * @brief Verifies that a mutex blocking seize is performed safely. * * This macro is to verify that a mutex blocking seize is * performed from a safe system state. For example, one * cannot block inside an isr. * - * @return this method returns true if dispatch is in an unsafe state. + * @retval this method returns true if dispatch is in an unsafe state. */ #ifdef RTEMS_SMP #define _CORE_mutex_Check_dispatch_for_seize(_wait) 0 @@ -354,7 +358,7 @@ void _CORE_mutex_Seize_interrupt_blocking( #endif /** - * @brief Sieze Interrupt Wrapper + * @brief Attempt to obtain the mutex. * * This routine attempts to obtain the mutex. If the mutex is available, * then it will return immediately. Otherwise, it will invoke the @@ -430,7 +434,7 @@ void _CORE_mutex_Seize_interrupt_blocking( #endif /** - * @brief Surrender the Mutex + * @brief Frees a unit to the mutex. * * This routine frees a unit to the mutex. If a task was blocked waiting for * a unit from this mutex, then that task will be readied and the unit @@ -441,7 +445,7 @@ void _CORE_mutex_Seize_interrupt_blocking( * @param[in] api_mutex_mp_support is the routine that will be called when * unblocking a remote mutex * - * @return an indication of whether the routine succeeded or failed + * @retval an indication of whether the routine succeeded or failed */ CORE_mutex_Status _CORE_mutex_Surrender( CORE_mutex_Control *the_mutex, @@ -450,7 +454,7 @@ CORE_mutex_Status _CORE_mutex_Surrender( ); /** - * @brief Flush all waiting threads + * @brief Flush all waiting threads. * * This routine assists in the deletion of a mutex by flushing the associated * wait queue. diff --git a/cpukit/score/include/rtems/score/corerwlock.h b/cpukit/score/include/rtems/score/corerwlock.h index 3b70d80701..8281abb9eb 100644 --- a/cpukit/score/include/rtems/score/corerwlock.h +++ b/cpukit/score/include/rtems/score/corerwlock.h @@ -1,6 +1,8 @@ /** * @file rtems/score/corerwlock.h * + * @brief Constants and Structures Associated with the RWLock Handler + * * This include file contains all the constants and structures associated * with the RWLock Handler. */ @@ -125,7 +127,7 @@ typedef struct { } CORE_RWLock_Control; /** - * @brief Initialize a RWlock + * @brief Initialize a RWlock. * * This routine initializes the RWLock based on the parameters passed. * @@ -138,7 +140,8 @@ void _CORE_RWLock_Initialize( ); /** - * @brief Obtain RWLock for reading + * @brief Obtain RWLock for reading. + * * This routine attempts to obtain the RWLock for read access. * * @param[in] the_rwlock is the RWLock to wait for @@ -161,8 +164,8 @@ void _CORE_RWLock_Obtain_for_reading( ); /** - * @brief RWLock Obtain for Writing - * + * @brief Obtain RWLock for writing. + * * This routine attempts to obtain the RWLock for write exclusive access. * * @param[in] the_rwlock is the RWLock to wait for @@ -184,14 +187,14 @@ void _CORE_RWLock_Obtain_for_writing( ); /** - * @brief Releases the RWLock + * @brief Release the RWLock. * * This routine manually releases @a the_rwlock. All of the threads waiting * for the RWLock will be readied. * * @param[in] the_rwlock is the RWLock to surrender * - * @return Status is returned to indicate successful or failure. + * @retval Status is returned to indicate successful or failure. */ CORE_RWLock_Status _CORE_RWLock_Release( CORE_RWLock_Control *the_rwlock @@ -214,7 +217,7 @@ CORE_RWLock_Status _CORE_RWLock_Release( ) /** - * @brief RWLock Specific Thread Queue Timeout + * @brief RWLock specific thread queue timeout. * * This routine processes a thread which timeouts while waiting on * an RWLock's thread queue. It is called by the watchdog handler. diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h index d7a8494c55..3bb8773430 100644 --- a/cpukit/score/include/rtems/score/coresem.h +++ b/cpukit/score/include/rtems/score/coresem.h @@ -1,6 +1,8 @@ /** * @file rtems/score/coresem.h * + * @brief Data Associated with the Counting Semaphore Handler + * * This include file contains all the constants and structures associated * with the Counting Semaphore Handler. A counting semaphore is the * standard Dijkstra binary semaphore used to provide synchronization @@ -90,7 +92,7 @@ typedef enum { } CORE_semaphore_Status; /** - * @brief Core Semaphore Last Status + * @brief Core semaphore last status value. * * This is the last status value. */ @@ -127,14 +129,14 @@ typedef struct { } CORE_semaphore_Control; /** - * @brief Core Semaphore Initialize - * + * @brief Initialize the semaphore based on the parameters passed. + * * DESCRIPTION: * * This package is the implementation of the CORE Semaphore Handler. * This core object utilizes standard Dijkstra counting semaphores to provide * synchronization and mutual exclusion capabilities. - * + * * This routine initializes the semaphore based on the parameters passed. * * @param[in] the_semaphore is the semaphore to initialize @@ -170,7 +172,7 @@ void _CORE_semaphore_Initialize( #endif /** - * @brief Surrenders a Unit to a Semaphore + * @brief Surrender a unit to a semaphore. * * This routine frees a unit to the semaphore. If a task was blocked waiting * for a unit from this semaphore, then that task will be readied and the unit @@ -182,7 +184,7 @@ void _CORE_semaphore_Initialize( * @param[in] api_semaphore_mp_support is the routine to invoke if the * thread unblocked is remote * - * @return an indication of whether the routine succeeded or failed + * @retval an indication of whether the routine succeeded or failed */ CORE_semaphore_Status _CORE_semaphore_Surrender( CORE_semaphore_Control *the_semaphore, @@ -191,8 +193,8 @@ CORE_semaphore_Status _CORE_semaphore_Surrender( ); /** - * @brief Core Semaphore Flush - * + * @brief Core semaphore flush. + * * DESCRIPTION: * This package is the implementation of the CORE Semaphore Handler. * This core object utilizes standard Dijkstra counting semaphores to provide diff --git a/cpukit/score/include/rtems/score/corespinlock.h b/cpukit/score/include/rtems/score/corespinlock.h index dfa62ccb8f..5a5b68168a 100644 --- a/cpukit/score/include/rtems/score/corespinlock.h +++ b/cpukit/score/include/rtems/score/corespinlock.h @@ -1,6 +1,8 @@ /** * @file rtems/score/corespinlock.h * + * @brief Constants and Structures Associated with the Spinlock Handler + * * This include file contains all the constants and structures associated * with the Spinlock Handler. */ @@ -110,7 +112,7 @@ typedef struct { } CORE_spinlock_Control; /** - * @brief Initialized a spinlock + * @brief Initialize the spinlock. * * This routine initializes the spinlock based on the parameters passed. * @@ -123,7 +125,8 @@ void _CORE_spinlock_Initialize( ); /** - * @brief Wait for Spinlock + * @brief Wait for spinlock. + * * This routine wait for the spinlock to be released. If the spinlock * is set to automatic and this is the appropriate thread, then it returns * immediately. Otherwise, the calling thread is blocked until the spinlock @@ -133,7 +136,7 @@ void _CORE_spinlock_Initialize( * @param[in] wait is true if willing to wait * @param[in] timeout is the maximum number of ticks to spin (0 is forever) * - * @return A status is returned which indicates the success or failure of + * @retval A status is returned which indicates the success or failure of * this operation. */ CORE_spinlock_Status _CORE_spinlock_Wait( @@ -143,8 +146,8 @@ CORE_spinlock_Status _CORE_spinlock_Wait( ); /** - * @brief Manually release Spinlock - * + * @brief Manually release the spinlock. + * * This routine manually releases the spinlock. All of the threads waiting * for the spinlock will be readied. * diff --git a/cpukit/score/include/rtems/score/heap.h b/cpukit/score/include/rtems/score/heap.h index f3d259d6cf..80b3fd2404 100644 --- a/cpukit/score/include/rtems/score/heap.h +++ b/cpukit/score/include/rtems/score/heap.h @@ -3,7 +3,7 @@ * * @ingroup ScoreHeap * - * @brief Heap Handler API. + * @brief Heap Handler API */ /* @@ -126,9 +126,8 @@ extern "C" { * block indicates that the previous block is used, this ensures that the * last block appears as used for the _Heap_Is_used() and _Heap_Is_free() * functions. - * - * @{ */ +/**@{**/ typedef struct Heap_Control Heap_Control; diff --git a/cpukit/score/include/rtems/score/interr.h b/cpukit/score/include/rtems/score/interr.h index 522e1576e2..2580c72253 100644 --- a/cpukit/score/include/rtems/score/interr.h +++ b/cpukit/score/include/rtems/score/interr.h @@ -1,6 +1,8 @@ /** * @file rtems/score/interr.h * + * @brief Constants and Prototypes Related to the Internal Error Handler + * * This include file contains constants and prototypes related * to the Internal Error Handler. */ diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h index 0d93d29de9..58d4fbc952 100644 --- a/cpukit/score/include/rtems/score/isr.h +++ b/cpukit/score/include/rtems/score/isr.h @@ -1,6 +1,8 @@ /** * @file rtems/score/isr.h * + * @brief Data Related to the Management of Processor Interrupt Levels + * * This include file contains all the constants and structures associated * with the management of processor interrupt levels. This handler * supports interrupt critical sections, vectoring of user interrupt @@ -87,19 +89,19 @@ SCORE_EXTERN ISR_Handler_entry *_ISR_Vector_table; #endif /** - * @brief Initialize the ISR Handler + * @brief Initialize the ISR handler. * * This routine performs the initialization necessary for the ISR handler. */ void _ISR_Handler_initialization ( void ); /** - * @brief Disable Interrupts on This Core + * @brief Disable interrupts on this core. * * This routine disables all interrupts so that a critical section * of code can be executing without being interrupted. * - * @return The argument @a _level will contain the previous interrupt + * @retval The argument @a _level will contain the previous interrupt * mask level. */ #define _ISR_Disable_on_this_core( _level ) \ @@ -109,13 +111,13 @@ void _ISR_Handler_initialization ( void ); } while (0) /** - * @brief Enable Interrupts on This Core + * @brief Enable interrupts on this core. * * This routine enables interrupts to the previous interrupt mask * LEVEL. It is used at the end of a critical section of code to * enable interrupts so they can be processed again. * - * @param[in] level contains the interrupt level mask level + * @param[in] _level contains the interrupt level mask level * previously returned by @ref _ISR_Disable_on_this_core. */ #define _ISR_Enable_on_this_core( _level ) \ @@ -125,7 +127,7 @@ void _ISR_Handler_initialization ( void ); } while (0) /** - * @brief Temporarily Enable Interrupts on This Core + * @brief Temporarily enable interrupts on this core. * * This routine temporarily enables interrupts to the previous * interrupt mask level and then disables all interrupts so that @@ -140,7 +142,7 @@ void _ISR_Handler_initialization ( void ); * must be selected with care to ensure that the critical section * properly protects itself. * - * @param[in] level contains the interrupt level mask level + * @param[in] _level contains the interrupt level mask level * previously returned by @ref _ISR_Disable_on_this_core. */ #define _ISR_Flash_on_this_core( _level ) \ @@ -153,7 +155,7 @@ void _ISR_Handler_initialization ( void ); #if defined(RTEMS_SMP) /** - * @brief Initialize SMP Interrupt Critical Section Support + * @brief Initialize SMP interrupt critical section support. * * This method initializes the variables required by the SMP implementation * of interrupt critical section management. @@ -161,17 +163,17 @@ void _ISR_Handler_initialization ( void ); void _ISR_SMP_Initialize(void); /** - * @brief Enter Interrupt Critical Section on SMP System + * @brief Enter interrupt critical section on SMP system. * * This method is used to enter an interrupt critical section that * is honored across all cores in an SMP system. * - * @return This method returns the previous interrupt mask level. + * @retval This method returns the previous interrupt mask level. */ ISR_Level _ISR_SMP_Disable(void); /** - * @brief Exit Interrupt Critical Section on SMP System + * @brief Exit interrupt critical section on SMP system. * * This method is used to exit an interrupt critical section that * is honored across all cores in an SMP system. @@ -182,7 +184,7 @@ ISR_Level _ISR_SMP_Disable(void); void _ISR_SMP_Enable(ISR_Level level); /** - * @brief Temporarily Exit Interrupt Critical Section on SMP System + * @brief Temporarily exit interrupt critical section on SMP system. * * This method is used to temporarily exit an interrupt critical section * that is honored across all cores in an SMP system. @@ -193,20 +195,20 @@ void _ISR_SMP_Enable(ISR_Level level); void _ISR_SMP_Flash(ISR_Level level); /** - * @brief Enter SMP interrupt code + * @brief Enter SMP interrupt code. * * This method is used to enter the SMP interrupt section. * - * @return This method returns the isr level. + * @retval This method returns the isr level. */ int _ISR_SMP_Enter(void); /** - * @brief Exit SMP interrupt code + * @brief Exit SMP interrupt code. * * This method is used to exit the SMP interrupt. * - * @return This method returns 0 on a simple return and returns 1 on a + * @retval This method returns 0 on a simple return and returns 1 on a * dispatching return. */ int _ISR_SMP_Exit(void); @@ -214,7 +216,7 @@ int _ISR_SMP_Exit(void); #endif /** - * @brief Enter Interrupt Disable Critical Section + * @brief Enter interrupt disable critical section. * * This routine enters an interrupt disable critical section. When * in an SMP configuration, this involves obtaining a spinlock to ensure @@ -222,7 +224,7 @@ int _ISR_SMP_Exit(void); * When on a single core system, this only involves disabling local * CPU interrupts. * - * @return The argument @a _level will contain the previous interrupt + * @retval The argument @a _level will contain the previous interrupt * mask level. */ #if defined(RTEMS_SMP) @@ -234,14 +236,14 @@ int _ISR_SMP_Exit(void); #endif /** - * @brief Exits Interrupt Disable Critical Section + * @brief Exits interrupt disable critical section. * * This routine exits an interrupt disable critical section. When * in an SMP configuration, this involves releasing a spinlock. * When on a single core system, this only involves disabling local * CPU interrupts. * - * @return The argument @a _level will contain the previous interrupt + * @retval The argument @a _level will contain the previous interrupt * mask level. */ #if defined(RTEMS_SMP) @@ -253,7 +255,7 @@ int _ISR_SMP_Exit(void); #endif /** - * @brief Temporarily Exit Interrupt Disable Critical Section + * @brief Temporarily exit interrupt disable critical section. * * This routine is used to temporarily enable interrupts * during a long critical section. It is used in long sections of @@ -263,7 +265,7 @@ int _ISR_SMP_Exit(void); * must be selected with care to ensure that the critical section * properly protects itself. * - * @return The argument @a _level will contain the previous interrupt + * @retval The argument @a _level will contain the previous interrupt * mask level. */ #if defined(RTEMS_SMP) @@ -275,7 +277,7 @@ int _ISR_SMP_Exit(void); #endif /** - * @brief Install Interrupt Handler Vector + * @brief Install interrupt handler vector. * * This routine installs new_handler as the interrupt service routine * for the specified vector. The previous interrupt service routine is @@ -289,26 +291,26 @@ int _ISR_SMP_Exit(void); * @param[in] _old_handler is a pointer to a variable which will be set * to the old handler * - * @return *_old_handler will be set to the old ISR handler + * @retval *_old_handler will be set to the old ISR handler */ #define _ISR_Install_vector( _vector, _new_handler, _old_handler ) \ _CPU_ISR_install_vector( _vector, _new_handler, _old_handler ) /** - * @brief Return Current Interrupt Level + * @brief Return current interrupt level. * * This routine returns the current interrupt level. * * LM32 Specific Information: * XXX document implementation including references if appropriate * - * @return This method returns the current level. + * @retval This method returns the current level. */ #define _ISR_Get_level() \ _CPU_ISR_Get_level() /** - * @brief Set Current Interrupt Level + * @brief Set current interrupt level. * * This routine sets the current interrupt level to that specified * by @a _new_level. The new interrupt level is effective when the @@ -324,7 +326,7 @@ int _ISR_SMP_Exit(void); } while (0) /** - * @brief ISR Handler or Dispatcher + * @brief ISR interrupt dispatcher. * * This routine is the interrupt dispatcher. ALL interrupts * are vectored to this routine so that minimal context can be saved @@ -340,7 +342,7 @@ int _ISR_SMP_Exit(void); void _ISR_Handler( void ); /** - * @brief ISR Wrapper for Thread Dispatcher + * @brief ISR wrapper for thread dispatcher. * * This routine provides a wrapper so that the routine * @ref _Thread_Dispatch can be invoked when a reschedule is necessary @@ -355,13 +357,13 @@ void _ISR_Handler( void ); void _ISR_Dispatch( void ); /** - * @brief Is an ISR in Progress + * @brief Checks if an ISR in progress. * * This function returns true if the processor is currently servicing * and interrupt and false otherwise. A return value of true indicates * that the caller is an interrupt service routine, NOT a thread. * - * @return This methods returns true when called from an ISR. + * @retval This methods returns true when called from an ISR. */ #if (CPU_PROVIDES_ISR_IS_IN_PROGRESS == TRUE) bool _ISR_Is_in_progress( void ); diff --git a/cpukit/score/include/rtems/score/isrlevel.h b/cpukit/score/include/rtems/score/isrlevel.h index 13f1c53c3f..e3146e4ef3 100644 --- a/cpukit/score/include/rtems/score/isrlevel.h +++ b/cpukit/score/include/rtems/score/isrlevel.h @@ -1,6 +1,8 @@ /** * @file rtems/score/isrlevel.h * + * @brief ISR Level Type + * * This include file defines the ISR Level type. It exists to * simplify include dependencies. It is part of the ISR Handler. */ @@ -22,6 +24,10 @@ extern "C" { #endif /** + * @defgroup ScoreISR ISR Handler + * + * @ingroup Score + * * @addtogroup ScoreISR ISR Handler */ /**@{*/ @@ -38,4 +44,3 @@ typedef uint32_t ISR_Level; } #endif #endif - diff --git a/cpukit/score/include/rtems/score/mpci.h b/cpukit/score/include/rtems/score/mpci.h index 5fce6a274f..16f6d36b20 100644 --- a/cpukit/score/include/rtems/score/mpci.h +++ b/cpukit/score/include/rtems/score/mpci.h @@ -1,6 +1,8 @@ /** * @file rtems/score/mpci.h * + * @brief Constants and Structures Associated with the MPCI Layer + * * This include file contains all the constants and structures associated * with the MPCI layer. It provides mechanisms to utilize packets. */ @@ -180,7 +182,7 @@ SCORE_EXTERN Thread_queue_Control _MPCI_Remote_blocked_threads; SCORE_EXTERN MPCI_Control *_MPCI_table; /** - * @brief Pointer to MP Thread Control Block + * @brief Pointer to MP thread control block. * * The following is used to determine when the multiprocessing receive * thread is executing so that a proxy can be allocated instead of @@ -196,7 +198,7 @@ SCORE_EXTERN MPCI_Packet_processor _MPCI_Packet_processors[MP_PACKET_CLASSES_LAST+1]; /** - * @brief Initialization of the MPCI Handler + * @brief Initialize the MPCI handler. * * This routine performs the initialization necessary for this handler. * @@ -208,14 +210,14 @@ void _MPCI_Handler_initialization( ); /** - * @brief Create the MPCI Server Thread - * + * @brief Create the MPCI server thread. + * * This routine creates the packet receive server used in MP systems. */ void _MPCI_Create_server( void ); /** - * @brief Initialize the MPCI driver + * @brief Initialize the MPCI driver. * * This routine initializes the MPCI driver by * invoking the user provided MPCI initialization callout. @@ -241,14 +243,14 @@ void _MPCI_Register_packet_processor( * This function obtains a packet by invoking the user provided * MPCI get packet callout. * - * @return This method returns a pointer to a MPCI packet which can be + * @retval This method returns a pointer to a MPCI packet which can be * filled in by the caller and used to perform a subsequent * remote operation. */ MP_packet_Prefix *_MPCI_Get_packet ( void ); /** - * @brief Deallocate a packet + * @brief Deallocate a packet. * * This routine deallocates a packet by invoking the user provided * MPCI return packet callout. @@ -260,7 +262,7 @@ void _MPCI_Return_packet ( ); /** - * @brief Send a process packet + * @brief Send a process packet. * * This routine sends a process packet by invoking the user provided * MPCI send callout. @@ -274,7 +276,7 @@ void _MPCI_Send_process_packet ( ); /** - * @brief Send a request packet + * @brief Send a request packet. * * This routine sends a request packet by invoking the user provided * MPCI send callout. @@ -286,7 +288,7 @@ void _MPCI_Send_process_packet ( * may indicate the caller is blocking on a message queue * operation. * - * @return This method returns the operation status from the remote node. + * @retval This method returns the operation status from the remote node. */ uint32_t _MPCI_Send_request_packet ( uint32_t destination, @@ -295,7 +297,7 @@ uint32_t _MPCI_Send_request_packet ( ); /** - * @brief Send a response packet + * @brief Send a response packet. * * This routine sends a response packet by invoking the user provided * MPCI send callout. @@ -309,17 +311,17 @@ void _MPCI_Send_response_packet ( ); /** - * @brief Receive a packet + * @brief Receive a packet. * * This routine receives a packet by invoking the user provided * MPCI receive callout. * - * @return This method returns the packet received. + * @retval This method returns the packet received. */ MP_packet_Prefix *_MPCI_Receive_packet ( void ); /** - * @brief Pass a packet to the thread + * @brief Pass a packet to the thread. * * This routine is responsible for passing @a the_packet to the thread * waiting on the remote operation to complete. The unblocked thread is @@ -327,7 +329,7 @@ MP_packet_Prefix *_MPCI_Receive_packet ( void ); * * @param[in] the_packet is the response packet to be processed. * - * @return This method returns a pointer to the thread which was if unblocked + * @retval This method returns a pointer to the thread which was if unblocked * or NULL if the waiting thread no longer exists. */ Thread_Control *_MPCI_Process_response ( @@ -335,7 +337,7 @@ Thread_Control *_MPCI_Process_response ( ); /** - * @brief Receive and process all packets + * @brief Receive and process all packets. * * This is the server thread which receives and processes all MCPI packets. * @@ -346,14 +348,14 @@ Thread _MPCI_Receive_server( ); /** - * @brief Announce the availability of a packet + * @brief Announce the availability of a packet. * * This routine informs RTEMS of the availability of an MPCI packet. */ void _MPCI_Announce ( void ); /** - * @brief Perform a process on another node + * @brief Perform a process on another node. * * This routine performs a remote procedure call so that a * process operation can be performed on another node. @@ -385,7 +387,7 @@ void _MPCI_Internal_packets_Send_process_packet ( */ /** - * @brief Perform requested action from another node + * @brief Perform requested action from another node. * * This routine performs the actions specific to this package for * the request from another node. @@ -417,7 +419,7 @@ void _MPCI_Internal_packets_Process_packet ( */ /** - * @brief Obtain an internal thread + * @brief Obtain an internal thread. * * This routine is used to obtain an internal threads MP packet. */ diff --git a/cpukit/score/include/rtems/score/mppkt.h b/cpukit/score/include/rtems/score/mppkt.h index 85d80b85b3..7dca30612d 100644 --- a/cpukit/score/include/rtems/score/mppkt.h +++ b/cpukit/score/include/rtems/score/mppkt.h @@ -1,6 +1,8 @@ /** * @file rtems/score/mppkt.h * + * @brief Specification for the Packet Handler + * * This package is the specification for the Packet Handler. * This handler defines the basic packet and provides * mechanisms to utilize packets based on this prefix. diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h index 91173c335a..d6b8f48d35 100644 --- a/cpukit/score/include/rtems/score/object.h +++ b/cpukit/score/include/rtems/score/object.h @@ -1,6 +1,8 @@ /** * @file rtems/score/object.h * + * @brief Constants and Structures Associated with the Object Handler + * * This include file contains all the constants and structures associated * with the Object Handler. This Handler provides mechanisms which * can be used to initialize and manipulate all objects which have ids. @@ -40,6 +42,7 @@ extern "C" { * * @brief Provides services for all APIs. */ +/**@{*/ /** * @defgroup ScoreCPU CPU Architecture Support @@ -48,12 +51,14 @@ extern "C" { * * @brief Provides CPU architecture dependent services. */ +/**@{*/ /** * @defgroup ScoreObject Object Handler * * @ingroup Score */ +/**@{*/ /** * The following type defines the control block used to manage @@ -502,20 +507,18 @@ void _Objects_Initialize_information ( * * @param[in] api is the API of interest * - * @return A positive integer on success and 0 otherwise. + * @retval A positive integer on success and 0 otherwise. */ unsigned int _Objects_API_maximum_class( uint32_t api ); /** - * @brief Allocate Object + * @brief Allocate an object. * - * This function allocates a object control block from + * This function allocates an object control block from * the inactive chain of free object control blocks. * - * @brief Allocate Object - * * @param[in] information points to an object class information block. */ Objects_Control *_Objects_Allocate( @@ -523,9 +526,9 @@ Objects_Control *_Objects_Allocate( ); /** - * @brief Free Object + * @brief Free an object. * - * This function frees a object control block to the + * This function frees an object control block to the * inactive chain of free object control blocks. * * @param[in] information points to an object class information block. @@ -583,7 +586,8 @@ typedef enum { #define OBJECTS_NAME_ERRORS_LAST OBJECTS_INVALID_NODE /** - * @brief Object Name To Id + * @brief Converts an object name to an Id. + * * This method converts an object name to an Id. It performs a look up * using the object information block for this object class. * @@ -592,7 +596,7 @@ typedef enum { * @param[in] node is the set of nodes to search. * @param[in] id will contain the Id if the search is successful. * - * @return This method returns one of the values from the + * @retval This method returns one of the values from the * @ref Objects_Name_or_id_lookup_errors enumeration to indicate * successful or failure. On success @a id will contain the Id of * the requested object. @@ -606,7 +610,7 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32( #if defined(RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES) /** - * @brief Object ID to Name + * @brief Converts an object name to an Id. * * This method converts an object name to an Id. It performs a look up * using the object information block for this object class. @@ -615,7 +619,7 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32( * @param[in] name is the name of the object to find. * @param[in] id will contain the Id if the search is successful. * - * @return This method returns one of the values from the + * @retval This method returns one of the values from the * @ref Objects_Name_or_id_lookup_errors enumeration to indicate * successful or failure. On success @a id will contain the Id of * the requested object. @@ -628,7 +632,8 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id_string( #endif /** - * @brief Object Id To Name + * @brief Implements the common portion of the object Id to name directives. + * * This function implements the common portion of the object Id * to name directives. This function returns the name * associated with object id. @@ -636,7 +641,7 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id_string( * @param[in] id is the Id of the object whose name we are locating. * @param[in] name will contain the name of the object, if found. * - * @return This method returns one of the values from the + * @retval This method returns one of the values from the * @ref Objects_Name_or_id_lookup_errors enumeration to indicate * successful or failure. On success @a name will contain the name of * the requested object. @@ -649,7 +654,8 @@ Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( ); /** - * @brief Get Object + * @brief Maps object ids to object control blocks. + * * This function maps object ids to object control blocks. * If id corresponds to a local object, then it returns * the_object control pointer which maps to id and location @@ -663,7 +669,7 @@ Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( * @param[in] id is the Id of the object whose name we are locating. * @param[in] location will contain an indication of success or failure. * - * @return This method returns one of the values from the + * @retval This method returns one of the values from the * @ref Objects_Name_or_id_lookup_errors enumeration to indicate * successful or failure. On success @a id will contain the Id of * the requested object. @@ -680,7 +686,7 @@ Objects_Control *_Objects_Get ( ); /** - * @brief Object Get Isr Disable + * @brief Maps object ids to object control blocks. * * This function maps object ids to object control blocks. * If id corresponds to a local object, then it returns @@ -696,7 +702,7 @@ Objects_Control *_Objects_Get ( * @param[in] location will contain an indication of success or failure. * @param[in] level is the interrupt level being turned. * - * @return This method returns one of the values from the + * @retval This method returns one of the values from the * @ref Objects_Name_or_id_lookup_errors enumeration to indicate * successful or failure. On success @a name will contain the name of * the requested object. @@ -714,7 +720,7 @@ Objects_Control *_Objects_Get_isr_disable( ); /** - * @brief Get No protection Object + * @brief Maps object ids to object control blocks. * * This function maps object ids to object control blocks. * If id corresponds to a local object, then it returns @@ -729,7 +735,7 @@ Objects_Control *_Objects_Get_isr_disable( * @param[in] id is the Id of the object whose name we are locating. * @param[in] location will contain an indication of success or failure. * - * @return This method returns one of the values from the + * @retval This method returns one of the values from the * @ref Objects_Name_or_id_lookup_errors enumeration to indicate * successful or failure. On success @a id will contain the Id of * the requested object. @@ -753,7 +759,7 @@ Objects_Control *_Objects_Get_no_protection( * @param[in] location_p will contain an indication of success or failure. * @param[in] next_id_p is the Id of the next object we will look at. * - * @return This method returns the pointer to the object located or + * @retval This method returns the pointer to the object located or * NULL on error. */ Objects_Control *_Objects_Get_next( @@ -764,7 +770,7 @@ Objects_Control *_Objects_Get_next( ); /** - * @brief Get Object Information + * @brief Get object information. * * This function return the information structure given * an the API and Class. This can be done independent of @@ -773,7 +779,7 @@ Objects_Control *_Objects_Get_next( * @param[in] the_api indicates the API for the information we want * @param[in] the_class indicates the Class for the information we want * - * @return This method returns a pointer to the Object Information Table + * @retval This method returns a pointer to the Object Information Table * for the class of objects which corresponds to this object ID. */ Objects_Information *_Objects_Get_information( @@ -782,14 +788,14 @@ Objects_Information *_Objects_Get_information( ); /** - * @brief Get Information of an Object from an ID + * @brief Get information of an object from an ID. * * This function return the information structure given * an @a id of an object. * * @param[in] id is the object ID to get the information from * - * @return This method returns a pointer to the Object Information Table + * @retval This method returns a pointer to the Object Information Table * for the class of objects which corresponds to this object ID. */ Objects_Information *_Objects_Get_information_id( @@ -797,7 +803,7 @@ Objects_Information *_Objects_Get_information_id( ); /** - * @brief _Objects_Get_name_as_string + * @brief Gets object name in the form of a C string. * * This method objects the name of an object and returns its name * in the form of a C string. It attempts to be careful about @@ -807,7 +813,7 @@ Objects_Information *_Objects_Get_information_id( * @param[in] length indicates the length of the caller's buffer * @param[in] name points a string which will be filled in. * - * @return This method returns @a name or NULL on error. @a *name will + * @retval This method returns @a name or NULL on error. @a *name will * contain the name if successful. */ char *_Objects_Get_name_as_string( @@ -817,7 +823,7 @@ char *_Objects_Get_name_as_string( ); /** - * @brief Set Objects Name + * @brief Set objects name. * * This method sets the object name to either a copy of a string * or up to the first four characters of the string based upon @@ -827,7 +833,7 @@ char *_Objects_Get_name_as_string( * @param[in] the_object is the object to operate upon * @param[in] name is a pointer to the name to use * - * @return If successful, true is returned. Otherwise false is returned. + * @retval If successful, true is returned. Otherwise false is returned. */ bool _Objects_Set_name( Objects_Information *information, @@ -836,7 +842,7 @@ bool _Objects_Set_name( ); /** - * @brief Removes Object from Namespace + * @brief Removes object from namespace. * * This function removes @a the_object from the namespace. * @@ -849,7 +855,7 @@ void _Objects_Namespace_remove( ); /** - * @brief Close Object + * @brief Close object. * * This function removes the_object control pointer and object name * in the Local Pointer and Local Name Tables. @@ -867,7 +873,7 @@ void _Objects_Close( * * @param[in] information The object information table. * - * @return The count of active objects. + * @retval The count of active objects. */ Objects_Maximum _Objects_Active_count( const Objects_Information *information @@ -886,5 +892,8 @@ Objects_Maximum _Objects_Active_count( } #endif +/**@}*/ +/**@}*/ +/**@}*/ #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/objectmp.h b/cpukit/score/include/rtems/score/objectmp.h index 4748c61e2b..1ef15b3c72 100644 --- a/cpukit/score/include/rtems/score/objectmp.h +++ b/cpukit/score/include/rtems/score/objectmp.h @@ -1,6 +1,8 @@ /** * @file rtems/score/objectmp.h * + * @brief Data Associated with the Manipulation of Global RTEMS Objects + * * This include file contains all the constants and structures associated * with the manipulation of Global RTEMS Objects. */ @@ -47,7 +49,8 @@ typedef struct { } Objects_MP_Control; /** - * @brief Objects MP Handler initialization + * @brief Intializes the inactive global object chain + * based on the maximum number of global objects configured. * * This routine intializes the inactive global object chain * based on the maximum number of global objects configured. @@ -55,7 +58,8 @@ typedef struct { void _Objects_MP_Handler_initialization(void); /** - * @brief Objects MP Handler Early Initialization + * @brief Intializes the global object node number + * used in the ID field of all objects. * * This routine intializes the global object node number * used in the ID field of all objects. @@ -63,7 +67,8 @@ void _Objects_MP_Handler_initialization(void); void _Objects_MP_Handler_early_initialization(void); /** - * @brief Objects MP Open + * @brief Place the specified global object in the + * specified information table. * * This routine place the specified global object in the * specified information table. @@ -85,7 +90,8 @@ void _Objects_MP_Open ( ); /** - * @brief Objects MP Allocate and open + * @brief Allocates a global object control block + * and places it in the specified information table. * * This routine allocates a global object control block * and places it in the specified information table. If the @@ -110,7 +116,7 @@ bool _Objects_MP_Allocate_and_open ( ); /** - * @brief Objects MP Close + * @brief Removes a global object from the specified information table. * * This routine removes a global object from the specified * information table and deallocates the global object control block. @@ -121,7 +127,8 @@ void _Objects_MP_Close ( ); /** - * @brief Objects MP Global name search + * @brief Look for the object with the_name in the global + * object tables indicated by information. * * This routine looks for the object with the_name in the global * object tables indicated by information. It returns the ID of the @@ -133,7 +140,7 @@ void _Objects_MP_Close ( * @param[in] nodes_to_search indicates the set of nodes to search. * @param[in] the_id will contain the Id of the object if found. * - * @return This method returns one of the + * @retval This method returns one of the * @ref Objects_Name_or_id_lookup_errors. If successful, @a the_id * will contain the Id of the object. */ @@ -145,7 +152,8 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( ); /** - * @brief Objects MP Is remote + * @brief Searches the Global Object Table managed + * by information for the object indicated by ID. * * This function searches the Global Object Table managed * by information for the object indicated by ID. If the object @@ -159,7 +167,7 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( * @param[in] location will contain the location of the object. * @param[in] the_object will contain a pointer to the object. * - * @return This method fills in @a location to indicate successful location + * @retval This method fills in @a location to indicate successful location * of the object or error. On success, @a the_object will be * filled in. */ diff --git a/cpukit/score/include/rtems/score/priority.h b/cpukit/score/include/rtems/score/priority.h index 3c6f7771f6..091351720c 100644 --- a/cpukit/score/include/rtems/score/priority.h +++ b/cpukit/score/include/rtems/score/priority.h @@ -1,6 +1,8 @@ /** * @file rtems/score/priority.h * + * @brief Thread Priority Manipulation Routines + * * This include file contains all thread priority manipulation routines. * This Handler provides mechanisms which can be used to * initialize and manipulate thread priorities. diff --git a/cpukit/score/include/rtems/score/prioritybitmap.h b/cpukit/score/include/rtems/score/prioritybitmap.h index 4a9966cef7..8e8f21ce34 100644 --- a/cpukit/score/include/rtems/score/prioritybitmap.h +++ b/cpukit/score/include/rtems/score/prioritybitmap.h @@ -1,6 +1,8 @@ /** * @file rtems/score/prioritybitmap.h * + * @brief Manipulation Routines for the Bitmap Priority Queue Implementation + * * This include file contains all thread priority manipulation routines for * the bit map priority queue implementation. */ @@ -18,8 +20,9 @@ #define _RTEMS_SCORE_PRIORITYBITMAP_H /** - * @addtogroup ScorePriority + * @defgroup ScorePriorityBitmap Bitmap Priority Thread Routines * + * @ingroup Score */ /**@{*/ @@ -86,7 +89,7 @@ typedef struct { * * @param[in] _bit_number is the bit number for which we need a mask * - * @return the priority bit mask + * @retval the priority bit mask * * @note This may simply be a pass through to a CPU dependent implementation. */ @@ -100,7 +103,7 @@ typedef struct { * * @param[in] _priority is the priority for which we need the index. * - * @return This method returns the array index into the priority bit map. + * @retval This method returns the array index into the priority bit map. * * @note This may simply be a pass through to a CPU dependent implementation. */ diff --git a/cpukit/score/include/rtems/score/protectedheap.h b/cpukit/score/include/rtems/score/protectedheap.h index 8c2f2cd66c..29ee62dbfb 100644 --- a/cpukit/score/include/rtems/score/protectedheap.h +++ b/cpukit/score/include/rtems/score/protectedheap.h @@ -3,7 +3,7 @@ * * @ingroup ScoreProtHeap * - * @brief Protected Heap Handler API. + * @brief Protected Heap Handler API */ /* @@ -34,8 +34,8 @@ extern "C" { * * The @ref ScoreAllocatorMutex is used to protect the heap accesses. * - * @{ */ +/**@{**/ /** * @brief See _Heap_Initialize(). diff --git a/cpukit/score/include/rtems/score/rbtree.h b/cpukit/score/include/rtems/score/rbtree.h index 5a03d7ca8d..55b5c55720 100644 --- a/cpukit/score/include/rtems/score/rbtree.h +++ b/cpukit/score/include/rtems/score/rbtree.h @@ -1,6 +1,8 @@ /** * @file rtems/score/rbtree.h * + * @brief Constants and Structures Associated with the Red-Black Tree Handler + * * This include file contains all the constants and structures associated * with the Red-Black Tree Handler. */ @@ -80,7 +82,7 @@ struct RBTree_Node_struct { }; /** - * @brief macro to return the structure containing the @a node. + * @brief Macro to return the structure containing the @a node. * * This macro returns a pointer of type @a container_type that points * to the structure containing @a node, where @a node_field_name is the @@ -184,12 +186,12 @@ RBTree_Control name = RBTREE_INITIALIZER_EMPTY(name) RBTree_Node name = RBTREE_NODE_INITIALIZER_EMPTY(name) /** - * @brief Initialize a RBTree Header + * @brief Initialize a RBTree Header. * * This routine initializes @a the_rbtree structure to manage the * contiguous array of @a number_nodes nodes which starts at * @a starting_address. Each node is of @a node_size bytes. - * + * * @param[in] the_rbtree is the pointer to rbtree header * @param[in] starting_address is the starting address of first node * @param[in] number_nodes is the number of nodes in rbtree @@ -205,13 +207,13 @@ void _RBTree_Initialize( ); /** - * @brief Obtain the min or max node of a rbtree + * @brief Obtain the min or max node of a rbtree. * * This function removes the min or max node from @a the_rbtree and returns * a pointer to that node. If @a the_rbtree is empty, then NULL is returned. * @a dir specifies whether to return the min (0) or max (1). * - * @return This method returns a pointer to a node. If a node was removed, + * @retval This method returns a pointer to a node. If a node was removed, * then a pointer to that node is returned. If @a the_rbtree was * empty, then NULL is returned. * @@ -222,37 +224,50 @@ RBTree_Node *_RBTree_Get( RBTree_Direction dir ); +/** @brief Find the node with given key in the tree + * + * This function returns a pointer to the node in @a the_rbtree + * having key equal to key of @a the_node if it exists, + * and NULL if not. @a the_node has to be made up before a search. + * + * @note If the tree is not unique and contains duplicate keys, the set + * of duplicate keys acts as FIFO. + */ +RBTree_Node *_RBTree_Find_unprotected( + const RBTree_Control *the_rbtree, + const RBTree_Node *the_node +); + /** - * @brief Find the node with given key in the tree + * @brief Find the node with given key in the tree. * * This function returns a pointer to the node with key equal to a key * of @a the_node if it exists in the Red-Black Tree @a the_rbtree, * and NULL if not. - * + * * @param[in] the_rbtree pointer to rbtree control * @param[in] the_node node with the key to search for - * @return This method returns pointer to control header of rbtree. * + * @retval This method returns pointer to control header of rbtree. * * If there is no control header available (the node is not part * of a tree), then NULL is returned. * * * - INTERRUPT LATENCY: - * + single case + * + single case */ RBTree_Node *_RBTree_Find( - RBTree_Control *the_rbtree, - RBTree_Node *the_node + const RBTree_Control *the_rbtree, + const RBTree_Node *the_node ); /** - * @brief Find the control structure of the tree containing the given node + * @brief Find the control structure of the tree containing the given node. * - * This function returns a pointer called @a return_header to the control structure of the tree - * containing @a the_node, if it exists, and @a NULL if not. + * This function returns a pointer called @a return_header to the + * control structure of the tree containing @a the_node, if it exists, + * and @a NULL if not. * * @param[in] the_node is the pointer to the rbtree node. - * @param[out] return_header is the pointer to control header of rbtree. - * @param[out] NULL is returned if there is no control header available. - * + * * -INTERRUPT LATENCY: * + single case */ @@ -261,7 +276,7 @@ RBTree_Control *_RBTree_Find_header( ); /** - * @brief Insert a Node (unprotected) + * @brief Insert @a the_node on the Red-Black Tree @a the_rbtree (unprotected). * * This routine inserts @a the_node on the Red-Black Tree @a the_rbtree. * @@ -279,7 +294,7 @@ RBTree_Node *_RBTree_Insert_unprotected( ); /** - * @brief Insert a node on a rbtree + * @brief Insert a node on a rbtree. * * This routine inserts @a the_node on the tree @a the_rbtree. * @@ -298,7 +313,7 @@ RBTree_Node *_RBTree_Insert( /** - * @brief Extract a Node (unprotected) + * @brief Extracts (removes) @a the_node from @a the_rbtree (unprotected). * * This routine extracts (removes) @a the_node from @a the_rbtree. * @@ -311,7 +326,7 @@ void _RBTree_Extract_unprotected( ); /** - * @brief Delete a node from the rbtree + * @brief Delete a node from the rbtree. * * This routine deletes @a the_node from @a the_rbtree. * diff --git a/cpukit/score/include/rtems/score/scheduler.h b/cpukit/score/include/rtems/score/scheduler.h index 117f86a37a..5c35a36de1 100644 --- a/cpukit/score/include/rtems/score/scheduler.h +++ b/cpukit/score/include/rtems/score/scheduler.h @@ -1,6 +1,8 @@ /** * @file rtems/score/scheduler.h * + * @brief Constants and Structures Associated with the Scheduler + * * This include file contains all the constants and structures associated * with the scheduler. */ @@ -129,7 +131,7 @@ extern Scheduler_Control _Scheduler; (_Scheduler_Priority_compare(_p1,_p2) > 0) /** - * @brief Scheduler is priority higher than + * @brief Initializes the scheduler to the policy chosen by the user. * * This routine initializes the scheduler to the policy chosen by the user * through confdefs, or to the priority scheduler with ready chains by diff --git a/cpukit/score/include/rtems/score/schedulercbs.h b/cpukit/score/include/rtems/score/schedulercbs.h index d0bc5ee109..53452e044a 100644 --- a/cpukit/score/include/rtems/score/schedulercbs.h +++ b/cpukit/score/include/rtems/score/schedulercbs.h @@ -1,6 +1,8 @@ /** * @file rtems/score/schedulercbs.h * + * @brief Thread manipulation for the CBS scheduler + * * This include file contains all the constants and structures associated * with the manipulation of threads for the CBS scheduler. */ @@ -31,8 +33,9 @@ extern "C" { #endif /** - * @addtogroup ScoreScheduler + * @defgroup ScoreSchedulerCBS CBS Scheduler * + * @ingroup ScoreScheduler */ /**@{*/ @@ -131,12 +134,12 @@ typedef struct { extern Scheduler_CBS_Server **_Scheduler_CBS_Server_list; /** - * @brief Unblocks a Thread from the Queue + * @brief Unblocks a thread from the queue. * * This routine adds @a the_thread to the scheduling decision, that is, * adds it to the ready queue and updates any appropriate scheduling - * variables, for example the heir thread. It is checked whether the - * remaining budget is sufficient. If not, the thread continues as a + * variables, for example the heir thread. It is checked whether the + * remaining budget is sufficient. If not, the thread continues as a * new job in order to protect concurrent threads. * * @param[in] the_thread will be unblocked. @@ -148,7 +151,7 @@ void _Scheduler_CBS_Unblock( ); /** - * @brief Scheduler CBS Release job + * @brief Called when a new job of task is released. * * This routine is called when a new job of task is released. * It is called only from Rate Monotonic manager in the beginning @@ -169,16 +172,16 @@ void _Scheduler_CBS_Release_job ( * * Initializes the CBS library. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Initialize(void); /** - * @brief Attach Scheduler CBS Thread + * @brief Attach a task to an already existing server. * * Attach a task to an already existing server. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Attach_thread ( Scheduler_CBS_Server_id server_id, @@ -186,11 +189,11 @@ int _Scheduler_CBS_Attach_thread ( ); /** - * @brief _Scheduler_CBS_Detach_thread + * @brief Detach from the CBS Server. * * Detach from the CBS Server. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Detach_thread ( Scheduler_CBS_Server_id server_id, @@ -198,20 +201,20 @@ int _Scheduler_CBS_Detach_thread ( ); /** - * @brief _Scheduler_CBS_Cleanup + * @brief Cleanup resources associated to the CBS Library. * * Cleanup resources associated to the CBS Library. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Cleanup (void); /** - * @brief _Scheduler_CBS_Create_server + * @brief Create a new server with specified parameters. * * Create a new server with specified parameters. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Create_server ( Scheduler_CBS_Parameters *params, @@ -220,25 +223,25 @@ int _Scheduler_CBS_Create_server ( ); /** - * @brief _Scheduler_CBS_Destroy_server + * @brief Detach all tasks from a server and destroy it. * * Detach all tasks from a server and destroy it. * * @param[in] server_id is the ID of the server * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Destroy_server ( Scheduler_CBS_Server_id server_id ); /** - * @brief _Scheduler_CBS_Get_approved_budget + * @brief Retrieve the approved budget. * * Retrieve the budget that has been approved for the subsequent * server instances. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Get_approved_budget ( Scheduler_CBS_Server_id server_id, @@ -246,11 +249,11 @@ int _Scheduler_CBS_Get_approved_budget ( ); /** - * @brief _Scheduler_CBS_Get_remaining_budget + * @brief Retrieve remaining budget for the current server instance. * * Retrieve remaining budget for the current server instance. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Get_remaining_budget ( Scheduler_CBS_Server_id server_id, @@ -258,15 +261,15 @@ int _Scheduler_CBS_Get_remaining_budget ( ); /** - * @brief Get relative time info + * @brief Get relative time info. * * Retrieve time info relative to @a server_id. The server status code is returned. * * @param[in] server_id is the server to get the status code from. * @param[in] exec_time is the execution time. - * @param[in] abs_time is not apparently used. + * @param[in] abs_time is not apparently used. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Get_execution_time ( Scheduler_CBS_Server_id server_id, @@ -275,11 +278,11 @@ int _Scheduler_CBS_Get_execution_time ( ); /** - * @brief _Scheduler_CBS_Get_parameters + * @brief Retrieve CBS scheduling parameters. * * Retrieve CBS scheduling parameters. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Get_parameters ( Scheduler_CBS_Server_id server_id, @@ -287,12 +290,12 @@ int _Scheduler_CBS_Get_parameters ( ); /** - * @brief Scheduler CBS Get Server id + * @brief Get a thread server id. * * Get a thread server id, or SCHEDULER_CBS_ERROR_NOT_FOUND if it is not * attached to any server. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Get_server_id ( rtems_id task_id, @@ -300,14 +303,14 @@ int _Scheduler_CBS_Get_server_id ( ); /** - * @brief Set Parameters for CBS Scheduling + * @brief Set parameters for CBS scheduling. * * Change CBS scheduling parameters. * * @param[in] server_id is the ID of the server. * @param[in] parameters are the parameters to set. * - * @return status code. + * @retval status code. */ int _Scheduler_CBS_Set_parameters ( Scheduler_CBS_Server_id server_id, @@ -315,7 +318,7 @@ int _Scheduler_CBS_Set_parameters ( ); /** - * @brief Scheduler CBS Budget overrun + * @brief Invoked when a limited time quantum is exceeded. * * This routine is invoked when a limited time quantum is exceeded. */ @@ -324,7 +327,7 @@ void _Scheduler_CBS_Budget_callout( ); /** - * @brief Scheduler CBS Allocate + * @brief Allocates CBS specific information of @a the_thread. * * This routine allocates CBS specific information of @a the_thread. * diff --git a/cpukit/score/include/rtems/score/scheduleredf.h b/cpukit/score/include/rtems/score/scheduleredf.h index 8381184858..24f9a1ac32 100644 --- a/cpukit/score/include/rtems/score/scheduleredf.h +++ b/cpukit/score/include/rtems/score/scheduleredf.h @@ -1,6 +1,8 @@ /** * @file rtems/score/scheduleredf.h * + * @brief Data Related to the Manipulation of Threads for the EDF Scheduler + * * This include file contains all the constants and structures associated * with the manipulation of threads for the EDF scheduler. */ @@ -27,8 +29,9 @@ extern "C" { #endif /** - * @addtogroup ScoreScheduler + * @defgroup ScoreSchedulerEDF EDF Scheduler * + * @ingroup ScoreScheduler */ /**@{*/ @@ -98,14 +101,14 @@ typedef struct { extern RBTree_Control _Scheduler_EDF_Ready_queue; /** - * @brief Scheduler EDF Initialize + * @brief Initialize EDF scheduler. * * This routine initializes the EDF scheduler. */ void _Scheduler_EDF_Initialize( void ); /** - * @brief Removes Thread from Ready Queue + * @brief Removes thread from ready queue. * * This routine removes @a the_thread from the scheduling decision, * that is, removes it from the ready queue. It performs @@ -119,7 +122,8 @@ void _Scheduler_EDF_Block( ); /** - * @brief Scheduler EDF Schedule + * @brief Sets the heir thread to be the next ready thread + * in the rbtree ready queue. * * This kernel routine sets the heir thread to be the next ready thread * in the rbtree ready queue. @@ -127,7 +131,7 @@ void _Scheduler_EDF_Block( void _Scheduler_EDF_Schedule( void ); /** - * @brief Scheduler EDF Allocate + * @brief Allocates EDF specific information of @a the_thread. * * This routine allocates EDF specific information of @a the_thread. * @@ -139,7 +143,7 @@ void *_Scheduler_EDF_Allocate( ); /** - * @brief Frees EDF information of a thread + * @brief Frees EDF information of a thread. * * This routine frees the EDF specific information of @a the_thread. * @@ -151,7 +155,7 @@ void _Scheduler_EDF_Free( ); /** - * @brief Scheduler EDF Update + * @brief Updates position in the ready queue of @a the_thread. * * This routine updates position in the ready queue of @a the_thread. * @@ -163,7 +167,7 @@ void _Scheduler_EDF_Update( ); /** - * @brief Scheduler EDF Unblock + * @brief Adds @a the_thread to the scheduling decision. * * This routine adds @a the_thread to the scheduling decision, that is, * adds it to the ready queue and updates any appropriate scheduling @@ -176,7 +180,9 @@ void _Scheduler_EDF_Unblock( ); /** - * @brief Scheduler EDF Yield + * @brief invoked when a thread wishes to voluntarily + * transfer control of the processor to another thread + * with equal deadline. * * This routine is invoked when a thread wishes to voluntarily * transfer control of the processor to another thread in the queue with @@ -189,7 +195,7 @@ void _Scheduler_EDF_Unblock( void _Scheduler_EDF_Yield( void ); /** - * @brief Scheduler EDF Enqueue + * @brief Put @a the_thread to the rbtree ready queue. * * This routine puts @a the_thread to the rbtree ready queue. * @@ -200,7 +206,7 @@ void _Scheduler_EDF_Enqueue( ); /** - * @brief Enqueues a thread to the ready queue + * @brief Enqueue a thread to the ready queue. * * This routine puts @a the_thread to the rbtree ready queue. * For the EDF scheduler this is the same as @a _Scheduler_EDF_Enqueue. @@ -212,7 +218,8 @@ void _Scheduler_EDF_Enqueue_first( ); /** - * @brief Scheduler EDF Extract + * @brief Remove a specific thread from the scheduler's set + * of ready threads. * * This routine removes a specific thread from the scheduler's set * of ready threads. @@ -224,12 +231,12 @@ void _Scheduler_EDF_Extract( ); /** - * @brief Scheduler EDF Priority compare + * @brief Explicitly compare absolute dedlines (priorities) of threads. * * This routine explicitly compares absolute dedlines (priorities) of threads. * In case of EDF scheduling time overflow is taken into account. * - * @return >0 for p1 > p2; 0 for p1 == p2; <0 for p1 < p2. + * @retval >0 for p1 > p2; 0 for p1 == p2; <0 for p1 < p2. */ int _Scheduler_EDF_Priority_compare ( Priority_Control p1, @@ -237,7 +244,7 @@ int _Scheduler_EDF_Priority_compare ( ); /** - * @brief Scheduler EDF Release job + * @brief Called when a new job of task is released. * * This routine is called when a new job of task is released. * It is called only from Rate Monotonic manager in the beginning diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h index 3432937062..f97bb7f075 100644 --- a/cpukit/score/include/rtems/score/schedulerpriority.h +++ b/cpukit/score/include/rtems/score/schedulerpriority.h @@ -1,6 +1,8 @@ /** * @file rtems/score/schedulerpriority.h * + * @brief Thread Manipulation with the Priority-Based Scheduler + * * This include file contains all the constants and structures associated * with the manipulation of threads for the priority-based scheduler. */ @@ -26,8 +28,9 @@ extern "C" { #endif /** - * @addtogroup ScoreScheduler + * @defgroup ScoreSchedulerDPS Deterministic Priority-based Scheduler * + * @ingroup ScoreScheduler */ /**@{*/ @@ -64,13 +67,13 @@ typedef struct { } Scheduler_priority_Per_thread; /** - * @brief Initialize Scheduler Priority + * @brief Initializes the priority scheduler. * This routine initializes the priority scheduler. */ void _Scheduler_priority_Initialize(void); /** - * @brief Scheduler priority Block + * @brief Removes @a the_thread from the scheduling decision. * * This routine removes @a the_thread from the scheduling decision, * that is, removes it from the ready queue. It performs @@ -84,7 +87,7 @@ void _Scheduler_priority_Block( ); /** - * @brief schedule entry point + * @brief Sets the heir thread to be the next ready thread. * * This kernel routine sets the heir thread to be the next ready thread * by invoking the_scheduler->ready_queue->operations->first(). @@ -92,7 +95,7 @@ void _Scheduler_priority_Block( void _Scheduler_priority_Schedule(void); /** - * @brief Allocate Scheduler Priority + * @brief Allocates @a the_thread->scheduler. * * This routine allocates @a the_thread->scheduler. * @@ -104,7 +107,7 @@ void * _Scheduler_priority_Allocate( ); /** - * @brief Free Scheduler Priority + * @brief Frees @a the_thread->scheduler. * * This routine frees @a the_thread->scheduler. * @@ -116,7 +119,7 @@ void _Scheduler_priority_Free( ); /** - * @brief Update Scheduler priority + * @brief Update the scheduler priority. * This routine updates @a the_thread->scheduler based on @a the_scheduler * structures and thread state. * @@ -128,7 +131,7 @@ void _Scheduler_priority_Update( ); /** - * @brief Scheduler Priority Unblock + * @brief Add @a the_thread to the scheduling decision. * * This routine adds @a the_thread to the scheduling decision, * that is, adds it to the ready queue and @@ -141,7 +144,7 @@ void _Scheduler_priority_Unblock( ); /** - * @brief Scheduler Priority Yield + * @brief Remove the running THREAD to the rear of this chain. * * This routine is invoked when a thread wishes to voluntarily * transfer control of the processor to another thread in the queue. @@ -160,7 +163,7 @@ void _Scheduler_priority_Unblock( void _Scheduler_priority_Yield( void ); /** - * @brief Scheduler Priority Enqueue + * @brief Puts @a the_thread on to the priority-based ready queue. * * This routine puts @a the_thread on to the priority-based ready queue. * @@ -171,7 +174,7 @@ void _Scheduler_priority_Enqueue( ); /** - * @brief Scheduler Priority Enqueue First + * @brief Puts @a the_thread to the head of the ready queue. * * This routine puts @a the_thread to the head of the ready queue. * For priority-based ready queues, the thread will be the first thread @@ -184,7 +187,7 @@ void _Scheduler_priority_Enqueue_first( ); /** - * @brief Removes a specific thread from scheduler + * @brief Remove a specific thread from scheduler. * * This routine removes a specific thread from the scheduler's set * of ready threads. @@ -196,7 +199,7 @@ void _Scheduler_priority_Extract( ); /** - * @brief Scheduler priority Priority compare + * @brief Compare two priorities. * * This routine compares two priorities. */ @@ -206,7 +209,7 @@ int _Scheduler_priority_Priority_compare( ); /** - * @brief Scheduler priority Release job + * @brief Called when a new job of task is released. * * This routine is called when a new job of task is released. * @@ -220,7 +223,7 @@ void _Scheduler_priority_Release_job ( ); /** - * @brief Deterministic Priority Scheduler Tick Method + * @brief Determines if the current thread allows timeslicing. * * This routine is invoked as part of processing each clock tick. * It is responsible for determining if the current thread allows diff --git a/cpukit/score/include/rtems/score/schedulersimple.h b/cpukit/score/include/rtems/score/schedulersimple.h index 66b4018b50..df52a586be 100644 --- a/cpukit/score/include/rtems/score/schedulersimple.h +++ b/cpukit/score/include/rtems/score/schedulersimple.h @@ -1,10 +1,13 @@ /** * @file rtems/score/schedulersimple.h * + * @brief Manipulation of Threads Simple-Priority-Based Ready Queue + * * This include file contains all the constants and structures associated * with the manipulation of threads on a simple-priority-based ready queue. - * - * + */ + +/* * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,8 +19,9 @@ #define _RTEMS_SCORE_SCHEDULERSIMPLE_H /** - * @addtogroup ScoreScheduler + * @defgroup ScoreSchedulerSimple Simple Priority Scheduler * + * @ingroup ScoreScheduler */ /**@{*/ @@ -50,7 +54,7 @@ extern "C" { } /** - * @brief Initializes simple scheduler + * @brief Initialize simple scheduler. * * This routine initializes the simple scheduler. */ @@ -64,7 +68,8 @@ void _Scheduler_simple_Initialize( void ); void _Scheduler_simple_Schedule( void ); /** - * @brief Simple Schedule + * @brief Invoked when a thread wishes to voluntarily + * transfer control of the processor to another thread in the queue. * * This routine is invoked when a thread wishes to voluntarily * transfer control of the processor to another thread in the queue. @@ -79,7 +84,7 @@ void _Scheduler_simple_Schedule( void ); void _Scheduler_simple_Yield( void ); /** - * @brief Removes a thread from the queue + * @brief Remove a simple-priority-based thread from the queue. * * This routine removes @a the_thread from the scheduling decision, * that is, removes it from the ready queue. It performs @@ -93,7 +98,8 @@ void _Scheduler_simple_Block( ); /** - * @brief Scheduler Simple Handler / Unblock + * @brief Unblock a simple-priority-based thread. + * * This routine adds @a the_thread to the scheduling decision, * that is, adds it to the ready queue and * updates any appropriate scheduling variables, for example the heir thread. @@ -105,7 +111,7 @@ void _Scheduler_simple_Unblock( ); /** - * @brief Removes a thread from a simple queue + * @brief Removes a simple-priority-based thread from a simple queue. * * This routine removes a specific thread from the specified * simple-based ready queue. @@ -117,7 +123,7 @@ void _Scheduler_simple_Extract( ); /** - * @brief Puts thread onto the ready queue + * @brief Puts simple-priority-based thread onto the ready queue. * * This routine puts @a the_thread on to the ready queue. * @@ -128,7 +134,8 @@ void _Scheduler_simple_Enqueue( ); /** - * @brief Scheduler simple Enqueue first + * @brief Put simple-priority-based @a the_thread to + * the head of the ready queue. * * This routine puts @a the_thread to the head of the ready queue. * The thread will be the first thread at its priority level. @@ -140,7 +147,7 @@ void _Scheduler_simple_Enqueue_first( ); /** - * @brief Returns empty placeholder for scheduler + * @brief Return empty placeholder for the simple scheduler. * * This routine is a place holder for any memeory allocation needed * by the scheduler. For the simple scheduler the routine is an empty @@ -149,7 +156,7 @@ void _Scheduler_simple_Enqueue_first( * @param[in] the_thread is the thread the scheduler is allocating * management memory for * - * @return this routine returns -1 since this is just an empty placeholder + * @retval this routine returns -1 since this is just an empty placeholder * and the return value may be defined differently by each scheduler. */ void *_Scheduler_simple_Allocate( @@ -157,7 +164,7 @@ void *_Scheduler_simple_Allocate( ); /** - * @breif Stub for schedule update + * @brief Stub for simple schedule update. * * This routine does nothing, and is used as a stub for Schedule update * The overhead of a function call will still be imposed. @@ -169,7 +176,7 @@ void _Scheduler_simple_Update( ); /** - * @brief Stub for schedule free + * @brief Stub for simple schedule free. * * This routine does nothing, and is used as a stub for Schedule free * The overhead of a function call will still be imposed. @@ -193,7 +200,8 @@ void _Scheduler_simple_Ready_queue_enqueue( ); /** - * @brief Scheduler Simple Ready Queue Enqueue First + * @brief Puts simple-priority-based @a the_thread on to the ready queue + * at the beginning of its priority group. * * This routine puts @a the_thread on to the ready queue * at the beginning of its priority group. diff --git a/cpukit/score/include/rtems/score/schedulersimplesmp.h b/cpukit/score/include/rtems/score/schedulersimplesmp.h index e915993a52..63213c6b2a 100644 --- a/cpukit/score/include/rtems/score/schedulersimplesmp.h +++ b/cpukit/score/include/rtems/score/schedulersimplesmp.h @@ -1,6 +1,8 @@ /** * @file rtems/score/schedulersimplesmp.h * + * @brief Manipulation of Threads on a Simple-Priority-Based Ready Queue + * * This include file contains all the constants and structures associated * with the manipulation of threads on a simple-priority-based ready queue. * This implementation is SMP-aware and schedules across multiple cores. @@ -21,7 +23,9 @@ #define _RTEMS_SCORE_SCHEDULERSIMPLE_SMP_H /** - * @addtogroup ScoreScheduler + * @defgroup ScoreSchedulerSMP Simple SMP Scheduler + * + * @ingroup ScoreScheduler * * The Simple SMP Scheduler attempts to faithfully implement the * behaviour of the Deterministic Priority Scheduler while spreading @@ -62,7 +66,7 @@ extern "C" { } /** - * @brief Scheduler Simple SMP Schedule Method + * @brief Allocates ready SMP threads to individual cores in an SMP system. * * This routine allocates ready threads to individual cores in an SMP * system. If the allocation results in a new heir which requires @@ -71,7 +75,7 @@ extern "C" { void _Scheduler_simple_smp_Schedule( void ); /** - * @brief Scheduler Simple SMP Block Method + * @brief Remove SMP @a the_thread from the ready queue. * * This routine removes @a the_thread from the scheduling decision, * that is, removes it from the ready queue. It performs @@ -85,7 +89,8 @@ void _Scheduler_simple_smp_Block( ); /** - * @brief Scheduler Simple SMP Unblock Method + * @brief Adds SMP @a the_thread to the ready queue and updates any + * appropriate scheduling variables, for example the heir thread. * * This routine adds @a the_thread to the scheduling decision, * that is, adds it to the ready queue and updates any appropriate @@ -98,7 +103,7 @@ void _Scheduler_simple_smp_Unblock( ); /** - * @brief Scheduler Simple SMP Tick Method + * @brief Invoked as part of processing each SMP clock tick. * * This routine is invoked as part of processing each clock tick. * It is responsible for determining if the current thread allows diff --git a/cpukit/score/include/rtems/score/smp.h b/cpukit/score/include/rtems/score/smp.h index 38ac681bcd..f4bf72edd9 100644 --- a/cpukit/score/include/rtems/score/smp.h +++ b/cpukit/score/include/rtems/score/smp.h @@ -1,6 +1,8 @@ /** * @file rtems/score/smp.h * + * @brief Interface to the SuperCore SMP Support used Internally to RTEMS + * * This include file defines the interface to the SuperCore * SMP support that is used internally to RTEMS. */ @@ -21,7 +23,7 @@ #include <rtems/score/percpu.h> /** - * @defgroup SuperCore SMP Support + * @defgroup SuperCoreSMP SMP Support * * @ingroup Score * @@ -65,7 +67,7 @@ extern "C" { #ifndef ASM /** - * @brief Number of CPUs in SMP System + * @brief Number of CPUs in a SMP system. * * This variable is set during the SMP initialization sequence to * indicate the number of CPUs in this system. @@ -73,7 +75,7 @@ extern "C" { SCORE_EXTERN uint32_t _SMP_Processor_count; /** - * @brief Make Request of Others CPUs + * @brief Request of others CPUs. * * This method is invoked by RTEMS when it needs to make a request * of the other CPUs. It should be implemented using some type of @@ -87,7 +89,7 @@ void _SMP_Broadcast_message( ); /** - * @brief Request Other Cores to Perform First Context Switch + * @brief Request other cores to perform first context switch. * * Send message to other cores requesting them to perform * their first context switch operation. @@ -95,7 +97,7 @@ void _SMP_Broadcast_message( void _SMP_Request_other_cores_to_perform_first_context_switch(void); /** - * @brief Request Dispatch on Other Cores + * @brief Request dispatch on other cores. * * Send message to other cores requesting them to perform * a thread dispatch operation. @@ -103,7 +105,7 @@ void _SMP_Request_other_cores_to_perform_first_context_switch(void); void _SMP_Request_other_cores_to_dispatch(void); /** - * @Brief Request Other Cores to Shutdown + * @brief Request other cores to shutdown. * * Send message to other cores requesting them to shutdown. */ @@ -116,5 +118,7 @@ void _SMP_Request_other_cores_to_shutdown(void); #endif #endif + +/**@}*/ #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/smplock.h b/cpukit/score/include/rtems/score/smplock.h index 611b49811f..6db8a43418 100644 --- a/cpukit/score/include/rtems/score/smplock.h +++ b/cpukit/score/include/rtems/score/smplock.h @@ -1,6 +1,8 @@ /** * @file rtems/score/smplock.h * + * @brief Interface for Atomic Locks + * * This include file defines the interface for atomic locks * which can be used in multiprocessor configurations. */ @@ -54,7 +56,7 @@ typedef struct { } SMP_lock_spinlock_nested_Control; /** - * @brief Initialize a Lock + * @brief Initialize a lock. * * This method is used to initialize the lock at @a lock. * @@ -65,13 +67,13 @@ void _SMP_lock_spinlock_simple_Initialize( ); /** - * @brief Obtain a Lock + * @brief Obtain a lock. * * This method is used to obtain the lock at @a lock. * * @param [in] lock is the address of the lock to obtain. * - * @return This method returns with processor interrupts disabled. + * @retval This method returns with processor interrupts disabled. * The previous level is returned. */ ISR_Level _SMP_lock_spinlock_simple_Obtain( @@ -79,7 +81,7 @@ ISR_Level _SMP_lock_spinlock_simple_Obtain( ); /** - * @brief Release a Lock + * @brief Release a lock. * * This method is used to release the lock at @a lock. * @@ -91,7 +93,7 @@ void _SMP_lock_spinlock_simple_Release( ); /** - * @brief Initialize a Lock + * @brief Initialize a lock. * * This method is used to initialize the lock at @a lock. * @@ -102,7 +104,7 @@ void _SMP_lock_spinlock_nested_Initialize( ); /** - * @brief Obtain a Lock + * @brief Obtain a lock. * * This method is used to obtain the lock at @a lock. ISR's are * disabled when this routine returns and it is the callers responsibility @@ -115,7 +117,7 @@ void _SMP_lock_spinlock_nested_Initialize( * * @param [in] lock is the address of the lock to obtain. * - * @return This method returns with processor interrupts disabled. + * @retval This method returns with processor interrupts disabled. * The previous level is returned. */ ISR_Level _SMP_lock_spinlock_nested_Obtain( @@ -123,9 +125,9 @@ ISR_Level _SMP_lock_spinlock_nested_Obtain( ); /** - * @brief Release a Lock + * @brief Release a lock. * - * This method is used to release the lock at @a lock. + * This method is used to release the lock at @a lock. * * @note ISR's are reenabled by this method and are expected to be * disabled upon entry to the method. diff --git a/cpukit/score/include/rtems/score/stack.h b/cpukit/score/include/rtems/score/stack.h index 1e06e366c9..9aa90425c4 100644 --- a/cpukit/score/include/rtems/score/stack.h +++ b/cpukit/score/include/rtems/score/stack.h @@ -1,6 +1,8 @@ /** * @file rtems/score/stack.h * + * @brief Information About the Thread Stack Handler + * * This include file contains all information about the thread * Stack Handler. This Handler provides mechanisms which can be used to * initialize and utilize stacks. diff --git a/cpukit/score/include/rtems/score/states.h b/cpukit/score/include/rtems/score/states.h index f71bf9399e..9fab5d4748 100644 --- a/cpukit/score/include/rtems/score/states.h +++ b/cpukit/score/include/rtems/score/states.h @@ -1,7 +1,9 @@ /** * @file rtems/score/states.h * - * This include file contains thread execution state information. + * @brief Thread Execution State Information + * + * This include file defines thread execution state information. */ /* @@ -17,7 +19,7 @@ #define _RTEMS_SCORE_STATES_H /** - * @defgroup ScoreStates Thread States Handler + * @defgroup ScoreStates SuperCore Thread States * * @ingroup Score * diff --git a/cpukit/score/include/rtems/score/sysstate.h b/cpukit/score/include/rtems/score/sysstate.h index b847dc842f..7d3d6aed59 100644 --- a/cpukit/score/include/rtems/score/sysstate.h +++ b/cpukit/score/include/rtems/score/sysstate.h @@ -3,7 +3,7 @@ * * @ingroup ScoreSysState * - * @brief System State Handler API. + * @brief System State Handler API */ /* @@ -30,9 +30,8 @@ extern "C" { * @ingroup Score * * @brief Management of the internal system state of RTEMS. - * - * @{ */ +/**@{**/ /** * @brief System states. diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index 623b56251f..248be62c95 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -1,6 +1,8 @@ /** * @file rtems/score/thread.h * + * @brief Constants and Structures Related with the Thread Control Block + * * This include file contains all constants and structures associated * with the thread control block. */ @@ -185,14 +187,14 @@ typedef enum { typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * ); /** - * @brief Per Task Variable Manager Structure Forward Reference + * @brief Forward reference to the per task variable structure.. * * Forward reference to the per task variable structure. */ struct rtems_task_variable_tt; /** - * @brief Per Task Variable Manager Structure + * @brief Internal structure used to manager per task variables. * * This is the internal structure used to manager per Task Variables. */ @@ -275,7 +277,7 @@ typedef union { } Thread_Wait_information_Object_argument_type; /** - * @brief Thread Blocking Management Information + * @brief Information required to manage a thread while it is blocked. * * This contains the information required to manage a thread while it is * blocked and to return information to it. @@ -503,14 +505,14 @@ SCORE_EXTERN Thread_Control *_Thread_Allocated_fp; */ SCORE_EXTERN struct _reent **_Thread_libc_reent; /** - * @brief Initialize Thread Handler + * @brief Initialize thread handler. * * This routine performs the initialization necessary for this handler. */ void _Thread_Handler_initialization(void); /** - * @brief Create Idle Thread + * @brief Create idle thread. * * This routine creates the idle thread. * @@ -519,7 +521,7 @@ void _Thread_Handler_initialization(void); void _Thread_Create_idle(void); /** - * @brief Start Thread Multitasking + * @brief Start thread multitasking. * * This routine initiates multitasking. It is invoked only as * part of initialization and its invocation is the last act of @@ -533,7 +535,7 @@ void _Thread_Create_idle(void); void _Thread_Start_multitasking( void ); /** - * @brief Dispatch Thread + * @brief Dispatch thread. * * This routine is responsible for transferring control of the * processor from the executing thread to the heir thread. Once the @@ -553,7 +555,7 @@ void _Thread_Start_multitasking( void ); void _Thread_Dispatch( void ); /** - * @brief Stack Allocate Helper + * @brief Allocate the requested stack space for the thread. * * Allocate the requested stack space for the thread. * Set the Start.stack field to the address of the stack. @@ -569,7 +571,7 @@ size_t _Thread_Stack_Allocate( ); /** - * @brief Deallocate Thread Stack + * @brief Deallocate thread stack. * * Deallocate the Thread's stack. */ @@ -578,7 +580,8 @@ void _Thread_Stack_Free( ); /** - * @brief Initialize Thread + * @brief Initialize thread. + * * This routine initializes the specified the thread. It allocates * all memory associated with this thread. It completes by adding * the thread to the local object table so operations on this @@ -604,14 +607,14 @@ bool _Thread_Initialize( ); /** - * @brief Initializes Thread and Executes it + * @brief Initializes thread and executes it. * * This routine initializes the executable information for a thread * and makes it ready to execute. After this routine executes, the * thread competes with all other threads for CPU time. * * @param the_thread is the thread to be initialized - * @param the_prototype + * @param the_prototype * @param entry_point * @param pointer_argument * @param numeric_argument @@ -625,7 +628,8 @@ bool _Thread_Start( ); /** - * @brief Restart Thread + * @brief Restarts the specified thread. + * * This support routine restarts the specified task in a way that the * next time this thread executes, it will begin execution at its * original starting point. @@ -639,7 +643,7 @@ bool _Thread_Restart( ); /** - * @brief Resets a thread to its initial state + * @brief Resets a thread to its initial state. * * This routine resets a thread to its initial state but does * not restart it. Some APIs do this in separate @@ -656,7 +660,7 @@ void _Thread_Reset( ); /** - * @brief Thread Close + * @brief Frees all memory associated with the specified thread. * * This routine frees all memory associated with the specified * thread and removes it from the local object table so no further @@ -668,7 +672,7 @@ void _Thread_Close( ); /** - * @brief Thread Ready + * @brief Removes any set states for @a the_thread. * * This routine removes any set states for @a the_thread. It performs * any necessary scheduling operations including the selection of @@ -683,7 +687,7 @@ void _Thread_Ready( ); /** - * @brief Clear Thread state + * @brief Clears the indicated STATES for @a the_thread. * * This routine clears the indicated STATES for @a the_thread. It performs * any necessary scheduling operations including the selection of @@ -699,13 +703,13 @@ void _Thread_Clear_state( ); /** - * @brief Sets States for a Thread + * @brief Sets the indicated @a state for @a the_thread. * * This routine sets the indicated @a state for @a the_thread. It performs * any necessary scheduling operations including the selection of * a new heir thread. * - * @param[in] the_thread is the thread to set the state for. + * @param[in] the_thread is the thread to set the state for. * @param[in] state is the state to set the_thread to. * * - INTERRUPT LATENCY: @@ -718,7 +722,7 @@ void _Thread_Set_state( ); /** - * @brief Sets the Transient state for a Thread + * @brief Sets the transient state for a thread. * * This routine sets the Transient state for @a the_thread. It performs * any necessary scheduling operations including the selection of @@ -734,11 +738,11 @@ void _Thread_Set_transient( ); /** - * @brief Initializes Enviroment for A Thread + * @brief Initializes enviroment for a thread. * * This routine initializes the context of @a the_thread to its * appropriate starting state. - * + * * @param[in] the_thread is the pointer to the thread control block. */ void _Thread_Load_environment( @@ -746,29 +750,24 @@ void _Thread_Load_environment( ); /** - * @brief Thread Handler + * @brief Wrapper function for all threads. + * * This routine is the wrapper function for all threads. It is * the starting point for all threads. The user provided thread * entry point is invoked by this routine. Operations * which must be performed immediately before and after the user's * thread executes are found here. * - * NOTE: - * - * On entry, it is assumed all interrupts are blocked and that this + * @note On entry, it is assumed all interrupts are blocked and that this * routine needs to set the initial isr level. This may or may not * actually be needed by the context switch routine and as a result * interrupts may already be at there proper level. Either way, * setting the initial isr level properly here is safe. - * - * Input parameters: NONE - * - * Output parameters: NONE */ void _Thread_Handler( void ); /** - * @brief Ended the delay of a Thread + * @brief Ended the delay of a thread. * * This routine is invoked when a thread must be unblocked at the * end of a time based delay (i.e. wake after or wake when). @@ -782,7 +781,7 @@ void _Thread_Delay_ended( ); /** - * @brief Changes the priority of a thread + * @brief Change the priority of a thread. * * This routine changes the current priority of @a the_thread to * @a new_priority. It performs any necessary scheduling operations @@ -799,7 +798,7 @@ void _Thread_Change_priority ( ); /** - * @brief Set Thread Priority + * @brief Set thread priority. * * This routine updates the priority related fields in the_thread * control block to indicate the current priority is now new_priority. @@ -840,7 +839,7 @@ void *_Thread_Idle_body( typedef void (*rtems_per_thread_routine)( Thread_Control * ); /** - * @brief Iterates Over All Threads + * @brief Iterates over all threads. * This routine iterates over all threads regardless of API and * invokes the specified routine. */ @@ -849,7 +848,7 @@ void rtems_iterate_over_all_threads( ); /** - * @brief Maps THread Id to a TCB Pointer + * @brief Maps thread Id to a TCB pointer. * * This function maps thread IDs to thread control * blocks. If ID corresponds to a local thread, then it @@ -875,7 +874,7 @@ Thread_Control *_Thread_Get ( ); /** - * @brief Cancel a blocking operation due to ISR + * @brief Cancel a blocking operation due to ISR. * * This method is used to cancel a blocking operation that was * satisfied from an ISR while the thread executing was in the @@ -900,14 +899,14 @@ void _Thread_blocking_operation_Cancel( #if defined(RTEMS_SMP) /** - * @brief _Thread_Dispatch_initialization + * @brief Initializes the thread dispatching subsystem. * * This routine initializes the thread dispatching subsystem. */ void _Thread_Dispatch_initialization(void); /** - * @brief _Thread_Dispatch_in_critical_section + * @brief Checks if thread dispatch says that we are in a critical section. * * This routine returns true if thread dispatch indicates * that we are in a critical section. @@ -915,14 +914,14 @@ void _Thread_blocking_operation_Cancel( bool _Thread_Dispatch_in_critical_section(void); /** - * @brief _Thread_Dispatch_get_disable_level + * @brief Returns value of the the thread dispatch level. * * This routine returns value of the the thread dispatch level. */ uint32_t _Thread_Dispatch_get_disable_level(void); /** - * @brief _Thread_Dispatch_set_disable_level + * @brief Sets thread dispatch level to the value passed in. * * This routine sets thread dispatch level to the * value passed in. @@ -930,14 +929,14 @@ void _Thread_blocking_operation_Cancel( uint32_t _Thread_Dispatch_set_disable_level(uint32_t value); /** - * @brief _Thread_Dispatch_increment_disable_level + * @brief Increments the thread dispatch level. * * This rountine increments the thread dispatch level */ uint32_t _Thread_Dispatch_increment_disable_level(void); /** - * @brief _Thread_Dispatch_decrement_disable_level + * @brief Decrements the thread dispatch level. * * This routine decrements the thread dispatch level. */ diff --git a/cpukit/score/include/rtems/score/threadmp.h b/cpukit/score/include/rtems/score/threadmp.h index eba713ca57..6c9788fe28 100644 --- a/cpukit/score/include/rtems/score/threadmp.h +++ b/cpukit/score/include/rtems/score/threadmp.h @@ -1,6 +1,8 @@ /** * @file rtems/score/threadmp.h * + * @brief Multiprocessing Portion of the Thread Package + * * This include file contains the specification for all routines * and data specific to the multiprocessing portion of the thread package. */ @@ -20,6 +22,8 @@ /** * @defgroup ScoreThreadMP Thread Handler Multiprocessing Support * + * @ingroup Score + * * This handler encapsulates functionality which is related to managing * threads in a multiprocessor system configuration. This handler must * manage proxies which represent remote threads blocking on local @@ -32,7 +36,7 @@ extern "C" { #endif /** - * @brief MP Thread Handler Initialization + * @brief Initialize MP thread handler. * * This routine initializes the multiprocessing portion of the Thread Handler. */ @@ -41,7 +45,8 @@ void _Thread_MP_Handler_initialization ( ); /** - * @brief MP Thread Proxy Allocate + * @brief Allocate a MP proxy control block from + * the inactive chain of free proxy control blocks. * * This allocates a proxy control block from * the inactive chain of free proxy control blocks. @@ -54,7 +59,8 @@ Thread_Control *_Thread_MP_Allocate_proxy ( ); /** - * @brief MP Thread Proxy Find + * @brief Removes the MP proxy control block for the specified + * id from the active chain of proxy control blocks. * * This function removes the proxy control block for the specified * id from the active chain of proxy control blocks. @@ -64,14 +70,14 @@ Thread_Control *_Thread_MP_Find_proxy ( ); /** - * @brief Active Proxy Set + * @brief Manage the active set MP proxies. * * The following chain is used to manage the active set proxies. */ SCORE_EXTERN Chain_Control _Thread_MP_Active_proxies; /** - * @brief Inactive Proxy Set + * @brief Manage the inactive set of MP proxies. * * The following chain is used to manage the inactive set of proxies. */ diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h index a2653b3a02..1be336993c 100644 --- a/cpukit/score/include/rtems/score/threadq.h +++ b/cpukit/score/include/rtems/score/threadq.h @@ -1,6 +1,8 @@ /** * @file rtems/score/threadq.h * + * Constants and Structures Associated with the Manipulation of Objects + * * This include file contains all the constants and structures associated * with the manipulation of objects. */ @@ -60,7 +62,7 @@ typedef void ( *Thread_queue_Timeout_callout )( ); /** - * @brief Thread Queue Dequeue + * @brief Gets a pointer to a thread waiting on the_thread_queue. * * This function returns a pointer to a thread waiting on * the_thread_queue. The selection of this thread is based on @@ -72,7 +74,7 @@ Thread_Control *_Thread_queue_Dequeue( ); /** - * @brief Thread Queue Enqueue Wrapper + * @brief Enqueues the currently executing thread on the_thread_queue. * * This routine enqueues the currently executing thread on * the_thread_queue with an optional timeout. @@ -84,7 +86,7 @@ Thread_Control *_Thread_queue_Dequeue( _Thread_queue_Timeout ) /** - * @brief Thread Queue Enqueue + * @brief Blocks a thread and places it on a thread. * * This routine blocks a thread, places it on a thread, and optionally * starts a timeout timer. @@ -102,7 +104,7 @@ void _Thread_queue_Enqueue_with_handler( ); /** - * @brief Thread Queue Requeue + * @brief Invoked when a thread changes priority and is blocked. * * This routine is invoked when a thread changes priority and is * blocked on a thread queue. If the queue is priority ordered, @@ -119,7 +121,7 @@ void _Thread_queue_Requeue( ); /** - * @brief Extracts Thread from Thread Queue + * @brief Extracts thread from thread queue. * * This routine removes @a the_thread from @a the_thread_queue * and cancels any timeouts associated with this blocking. @@ -133,7 +135,7 @@ void _Thread_queue_Extract( ); /** - * @brief Thread Queue Extract with proxy + * @brief Extracts the_thread from the_thread_queue. * * This routine extracts the_thread from the_thread_queue * and ensures that if there is a proxy for this task on @@ -144,7 +146,7 @@ bool _Thread_queue_Extract_with_proxy( ); /** - * @brief Thread Queue First + * @brief Gets a pointer to the "first" thread on the_thread_queue. * * This function returns a pointer to the "first" thread * on the_thread_queue. The "first" thread is selected @@ -152,17 +154,23 @@ bool _Thread_queue_Extract_with_proxy( * * @param[in] the_thread_queue pointer to thread queue * - * @return first thread or NULL + * @retval first thread or NULL */ Thread_Control *_Thread_queue_First( Thread_queue_Control *the_thread_queue ); /** - * @brief Thread Queue Flush + * @brief Unblocks all threads blocked on the_thread_queue. * * This routine unblocks all threads blocked on the_thread_queue * and cancels any associated timeouts. + * + * @param[in] the_thread_queue is the pointer to a threadq header + * @param[in] remote_extract_callout points to a method to invoke to + * invoke when a remote thread is unblocked + * @param[in] status is the status which will be returned to + * all unblocked threads */ void _Thread_queue_Flush( Thread_queue_Control *the_thread_queue, @@ -171,14 +179,14 @@ void _Thread_queue_Flush( ); /** - * @brief Thread Queue Initialize + * @brief Initialize the_thread_queue. * * This routine initializes the_thread_queue based on the * discipline indicated in attribute_set. The state set on * threads which block on the_thread_queue is state. * * @param[in] the_thread_queue is the pointer to a threadq header - * @param[in] discipline is the queueing discipline + * @param[in] the_discipline is the queueing discipline * @param[in] state is the state of waiting threads * @param[in] timeout_status is the return on a timeout */ @@ -190,7 +198,8 @@ void _Thread_queue_Initialize( ); /** - * @brief Thread Queue Dequeue priority + * @brief Removes a thread from the specified PRIORITY based + * threadq, unblocks it, and cancels its timeout timer. * * This routine removes a thread from the specified PRIORITY based * threadq, unblocks it, and cancels its timeout timer. @@ -208,14 +217,18 @@ Thread_Control *_Thread_queue_Dequeue_priority( ); /** - * @brief Thread Queue Enqueue Priority + * @brief Enqueues the currently executing thread on the_thread_queue. * * This routine enqueues the currently executing thread on * the_thread_queue with an optional timeout using the * priority discipline. * * @param[in] the_thread_queue is the pointer to threadq - * @param[in] thread is the thread to insert + * @param[in] the_thread is the thread to insert + * @param[in] level_p is a pointer to an interrupt level to be returned + * + * @retval This methods returns an indication of the blocking state as + * well as filling in *@ level_p with the previous interrupt level. * * - INTERRUPT LATENCY: * + forward less than @@ -228,7 +241,7 @@ Thread_blocking_operation_States _Thread_queue_Enqueue_priority ( ); /** - * @brief Thread Queue Extract priority Helper + * @brief Removes the_thread and cancels related timeouts. * * This routine removes the_thread from the_thread_queue * and cancels any timeouts associated with this blocking. @@ -246,7 +259,7 @@ void _Thread_queue_Extract_priority_helper( ); /** - * @brief Thread Queue Extract priority + * @brief Wraps the underlying call and hides the requeuing argument. * * This macro wraps the underlying call and hides the requeuing argument. */ @@ -254,21 +267,21 @@ void _Thread_queue_Extract_priority_helper( #define _Thread_queue_Extract_priority( _the_thread_queue, _the_thread ) \ _Thread_queue_Extract_priority_helper( _the_thread_queue, _the_thread, false ) /** - * @brief Returns highest priority thread on the_thread_queue + * @brief Get highest priority thread on the_thread_queue. * * This function returns a pointer to the "first" thread * on @a the_thread_queue. The "first" thread is the highest * priority thread waiting on @a the_thread_queue. * * @param[in] the_thread_queue is the pointer to the thread queue - * @return first thread or NULL + * @retval first thread or NULL */ Thread_Control *_Thread_queue_First_priority( Thread_queue_Control *the_thread_queue ); /** - * @brief Thread Queue Dequeue FIFO + * @brief Gets a pointer to the thread which has been waiting the longest. * * This function returns a pointer to the thread which has * been waiting the longest on the_thread_queue. If no @@ -276,7 +289,7 @@ Thread_Control *_Thread_queue_First_priority( * * @param[in] the_thread_queue is the pointer to threadq * - * @return thread dequeued or NULL + * @retval thread dequeued or NULL * * - INTERRUPT LATENCY: * + check sync @@ -287,7 +300,7 @@ Thread_Control *_Thread_queue_Dequeue_fifo( ); /** - * @brief Thread Queue Enqueue FIFO + * @brief Enqueues the currently executing thread on the_thread_queue. * * This routine enqueues the currently executing thread on * the_thread_queue with an optional timeout using the @@ -307,7 +320,7 @@ Thread_blocking_operation_States _Thread_queue_Enqueue_fifo ( ); /** - * @brief Thread Queue Extract FIFO + * @brief Removes the_thread from the_thread_queue and cancels any timeouts. * * This routine removes the_thread from the_thread_queue * and cancels any timeouts associated with this blocking. @@ -318,7 +331,7 @@ void _Thread_queue_Extract_fifo( ); /** - * @brief Thread Queue First FIFO + * @brief Gets a pointer to the "first" thread on the_thread_queue. * * This function returns a pointer to the "first" thread * on the_thread_queue. The first thread is the thread @@ -326,14 +339,14 @@ void _Thread_queue_Extract_fifo( * * @param[in] the_thread_queue is the pointer to threadq * - * @return first thread or NULL + * @retval first thread or NULL */ Thread_Control *_Thread_queue_First_fifo( Thread_queue_Control *the_thread_queue ); /** - * @brief Thread Queue Timeout + * @brief Thread queue timeout. * * This routine is invoked when a task's request has not * been satisfied after the timeout interval specified to @@ -349,7 +362,7 @@ void _Thread_queue_Timeout ( ); /** - * @brief Process Thread Queue Timeout + * @brief Process thread queue timeout. * * This is a shared helper routine which makes it easier to have multiple * object class specific timeout routines. diff --git a/cpukit/score/include/rtems/score/threadsync.h b/cpukit/score/include/rtems/score/threadsync.h index df8ce5f800..a740302f7e 100644 --- a/cpukit/score/include/rtems/score/threadsync.h +++ b/cpukit/score/include/rtems/score/threadsync.h @@ -1,5 +1,7 @@ /** - * @file rtems/score/threadsync.h + * @file rtems/score/threadsync.h + * + * @brief Synchronize Thread Blocking Operations with Actions in an ISR * * This include file contains all constants and structures associated * with synchronizing a thread blocking operation with potential diff --git a/cpukit/score/include/rtems/score/timespec.h b/cpukit/score/include/rtems/score/timespec.h index 41bb8bb3ef..e72ccb2b72 100644 --- a/cpukit/score/include/rtems/score/timespec.h +++ b/cpukit/score/include/rtems/score/timespec.h @@ -35,7 +35,7 @@ extern "C" { #endif /** - * @brief Set Timespec to Seconds Nanosecond + * @brief Set timespec to seconds nanosecond. * * This method sets the timespec to the specified seconds and nanoseconds * value. @@ -51,7 +51,7 @@ extern "C" { } while (0) /** - * @brief Zero Timespec + * @brief Sets the Timespec to Zero * * This method sets the timespec to zero. * value. @@ -65,37 +65,37 @@ extern "C" { } while (0) /** - * @brief Get Seconds Portion of Timespec + * @brief Get seconds portion of timespec. * * This method returns the seconds portion of the specified timespec * * @param[in] _time points to the timespec * - * @return The seconds portion of @a _time. + * @retval The seconds portion of @a _time. */ #define _Timespec_Get_seconds( _time ) \ ((_time)->tv_sec) /** - * @brief Get Nanoseconds Portion of Timespec + * @brief Get nanoseconds portion of timespec. * * This method returns the nanoseconds portion of the specified timespec * * @param[in] _time points to the timespec * - * @return The nanoseconds portion of @a _time. + * @retval The nanoseconds portion of @a _time. */ #define _Timespec_Get_nanoseconds( _time ) \ ((_time)->tv_nsec) /** - * @brief Is Timespec Valid + * @brief Check if timespec is valid. * * This method determines the validity of a timespec. * * @param[in] time is the timespec instance to validate. * - * @return This method returns true if @a time is valid and + * @retval This method returns true if @a time is valid and * false otherwise. */ bool _Timespec_Is_valid( @@ -103,14 +103,14 @@ bool _Timespec_Is_valid( ); /** - * @brief Timespec Less Than Operator + * @brief The Timespec "less than" operator. * * This method is the less than operator for timespecs. * * @param[in] lhs is the left hand side timespec * @param[in] rhs is the right hand side timespec * - * @return This method returns true if @a lhs is less than the @a rhs and + * @retval This method returns true if @a lhs is less than the @a rhs and * false otherwise. */ bool _Timespec_Less_than( @@ -119,28 +119,28 @@ bool _Timespec_Less_than( ); /** - * @brief Timespec Greater Than Operator + * @brief The Timespec "greater than" operator. * * This method is the greater than operator for timespecs. * - * @param[in] lhs is the left hand side timespec - * @param[in] rhs is the right hand side timespec + * @param[in] _lhs is the left hand side timespec + * @param[in] _rhs is the right hand side timespec * - * @return This method returns true if @a lhs is greater than the @a rhs and + * @retval This method returns true if @a lhs is greater than the @a rhs and * false otherwise. */ #define _Timespec_Greater_than( _lhs, _rhs ) \ _Timespec_Less_than( _rhs, _lhs ) /** - * @brief Timespec equal to Operator + * @brief The Timespec "equal to" operator. * * This method is the is equal to than operator for timespecs. * * @param[in] lhs is the left hand side timespec * @param[in] rhs is the right hand side timespec * - * @return This method returns true if @a lhs is equal to @a rhs and + * @retval This method returns true if @a lhs is equal to @a rhs and * false otherwise. */ #define _Timespec_Equal_to( lhs, rhs ) \ @@ -149,7 +149,7 @@ bool _Timespec_Less_than( ) /** - * @brief Add to a Timespec + * @brief Add two timespecs. * * This routine adds two timespecs. The second argument is added * to the first. @@ -157,7 +157,7 @@ bool _Timespec_Less_than( * @param[in] time is the base time to be added to * @param[in] add is the timespec to add to the first argument * - * @return This method returns the number of seconds @a time increased by. + * @retval This method returns the number of seconds @a time increased by. */ uint32_t _Timespec_Add_to( struct timespec *time, @@ -165,21 +165,21 @@ uint32_t _Timespec_Add_to( ); /** - * @brief Convert Timespec to Number of Ticks + * @brief Convert timespec to number of ticks. * * This routine convert the @a time timespec to the corresponding number * of clock ticks. * * @param[in] time is the time to be converted * - * @return This method returns the number of ticks computed. + * @retval This method returns the number of ticks computed. */ uint32_t _Timespec_To_ticks( const struct timespec *time ); /** - * @brief Convert Ticks to Timespec + * @brief Convert ticks to timespec. * * This routine converts the @a ticks value to the corresponding * timespec format @a time. @@ -193,7 +193,7 @@ void _Timespec_From_ticks( ); /** - * @brief Subtract Two Timespec + * @brief Subtract two timespec. * * This routine subtracts two timespecs. @a result is set to * @a end - @a start. @@ -202,7 +202,7 @@ void _Timespec_From_ticks( * @param[in] end is the ending time * @param[in] result is the difference between starting and ending time. * - * @return This method fills in @a result. + * @retval This method fills in @a result. */ void _Timespec_Subtract( const struct timespec *start, @@ -211,7 +211,7 @@ void _Timespec_Subtract( ); /** - * @brief Divide Timespec By Integer + * @brief Divide timespec by an integer. * * This routine divides a timespec by an integer value. The expected * use is to assist in benchmark calculations where you typically @@ -221,7 +221,7 @@ void _Timespec_Subtract( * @param[in] iterations is the number of iterations * @param[in] result is the average time. * - * @return This method fills in @a result. + * @retval This method fills in @a result. */ void _Timespec_Divide_by_integer( const struct timespec *time, @@ -230,7 +230,7 @@ void _Timespec_Divide_by_integer( ); /** - * @brief Divide Timespec + * @brief Divide a timespec by anonther timespec. * * This routine divides a timespec by another timespec. The * intended use is for calculating percentages to three decimal points. @@ -240,7 +240,7 @@ void _Timespec_Divide_by_integer( * @param[in] ival_percentage is the integer portion of the average * @param[in] fval_percentage is the thousandths of percentage * - * @return This method fills in @a result. + * @retval This method fills in @a result. */ void _Timespec_Divide( const struct timespec *lhs, diff --git a/cpukit/score/include/rtems/score/timestamp.h b/cpukit/score/include/rtems/score/timestamp.h index 951c37413d..638ae7bf52 100644 --- a/cpukit/score/include/rtems/score/timestamp.h +++ b/cpukit/score/include/rtems/score/timestamp.h @@ -1,6 +1,8 @@ /** * @file rtems/score/timestamp.h * + * @brief Helpers for Manipulating Timestamps + * * This include file contains helpers for manipulating timestamps. */ @@ -17,7 +19,7 @@ #define _RTEMS_SCORE_TIMESTAMP_H /** - * @defgroup SuperCore Timestamp + * @defgroup SuperCoreTimeStamp Score Timestamp * * @ingroup Score * @@ -73,7 +75,7 @@ extern "C" { #endif /** - * @brief Set Timestamp to Specified Seconds and Nanoseconds + * @brief Set timestamp to specified seconds and nanoseconds. * * This method sets the timestamp to the specified @a _seconds and @a _nanoseconds * value. @@ -91,7 +93,7 @@ extern "C" { #endif /** - * @brief Zero Timestamp + * @brief Sets the timestamp to zero. * * This method sets the timestamp to zero. * value. @@ -107,13 +109,13 @@ extern "C" { #endif /** - * @brief Is Timestamp Valid + * @brief Determines the validity of a timestamp. * * This method determines the validity of a timestamp. * * @param[in] _time points to the timestamp instance to validate. * - * @return This method returns true if @a time is valid and + * @retval This method returns true if @a time is valid and * false otherwise. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE @@ -125,14 +127,14 @@ extern "C" { #endif /** - * @brief Timestamp Less Than Operator + * @brief Less than operator for timestamps. * * This method is the less than operator for timestamps. * * @param[in] _lhs points to the left hand side timestamp * @param[in] _rhs points to the right hand side timestamp * - * @return This method returns true if @a _lhs is less than the @a _rhs and + * @retval This method returns true if @a _lhs is less than the @a _rhs and * false otherwise. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE @@ -144,28 +146,28 @@ extern "C" { #endif /** - * @brief Timestamp Greater Than Operator + * @brief Greater than operator for timestamps. * * This method is the greater than operator for timestamps. * * @param[in] _lhs points to the left hand side timestamp * @param[in] _rhs points to the right hand side timestamp * - * @return This method returns true if @a _lhs is greater than the @a _rhs and + * @retval This method returns true if @a _lhs is greater than the @a _rhs and * false otherwise. */ #define _Timestamp_Greater_than( _lhs, _rhs ) \ _Timestamp_Less_than( _rhs, _lhs ) /** - * @brief Timestamp equal to Operator + * @brief Equal to than operator for timestamps. * * This method is the is equal to than operator for timestamps. * * @param[in] _lhs points to the left hand side timestamp * @param[in] _rhs points to the right hand side timestamp * - * @return This method returns true if @a _lhs is equal to @a _rhs and + * @retval This method returns true if @a _lhs is equal to @a _rhs and * false otherwise. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE @@ -177,7 +179,7 @@ extern "C" { #endif /** - * @brief Add to a Timestamp + * @brief Adds two timestamps. * * This routine adds two timestamps. The second argument is added * to the first. @@ -185,7 +187,7 @@ extern "C" { * @param[in] _time points to the base time to be added to * @param[in] _add points to the timestamp to add to the first argument * - * @return This method returns the number of seconds @a time increased by. + * @retval This method returns the number of seconds @a time increased by. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE #define _Timestamp_Add_to( _time, _add ) \ @@ -196,14 +198,14 @@ extern "C" { #endif /** - * @brief Convert Timestamp to Number of Ticks + * @brief Convert timestamp to number of clock ticks. * * This routine convert the @a time timestamp to the corresponding number * of clock ticks. * * @param[in] _time points to the time to be converted * - * @return This method returns the number of ticks computed. + * @retval This method returns the number of ticks computed. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE #define _Timestamp_To_ticks( _time ) \ @@ -214,7 +216,7 @@ extern "C" { #endif /** - * @brief Convert Ticks to Timestamp + * @brief Converts the @a _ticks value to timestamp format. * * This routine converts the @a _ticks value to the corresponding * timestamp format @a _time. @@ -231,7 +233,7 @@ extern "C" { #endif /** - * @brief Subtract Two Timestamp + * @brief Subtracts two timestamps. * * This routine subtracts two timestamps. @a result is set to * @a end - @a start. @@ -241,7 +243,7 @@ extern "C" { * @param[in] _result points to the difference between * starting and ending time. * - * @return This method fills in @a _result. + * @retval This method fills in @a _result. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE #define _Timestamp_Subtract( _start, _end, _result ) \ @@ -252,7 +254,7 @@ extern "C" { #endif /** - * @brief Divide Timestamp By Integer + * @brief Divides a timestamp by an integer value. * * This routine divides a timestamp by an integer value. The expected * use is to assist in benchmark calculations where you typically @@ -262,7 +264,7 @@ extern "C" { * @param[in] _iterations is the number of iterations * @param[in] _result points to the average time. * - * @return This method fills in @a result. + * @retval This method fills in @a result. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE #define _Timestamp_Divide_by_integer( _time, _iterations, _result ) \ @@ -273,7 +275,7 @@ extern "C" { #endif /** - * @brief Divide Timestamp + * @brief Divides a timestamp by another timestamp. * * This routine divides a timestamp by another timestamp. The * intended use is for calculating percentages to three decimal points. @@ -283,7 +285,7 @@ extern "C" { * @param[in] _ival_percentage points to the integer portion of the average * @param[in] _fval_percentage points to the thousandths of percentage * - * @return This method fills in @a result. + * @retval This method fills in @a result. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE #define _Timestamp_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage ) \ @@ -294,13 +296,13 @@ extern "C" { #endif /** - * @brief Get Seconds Portion of Timestamp + * @brief Get seconds portion of timestamp. * * This method returns the seconds portion of the specified timestamp * * @param[in] _time points to the timestamp * - * @return The seconds portion of @a _time. + * @retval The seconds portion of @a _time. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE #define _Timestamp_Get_seconds( _time ) \ @@ -311,13 +313,13 @@ extern "C" { #endif /** - * @brief Get Nanoseconds Portion of Timestamp + * @brief Get nanoseconds portion of timestamp. * * This method returns the nanoseconds portion of the specified timestamp * * @param[in] _time points to the timestamp * - * @return The nanoseconds portion of @a _time. + * @retval The nanoseconds portion of @a _time. */ #if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE #define _Timestamp_Get_nanoseconds( _time ) \ @@ -328,7 +330,7 @@ extern "C" { #endif /** - * @brief Convert Timestamp to Struct Timespec + * @brief Convert timestamp to struct timespec. * * This method returns the seconds portion of the specified @a _timestamp. * @@ -345,7 +347,7 @@ extern "C" { #endif /** - * @brief Convert Timestamp to struct timeval + * @brief Convert timestamp to struct timeval. * * @param[in] _timestamp points to the timestamp * @param[in] _timeval points to the timeval diff --git a/cpukit/score/include/rtems/score/timestamp64.h b/cpukit/score/include/rtems/score/timestamp64.h index 41735fa144..306ee35fee 100644 --- a/cpukit/score/include/rtems/score/timestamp64.h +++ b/cpukit/score/include/rtems/score/timestamp64.h @@ -1,6 +1,8 @@ /** * @file rtems/score/timestamp64.h * + * @brief Helpers for Manipulating 64-bit Integer Timestamps + * * This include file contains helpers for manipulating * 64-bit integer timestamps. */ @@ -18,7 +20,7 @@ #define _RTEMS_SCORE_TIMESTAMP64_H /** - * @defgroup SuperCore Timestamp64 + * @defgroup SuperCoreTimestamp64 SuperCore Sixty-Four Bit Timestamps * * @ingroup Score * @@ -61,7 +63,7 @@ static inline void _Timestamp64_implementation_Set( } /** - * @brief Set Timestamp to Seconds Nanosecond + * @brief Set 64-bit timestamp to seconds nanosecond. * * This method sets the timestamp to the specified seconds and nanoseconds * value. @@ -89,10 +91,9 @@ static inline void _Timestamp64_implementation_Set_to_zero( } /** - * @brief Zero Timestamp + * @brief Sets the 64-bit timestamp to zero. * - * This method sets the timestamp to zero. - * value. + * This method sets the timestamp to zero value. * * @param[in] _time points to the timestamp instance to zero. */ @@ -106,13 +107,13 @@ static inline void _Timestamp64_implementation_Set_to_zero( #endif /** - * @brief Is Timestamp Valid + * @brief Determines the validity of a 64-bit timestamp. * * This method determines the validity of a timestamp. * * @param[in] _time points to the timestamp instance to validate. * - * @return This method returns true if @a time is valid and + * @retval This method returns true if @a time is valid and * false otherwise. */ #define _Timestamp64_Is_valid( _time ) \ @@ -127,14 +128,14 @@ static inline bool _Timestamp64_implementation_Less_than( } /** - * @brief Timestamp Less Than Operator + * @brief The "less than" operator for 64-bit timestamps. * * This method is the less than operator for timestamps. * * @param[in] _lhs points to the left hand side timestamp * @param[in] _rhs points to the right hand side timestamp * - * @return This method returns true if @a _lhs is less than the @a _rhs and + * @retval This method returns true if @a _lhs is less than the @a _rhs and * false otherwise. */ #if CPU_TIMESTAMP_USE_INT64_INLINE == TRUE @@ -159,14 +160,14 @@ static inline bool _Timestamp64_implementation_Equal_to( _Timestamp64_Less_than( _rhs, _lhs ) /** - * @brief Timestamp equal to Operator + * @brief The "equal to" operator for 64-bit timestamps. * * This method is the is equal to than operator for timestamps. * * @param[in] _lhs points to the left hand side timestamp * @param[in] _rhs points to the right hand side timestamp * - * @return This method returns true if @a _lhs is equal to @a _rhs and + * @retval This method returns true if @a _lhs is equal to @a _rhs and * false otherwise. */ #if CPU_TIMESTAMP_USE_INT64_INLINE == TRUE @@ -188,7 +189,7 @@ static inline void _Timestamp64_implementation_Add_to( } /** - * @brief Add to a Timestamp + * @brief Add two 64-bit timestamps. * * This routine adds two timestamps. The second argument is added * to the first. @@ -196,7 +197,7 @@ static inline void _Timestamp64_implementation_Add_to( * @param[in] _time points to the base time to be added to * @param[in] _add points to the timestamp to add to the first argument * - * @return This method returns the number of seconds @a time increased by. + * @retval This method returns the number of seconds @a time increased by. */ #if CPU_TIMESTAMP_USE_INT64_INLINE == TRUE #define _Timestamp64_Add_to( _time, _add ) \ @@ -209,21 +210,21 @@ static inline void _Timestamp64_implementation_Add_to( #endif /** - * @brief Convert Timestamp to Number of Ticks + * @brief Convert 64-bit timestamp to number of ticks. * * This routine convert the @a time timestamp to the corresponding number * of clock ticks. * * @param[in] _time points to the time to be converted * - * @return This method returns the number of ticks computed. + * @retval This method returns the number of ticks computed. */ uint32_t _Timestamp64_To_ticks( const Timestamp64_Control *_time ); /** - * @brief Convert Ticks to Timestamp + * @brief Convert ticks to 64-bit timestamp. * * This routine converts the @a _ticks value to the corresponding * timestamp format @a _time. @@ -246,7 +247,7 @@ static inline void _Timestamp64_implementation_Subtract( } /** - * @brief Subtract Two Timestamp + * @brief Subtract two 64-bit timestamps. * * This routine subtracts two timestamps. @a result is set to * @a end - @a start. @@ -277,7 +278,7 @@ static inline void _Timestamp64_implementation_Divide_by_integer( } /** - * @brief Divide Timestamp By Integer + * @brief Divide 64-bit timestamp by an integer. * * This routine divides a timestamp by an integer value. The expected * use is to assist in benchmark calculations where you typically @@ -299,7 +300,7 @@ static inline void _Timestamp64_implementation_Divide_by_integer( #endif /** - * @brief Divide Timestamp + * @brief Divide 64-bit timestamp by another 64-bit timestamp. * * This routine divides a timestamp by another timestamp. The * intended use is for calculating percentages to three decimal points. @@ -324,13 +325,13 @@ static inline uint32_t _Timestamp64_implementation_Get_seconds( } /** - * @brief Get Seconds Portion of Timestamp + * @brief Get seconds portion of a 64-bit timestamp. * * This method returns the seconds portion of the specified timestamp * * @param[in] _time points to the timestamp * - * @return The seconds portion of @a _time. + * @retval The seconds portion of @a _time. */ #if CPU_TIMESTAMP_USE_INT64_INLINE == TRUE #define _Timestamp64_Get_seconds( _time ) \ @@ -349,13 +350,13 @@ static inline uint32_t _Timestamp64_implementation_Get_nanoseconds( } /** - * @brief Get Nanoseconds Portion of Timestamp + * @brief Get nanoseconds portion of a 64-bit timestamp. * * This method returns the nanoseconds portion of the specified timestamp * * @param[in] _time points to the timestamp * - * @return The nanoseconds portion of @a _time. + * @retval The nanoseconds portion of @a _time. */ #if CPU_TIMESTAMP_USE_INT64_INLINE == TRUE #define _Timestamp64_Get_nanoseconds( _time ) \ @@ -376,7 +377,7 @@ static inline void _Timestamp64_implementation_To_timespec( } /** - * @brief Convert Timestamp to struct timespec + * @brief Convert 64-bit timestamp to struct timespec. * * This method returns the seconds portion of the specified timestamp * @@ -403,7 +404,7 @@ static inline void _Timestamp64_implementation_To_timeval( } /** - * @brief Convert Timestamp to struct timeval + * @brief Convert 64-bit timestamp to struct timeval. * * This method returns the seconds portion of the specified timestamp * diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h index eb743b737a..df73f95970 100644 --- a/cpukit/score/include/rtems/score/tod.h +++ b/cpukit/score/include/rtems/score/tod.h @@ -1,6 +1,8 @@ /** * @file rtems/score/tod.h * + * @brief Constants and Structures Associated with the Time of Day Handler. + * * This include file contains all the constants and structures associated * with the Time of Day Handler. */ @@ -105,7 +107,7 @@ extern "C" { (4 * TOD_SECONDS_PER_DAY)) /** - * @brief RTEMS Epoch Year + * @brief Earliest year to which an time of day can be initialized. * * The following constant define the earliest year to which an * time of day can be initialized. This is considered the @@ -157,7 +159,7 @@ typedef struct { SCORE_EXTERN TOD_Control _TOD; /** - * @brief Seconds Since RTEMS Epoch + * @brief Number of seconds Since RTEMS epoch. * * The following contains the number of seconds from 00:00:00 * January 1, TOD_BASE_YEAR until the current time of day. @@ -166,14 +168,14 @@ SCORE_EXTERN TOD_Control _TOD; _Timestamp_Get_seconds(&_TOD.now) /** - * @brief Initializes the Time of Day Handler + * @brief Initializes the time of day handler. * * Performs the initialization necessary for the Time Of Day handler. */ void _TOD_Handler_initialization(void); /** - * @brief Sets the time of day from timestamp + * @brief Sets the time of day from timestamp. * * The @a tod_as_timestamp timestamp represents the time since UNIX epoch. * The watchdog seconds chain will be adjusted. @@ -203,10 +205,11 @@ static inline void _TOD_Set( * * This function invokes the nanoseconds extension. * - * @param[out] snapshot The snapshot. - * @param[in] source The clock. + * @param[out] snapshot points to an area that will contain the current + * TOD plus the BSP nanoseconds since last tick adjustment + * @param[in] clock contains the current TOD * - * @return The snapshot. + * @retval @a snapshot */ Timestamp_Control *_TOD_Get_with_nanoseconds( Timestamp_Control *snapshot, @@ -226,7 +229,7 @@ static inline void _TOD_Get( } /** - * @brief _TOD_Get_uptime + * @brief Gets the system uptime with potential accuracy to the nanosecond. * * This routine returns the system uptime with potential accuracy * to the nanosecond. @@ -241,7 +244,7 @@ static inline void _TOD_Get_uptime( } /** - * @brief _TOD_Get_uptime_as_timespec + * @brief Gets the system uptime with potential accuracy to the nanosecond. * * This routine returns the system uptime with potential accuracy * to the nanosecond. @@ -253,7 +256,7 @@ void _TOD_Get_uptime_as_timespec( ); /** - * @brief Increments time of day at each clock tick + * @brief Increments time of day at each clock tick. * * This routine increments the ticks field of the current time of * day at each clock tick. @@ -261,7 +264,7 @@ void _TOD_Get_uptime_as_timespec( void _TOD_Tickle_ticks( void ); /** - * @brief TOD_MILLISECONDS_TO_MICROSECONDS + * @brief Converts an interval expressed in milliseconds to microseconds. * * This routine converts an interval expressed in milliseconds to microseconds. * @@ -270,7 +273,7 @@ void _TOD_Tickle_ticks( void ); #define TOD_MILLISECONDS_TO_MICROSECONDS(_ms) ((uint32_t)(_ms) * 1000L) /** - * @brief Converts microseconds to ticks + * @brief Converts an interval expressed in microseconds to ticks. * * This routine converts an interval expressed in microseconds to ticks. * @@ -281,7 +284,7 @@ uint32_t TOD_MICROSECONDS_TO_TICKS( ); /** - * @brief TOD_MILLISECONDS_TO_TICKS + * @brief Converts an interval expressed in milliseconds to ticks. * * This routine converts an interval expressed in milliseconds to ticks. * @@ -292,7 +295,7 @@ uint32_t TOD_MILLISECONDS_TO_TICKS( ); /** - * @brief How many ticks in a second? + * @brief Gets number of ticks in a second. * * This method returns the number of ticks in a second. * @@ -302,7 +305,7 @@ uint32_t TOD_MILLISECONDS_TO_TICKS( uint32_t TOD_TICKS_PER_SECOND_method(void); /** - * @brief Method to return number of ticks in a second + * @brief Gets number of ticks in a second. * * This method exists to hide the fact that TOD_TICKS_PER_SECOND can not * be implemented as a macro in a .h file due to visibility issues. diff --git a/cpukit/score/include/rtems/score/tqdata.h b/cpukit/score/include/rtems/score/tqdata.h index 1c2e1326f5..c556d3ffe8 100644 --- a/cpukit/score/include/rtems/score/tqdata.h +++ b/cpukit/score/include/rtems/score/tqdata.h @@ -1,6 +1,8 @@ /** * @file rtems/score/tqdata.h * + * @brief Constants and Structures Needed to Declare a Thread Queue + * * This include file contains all the constants and structures * needed to declare a thread queue. */ diff --git a/cpukit/score/include/rtems/score/userext.h b/cpukit/score/include/rtems/score/userext.h index 6071d7ab3b..bf76c35e39 100644 --- a/cpukit/score/include/rtems/score/userext.h +++ b/cpukit/score/include/rtems/score/userext.h @@ -3,7 +3,7 @@ * * @ingroup ScoreUserExt * - * @brief User Extension Handler API. + * @brief User Extension Handler API */ /* @@ -36,9 +36,8 @@ typedef void User_extensions_routine RTEMS_COMPILER_DEPRECATED_ATTRIBUTE; * @brief The User Extension Handler provides invocation of application * dependent routines at critical points in the life of each thread and the * system as a whole. - * - * @{ */ +/**@{**/ /** * @brief Task create extension. diff --git a/cpukit/score/include/rtems/score/userextimpl.h b/cpukit/score/include/rtems/score/userextimpl.h index 7a89d9af0c..6ecdcc579a 100644 --- a/cpukit/score/include/rtems/score/userextimpl.h +++ b/cpukit/score/include/rtems/score/userextimpl.h @@ -3,7 +3,7 @@ * * @ingroup ScoreUserExt * - * @brief User Extension Handler API. + * @brief User Extension Handler API */ /* @@ -25,10 +25,13 @@ extern "C" { #endif /** - * @addtogroup ScoreUserExt + * @defgroup ScoreUserExt User Extension Handler + * + * @ingroup Score * - * @{ + * @addtogroup ScoreUserExt */ +/**@{**/ /** * @brief List of active extensions. @@ -42,9 +45,8 @@ extern Chain_Control _User_extensions_Switches_list; /** * @name Extension Maintainance - * - * @{ */ +/**@{**/ void _User_extensions_Handler_initialization( void ); @@ -154,9 +156,8 @@ void _User_extensions_Iterate( /** * @name Extension Callout Dispatcher - * - * @{ */ +/**@{**/ static inline bool _User_extensions_Thread_create( Thread_Control *created ) { diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h index 1471f84b28..6dd0b5d0ce 100644 --- a/cpukit/score/include/rtems/score/watchdog.h +++ b/cpukit/score/include/rtems/score/watchdog.h @@ -1,6 +1,8 @@ /** * @file rtems/score/watchdog.h * + * @brief Constants and Structures Associated with Watchdog Timers + * * This include file contains all the constants and structures associated * with watchdog timers. This Handler provides mechanisms which can be * used to initialize and manipulate watchdog timers. @@ -38,7 +40,7 @@ extern "C" { #endif /** - * @brief Maximum Interval Length + * @brief Control block used to manage intervals. * * The following type defines the control block used to manage * intervals. @@ -46,14 +48,15 @@ extern "C" { #define WATCHDOG_MAXIMUM_INTERVAL ((Watchdog_Interval) 0xffffffff) /** - * @brief Watchdog Interval Type + * @brief Type is used to specify the length of intervals. * * This type is used to specify the length of intervals. */ typedef uint32_t Watchdog_Interval; /** - * @brief Watchdog Nanoseconds Since Last Tick Extension + * @brief Pointer to the BSP plugin to obtain the number + * of nanoseconds since the last clock tick. * * This type defines a pointer to the BSP plugin to obtain the number * of nanoseconds since the last clock tick. @@ -61,14 +64,14 @@ typedef uint32_t Watchdog_Interval; typedef uint32_t (*Watchdog_Nanoseconds_since_last_tick_routine)(void); /** - * @brief Watchdog Service Routine Return Type + * @brief Return type from a Watchdog Service Routine. * * This type defines the return type from a Watchdog Service Routine. */ typedef void Watchdog_Service_routine; /** - * @brief Watchdog Service Routine Pointer Type + * @brief Pointer to a watchdog service routine. * * This type define a pointer to a watchdog service routine. */ @@ -78,7 +81,7 @@ typedef Watchdog_Service_routine ( *Watchdog_Service_routine_entry )( ); /** - * @brief No timeout constant + * @brief The constant for indefinite wait. * * This is the constant for indefinite wait. It is actually an * illegal interval. @@ -86,7 +89,7 @@ typedef Watchdog_Service_routine ( *Watchdog_Service_routine_entry )( #define WATCHDOG_NO_TIMEOUT 0 /** - * @brief Watchdog States Type + * @brief Set of the states which a watchdog timer may be at any given time. * * This enumerated type is the set of the states in which a * watchdog timer may be at any given time. @@ -108,7 +111,8 @@ typedef enum { } Watchdog_States; /** - * @brief Watchdog Adjustment Directions Type + * @brief the manner in which a watchdog chain may + * be adjusted by the @ref _Watchdog_Adjust routine. * * The following enumerated type details the manner in which * a watchdog chain may be adjusted by the @ref _Watchdog_Adjust @@ -123,7 +127,7 @@ typedef enum { } Watchdog_Adjust_directions; /** - * @brief Watchdog Control Structure + * @brief The control block used to manage each watchdog timer. * * The following record defines the control block used * to manage each watchdog timer. @@ -154,7 +158,7 @@ typedef struct { } Watchdog_Control; /** - * @brief Watchdog Synchronization Level + * @brief Watchdog synchronization level. * * This used for synchronization purposes * during an insert on a watchdog delta chain. @@ -162,7 +166,7 @@ typedef struct { SCORE_EXTERN volatile uint32_t _Watchdog_Sync_level; /** - * @brief Watchdog Synchronization Count + * @brief Watchdog synchronization count. * * This used for synchronization purposes * during an insert on a watchdog delta chain. @@ -170,7 +174,7 @@ SCORE_EXTERN volatile uint32_t _Watchdog_Sync_level; SCORE_EXTERN volatile uint32_t _Watchdog_Sync_count; /** - * @brief Ticks Since System Boot + * @brief The number of ticks since the system was booted. * * This contains the number of ticks since the system was booted. */ @@ -178,7 +182,7 @@ SCORE_EXTERN volatile uint32_t _Watchdog_Sync_count; SCORE_EXTERN volatile Watchdog_Interval _Watchdog_Ticks_since_boot; /** - * @brief Watchdog Nanoseconds Since Last Tick Handler + * @brief The number of nanoseconds since the last clock tick. * * This is a pointer to the optional BSP plugin to obtain the number * of nanoseconds since the last clock tick. @@ -187,21 +191,21 @@ extern Watchdog_Nanoseconds_since_last_tick_routine _Watchdog_Nanoseconds_since_tick_handler; /** - * @brief Per Ticks Watchdog List + * @brief Watchdog chain which is managed at ticks. * * This is the watchdog chain which is managed at ticks. */ SCORE_EXTERN Chain_Control _Watchdog_Ticks_chain; /** - * @brief Per Seconds Watchdog List + * @brief Watchdog chain which is managed at second boundaries. * * This is the watchdog chain which is managed at second boundaries. */ SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain; /** - * @brief Watchdog Handler Initialization + * @brief Initialize the watchdog handler. * * This routine initializes the watchdog handler. The watchdog * synchronization flag is initialized and the watchdog chains are @@ -210,20 +214,21 @@ SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain; void _Watchdog_Handler_initialization( void ); /** - * @brief Remove Watchdog from List + * @brief Removes @a the_watchdog from the watchdog chain. * * This routine removes @a the_watchdog from the watchdog chain on which * it resides and returns the state @a the_watchdog timer was in. * * @param[in] the_watchdog will be removed - * @return the state in which @a the_watchdog was in when removed + * @retval the state in which @a the_watchdog was in when removed */ Watchdog_States _Watchdog_Remove ( Watchdog_Control *the_watchdog ); /** - * @brief Watchdog Adjust + * @brief Adjusts the @a header watchdog chain in the forward + * or backward @a direction for @a units ticks. * * This routine adjusts the @a header watchdog chain in the forward * or backward @a direction for @a units ticks. @@ -239,7 +244,8 @@ void _Watchdog_Adjust ( ); /** - * @brief Watchdog Adjust to Chain + * @brief Adjusts the @a header watchdog chain in the forward + * @a direction for @a units_arg ticks. * * This routine adjusts the @a header watchdog chain in the forward * @a direction for @a units_arg ticks. @@ -259,7 +265,8 @@ void _Watchdog_Adjust_to_chain( ); /** - * @brief Watchdog Insert + * @brief Inserts @a the_watchdog into the @a header watchdog chain + * for a time of @a units. * * This routine inserts @a the_watchdog into the @a header watchdog chain * for a time of @a units. @@ -274,7 +281,8 @@ void _Watchdog_Insert ( ); /** - * @brief Watchdog Tickle + * @brief This routine is invoked at appropriate intervals to update + * the @a header watchdog chain. * * This routine is invoked at appropriate intervals to update * the @a header watchdog chain. @@ -287,7 +295,7 @@ void _Watchdog_Tickle ( ); /** - * @brief Report Information on a Single Watchdog Instance + * @brief Report information on a single watchdog instance. * * This method prints a one line report on the watchdog instance * provided. The @a name may be used to identify the watchdog and @@ -306,7 +314,7 @@ void _Watchdog_Report( ); /** - * @brief Report Information on a Watchdog Chain + * @brief Report information on a watchdog chain. * * This method prints report on the watchdog chain provided. * The @a name may be used to identify the watchdog chain and @@ -326,7 +334,7 @@ void _Watchdog_Report_chain( ); /** - * @brief Default Nanoseconds Since Last Tick Handler + * @brief Handler for default nanoseconds since last tick. * * @retval 0 Always. */ diff --git a/cpukit/score/include/rtems/score/wkspace.h b/cpukit/score/include/rtems/score/wkspace.h index ffac4cbff0..91059f734f 100644 --- a/cpukit/score/include/rtems/score/wkspace.h +++ b/cpukit/score/include/rtems/score/wkspace.h @@ -1,5 +1,7 @@ /** - * @file rtems/score/wkspace.h + * @file rtems/score/wkspace.h + * + * @brief Information Related to the RAM Workspace * * This include file contains information related to the * RAM Workspace. This Handler provides mechanisms which can be used to @@ -44,7 +46,7 @@ extern "C" { SCORE_EXTERN Heap_Control _Workspace_Area; /** - * @brief Workspace Handler Initialization + * @brief Initilize workspace handler. * * This routine performs the initialization necessary for this handler. */ @@ -55,7 +57,7 @@ void _Workspace_Handler_initialization( ); /** - * @brief Allocate Memory from Workspace + * @brief Allocate memory from workspace. * * This routine returns the address of a block of memory of size * bytes. If a block of the appropriate size cannot be allocated @@ -63,14 +65,14 @@ void _Workspace_Handler_initialization( * * @param size is the requested size * - * @return a pointer to the requested memory or NULL. + * @retval a pointer to the requested memory or NULL. */ void *_Workspace_Allocate( size_t size ); /** - * @brief Free Memory to the Workspace + * @brief Free memory to the workspace. * * This function frees the specified block of memory. If the block * belongs to the Workspace and can be successfully freed, then @@ -88,27 +90,27 @@ void _Workspace_Free( ); /** - * @brief Workspace Allocate or Fail with Fatal Error + * @brief Workspace allocate or fail with fatal error. * * This routine returns the address of a block of memory of @a size * bytes. If a block of the appropriate size cannot be allocated * from the workspace, then the internal error handler is invoked. * * @param[in] size is the desired number of bytes to allocate - * @return If successful, the starting address of the allocated memory + * @retval If successful, the starting address of the allocated memory */ void *_Workspace_Allocate_or_fatal_error( size_t size ); /** - * @brief Duplicates String with Memory from the Workspace + * @brief Duplicates string with memory from the workspace. * * @param[in] string is the pointer to a zero terminated string. * @param[in] len is the length of the string (equal to strlen(string)). * - * @return NULL Not enough memory. - * @return other Duplicated string. + * @retval NULL Not enough memory. + * @retval other Duplicated string. */ char *_Workspace_String_duplicate( const char *string, diff --git a/cpukit/score/include/rtems/seterr.h b/cpukit/score/include/rtems/seterr.h index ddd5c1c685..f0e5b7ca6d 100644 --- a/cpukit/score/include/rtems/seterr.h +++ b/cpukit/score/include/rtems/seterr.h @@ -1,6 +1,8 @@ /** * @file rtems/seterr.h * + * @brief Data which Ease the Burden of Consistently Setting Errno + * * This file contains macros and definitions which ease the burden * of consistently setting errno and returning -1. */ @@ -17,6 +19,14 @@ #ifndef _RTEMS_SETERR_H #define _RTEMS_SETERR_H +/** + * @defgroup ScoreSetErr Set Errno + * + * @ingroup Score + * + */ +/**@{*/ + #include <errno.h> /** @@ -41,5 +51,6 @@ #define rtems_set_errno_and_return_minus_one_cast( _error, _cast ) \ do { errno = (_error); return (_cast) -1; } while(0) +/**@}*/ #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/system.h b/cpukit/score/include/rtems/system.h index 46f080b46a..0100b72b84 100644 --- a/cpukit/score/include/rtems/system.h +++ b/cpukit/score/include/rtems/system.h @@ -1,9 +1,11 @@ /** - * @file rtems/system.h + * @file * - * This include file contains information that is included in every - * function in the executive. This must be the first include file - * included in all internal RTEMS files. + * @brief Information Included in Every Function in the Executive + * + * This include file contains information that is included in every + * function in the executive. This must be the first include file + * included in all internal RTEMS files. */ /* @@ -20,6 +22,13 @@ #include <rtems/score/percpu.h> +/** + * @defgroup ScoreSystem System Information + * + * @ingroup Score + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -52,5 +61,6 @@ extern const char _Copyright_Notice[]; } #endif +/**@}*/ #endif /* end of include file */ |