diff options
| author | Joel Sherrill <joel.sherrill@OARcorp.com> | 2006-01-16 15:13:58 +0000 |
|---|---|---|
| committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 2006-01-16 15:13:58 +0000 |
| commit | 6a074363a2657a86b5f1ea0fc1185f68ad9f3c08 (patch) | |
| tree | 3785d2da164f2c26988014ad5dbae6e35aa24147 /cpukit/score/include | |
| parent | 2006-01-16 Joel Sherrill <joel@OARcorp.com> (diff) | |
| download | rtems-6a074363a2657a86b5f1ea0fc1185f68ad9f3c08.tar.bz2 | |
2006-01-16 Joel Sherrill <joel@OARcorp.com>
Large patch to improve Doxygen output. As a side-effect, grammar and
spelling errors were corrected, spacing errors were address, and some
variable names were improved.
* libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h:
Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS.
* score/Doxyfile: Set output directory. Predefine some macro values.
Turn on graphical output.
* score/include/rtems/debug.h, score/include/rtems/seterr.h,
score/include/rtems/system.h, score/include/rtems/score/address.h,
score/include/rtems/score/apiext.h,
score/include/rtems/score/apimutex.h,
score/include/rtems/score/bitfield.h,
score/include/rtems/score/chain.h,
score/include/rtems/score/context.h,
score/include/rtems/score/coremsg.h,
score/include/rtems/score/coremutex.h,
score/include/rtems/score/coresem.h,
score/include/rtems/score/heap.h, score/include/rtems/score/interr.h,
score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h,
score/include/rtems/score/mppkt.h,
score/include/rtems/score/object.h,
score/include/rtems/score/objectmp.h,
score/include/rtems/score/priority.h,
score/include/rtems/score/stack.h,
score/include/rtems/score/states.h,
score/include/rtems/score/sysstate.h,
score/include/rtems/score/thread.h,
score/include/rtems/score/threadmp.h,
score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h,
score/include/rtems/score/tqdata.h,
score/include/rtems/score/userext.h,
score/include/rtems/score/watchdog.h,
score/include/rtems/score/wkspace.h,
score/inline/rtems/score/address.inl,
score/inline/rtems/score/chain.inl,
score/inline/rtems/score/coremutex.inl,
score/inline/rtems/score/coresem.inl,
score/inline/rtems/score/heap.inl,
score/inline/rtems/score/object.inl,
score/inline/rtems/score/stack.inl,
score/inline/rtems/score/thread.inl,
score/inline/rtems/score/tqdata.inl, score/macros/README,
score/src/heap.c, score/src/threadmp.c, score/src/threadready.c,
score/src/threadstartmultitasking.c: Improve generated Doxygen
output. Fix spelling and grammar errors in comments. Correct names of
some variables and propagate changes.
Diffstat (limited to 'cpukit/score/include')
31 files changed, 1433 insertions, 721 deletions
diff --git a/cpukit/score/include/rtems/debug.h b/cpukit/score/include/rtems/debug.h index 31f0005709..abdb6200d0 100644 --- a/cpukit/score/include/rtems/debug.h +++ b/cpukit/score/include/rtems/debug.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,69 +24,49 @@ extern "C" { #endif -/* +/** * The following type is used to manage the debug mask. */ - typedef uint32_t rtems_debug_control; /* * These constants represent various classes of debugging. */ +/** Macro which indicates that all debugging modes are enabled */ #define RTEMS_DEBUG_ALL_MASK 0xffffffff + +/** Macro which indicates that debugging for heaps/regions is enabled */ #define RTEMS_DEBUG_REGION 0x00000001 -/* +/** * This variable contains the current debug level. */ - SCORE_EXTERN rtems_debug_control _Debug_Level; -/* - * _Debug_Manager_initialization - * - * DESCRIPTION: - * +/** * This routine performs the initialization necessary for this manager. */ - void _Debug_Manager_initialization( void ); -/* - * rtems_debug_enable - * - * DESCRIPTION: - * +/** * This routine enables the specified types of debug checks. */ - void rtems_debug_enable ( rtems_debug_control to_be_enabled ); -/* - * rtems_debug_disable - * - * DESCRIPTION: - * +/** * This routine disables the specified types of debug checks. */ - void rtems_debug_disable ( rtems_debug_control to_be_disabled ); -/* - * - * _Debug_Is_enabled - * - * DESCRIPTION: - * +/** * This routine returns TRUE if the requested debug level is * enabled, and FALSE otherwise. */ - boolean _Debug_Is_enabled( rtems_debug_control level ); diff --git a/cpukit/score/include/rtems/score/address.h b/cpukit/score/include/rtems/score/address.h index aab714afd4..405c5b715c 100644 --- a/cpukit/score/include/rtems/score/address.h +++ b/cpukit/score/include/rtems/score/address.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,8 +22,8 @@ /** * @defgroup ScoreAddress Address Handler * - * This group contains functionality which abstracts address manipulation - * in a portable manner. + * This handler encapsulates functionality which abstracts address + * manipulation in a portable manner. */ /**@{*/ diff --git a/cpukit/score/include/rtems/score/apiext.h b/cpukit/score/include/rtems/score/apiext.h index cd794bc2d1..e1135fbd63 100644 --- a/cpukit/score/include/rtems/score/apiext.h +++ b/cpukit/score/include/rtems/score/apiext.h @@ -1,11 +1,11 @@ -/** +/** * @file rtems/score/apiext.h * * This is the API Extensions Handler. */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,9 +21,9 @@ /** * @defgroup ScoreAPIExtension API Extension Handler * - * This group contains functionality which provides mechanisms for the - * SuperCore to perform API specific actions without there being - * "up-references" from the SuperCore to APIs. If these references + * This handler encapsulates functionality which provides mechanisms for the + * SuperCore to perform API specific actions without there beingg + * "up-references" from the SuperCore to APIs. If these referencesg * were allowed in the implementation, the cohesion would be too high * and adding an API would be more difficult. The SuperCore is supposed * to be largely independent of any API. @@ -87,31 +87,36 @@ typedef struct { */ SCORE_EXTERN Chain_Control _API_extensions_List; -/** +/** @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 + * * This routine adds an extension to the active set of API extensions. * - * @param the_extension (in) is the extension set to add. + * @param[in] the_extension is the extension set to add. */ void _API_extensions_Add( API_extensions_Control *the_extension ); -/** +/** @brief Execute all Pre-Driver Extensions + * * This routine executes all of the predriver callouts. */ void _API_extensions_Run_predriver( void ); -/** +/** @brief Execute all Post-Driver Extensions + * * This routine executes all of the postdriver callouts. */ void _API_extensions_Run_postdriver( void ); -/** +/** @brief Execute all Post Context Switch Extensions + * * This routine executes all of the post context switch callouts. */ void _API_extensions_Run_postswitch( void ); diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h index 914207fc81..ea257f4a7e 100644 --- a/cpukit/score/include/rtems/score/apimutex.h +++ b/cpukit/score/include/rtems/score/apimutex.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,7 @@ /** * @defgroup ScoreAPIMutex API Mutex Handler * - * This group contains functionality which provides mutexes to be used + * This handler encapsulates functionality which provides mutexes to be used * in the implementation of API functionality. */ /**@{*/ @@ -56,7 +56,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; /** * This routine performs the initialization necessary for this handler. * - * @param _maximum_mutexes (in) is the maximum number of API mutexes + * @param[in] _maximum_mutexes is the maximum number of API mutexes * that may exist at any time */ #if defined(RTEMS_MULTIPROCESSING) @@ -88,7 +88,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; /** * This routine allocates an API mutex from the inactive set. * - * @param _the_mutex (out) will contain the allocated mutex. + * @param[out] _the_mutex will contain the allocated mutex. */ #define _API_Mutex_Allocate( _the_mutex ) \ do { \ @@ -104,7 +104,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; /** * This routine acquires the specified API mutex. * - * @param _the_mutex (in) is the mutex to acquire. + * @param[in] _the_mutex is the mutex to acquire. */ #define _API_Mutex_Lock( _the_mutex ) \ do { \ @@ -117,7 +117,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; /** * This routine releases the specified API mutex. * - * @param _the_mutex (in) is the mutex to release. + * @param[in] _the_mutex is the mutex to release. */ #define _API_Mutex_Unlock( _the_mutex ) \ diff --git a/cpukit/score/include/rtems/score/bitfield.h b/cpukit/score/include/rtems/score/bitfield.h index 71fe09db6f..bfeef76dfc 100644 --- a/cpukit/score/include/rtems/score/bitfield.h +++ b/cpukit/score/include/rtems/score/bitfield.h @@ -5,7 +5,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,7 +21,7 @@ /** * @defgroup ScoreBitfield Bitfield Handler * - * This group contains functionality that is used to manipulate the + * This handler encapsulates functionality that is used to manipulate the * priority bitfields used to lookup which priority has the highest * priority ready to execute thread. */ @@ -70,8 +70,8 @@ const unsigned char __log2table[256] = { * the first bit set may run from most to least significant bit * or vice-versa. * - * @param _value (in) is the value to bit scan. - * @param _bit_number (in) is the position of the first bit set. + * @param[in] _value is the value to bit scan. + * @param[in] _bit_number is the position of the first bit set. * * @note This routine is used when the executing thread is removed * from the ready state and, as a result, its performance has a diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h index 0e3e930257..4a908cd19c 100644 --- a/cpukit/score/include/rtems/score/chain.h +++ b/cpukit/score/include/rtems/score/chain.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,11 @@ /** * @defgroup ScoreChain Chain Handler * - * The Chain Handler contains XXX + * The Chain Handler is used to manage sets of entities. This handler + * provides two data structures. The Chain Node data structure is included + * as the first part of every data structure that will be placed on + * a chain. The second data structure is Chain Control which is used + * to manage a set of Chain Nodes. */ /**@{*/ @@ -37,7 +41,8 @@ extern "C" { * * This type definition promotes the name for the Chain Node used by * all RTEMS code. It is a separate type definition because a forward - * reference is required to define it. + * reference is required to define it. See @ref Chain_Node_struct for + * detailed information. */ typedef struct Chain_Node_struct Chain_Node; @@ -95,11 +100,11 @@ typedef struct { * contiguous array of @a number_nodes nodes which starts at * @a starting_address. Each node is of @a node_size bytes. * - * @param the_chain (in) specifies the chain to initialize - * @param starting_address (in) is the starting address of the array + * @param[in] the_chain specifies the chain to initialize + * @param[in] starting_address is the starting address of the array * of elements - * @param number_nodes (in) is the numebr of nodes that will be in the chain - * @param node_size (in) is the size of each node + * @param[in] number_nodes is the numebr of nodes that will be in the chain + * @param[in] node_size is the size of each node */ void _Chain_Initialize( Chain_Control *the_chain, @@ -112,9 +117,9 @@ void _Chain_Initialize( /** * @brief Get the first node (do not disable interrupts) * - * This method attempts to obtain the first node from \a the_chain. + * This method attempts to obtain the first node from @a the_chain. * - * @param the_chain (in) points to the chain to operate upon + * @param[in] the_chain points to the chain to operate upon * @return If successful, a chain node is returned. Otherwise, NULL * is returned. */ @@ -126,8 +131,8 @@ Chain_Node *_Chain_Get_first_unprotected( /** * @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 insure the atomicity of the + * This routine extracts @a the_node from the chain on which it resides. + * It disables interrupts to ensure the atomicity of the * extract operation. * * @arg the_node specifies the node to extract @@ -139,11 +144,14 @@ void _Chain_Extract( /** * @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. + * 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. * - * @note It disables interrupts to insure the atomicity of the - * get operation. + * @return 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. + * + * @note It disables interrupts to ensure the atomicity of the get operation. */ Chain_Node *_Chain_Get( Chain_Control *the_chain @@ -152,10 +160,10 @@ Chain_Node *_Chain_Get( /** * @brief Insert a node on a chain * - * This routine inserts \a the_node on a chain immediately following - * \a after_node. + * This routine inserts @a the_node on a chain immediately following + * @a after_node. * - * @note It disables interrupts to insure the atomicity + * @note It disables interrupts to ensure the atomicity * of the extract operation. */ void _Chain_Insert( @@ -166,9 +174,9 @@ void _Chain_Insert( /** * @brief Append a node on the end of a chain * - * This routine appends \a the_node onto the end of \a the_chain. + * This routine appends @a the_node onto the end of @a the_chain. * - * @note It disables interrupts to insure the atomicity of the + * @note It disables interrupts to ensure the atomicity of the * append operation. */ void _Chain_Append( diff --git a/cpukit/score/include/rtems/score/context.h b/cpukit/score/include/rtems/score/context.h index 5c7e0fa3b9..87c61957ba 100644 --- a/cpukit/score/include/rtems/score/context.h +++ b/cpukit/score/include/rtems/score/context.h @@ -5,7 +5,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,7 +21,7 @@ /** * @defgroup ScoreContext Context Handler * - * This group contains functionality which abstracts thread context + * This handler encapsulates functionality which abstracts thread context * management in a portable manner. */ /**@{*/ @@ -33,14 +33,16 @@ extern "C" { #include <rtems/score/cpu.h> /** - * @ingroup ScoreContext + * @brief Size of Floating Point Context Area + * * This constant defines the number of bytes required * to store a full floating point context. */ #define CONTEXT_FP_SIZE CPU_CONTEXT_FP_SIZE /** - * @ingroup ScoreContext + * @brief Is Context Switch Needed? + * * This variable is set to TRUE when a reschedule operation * has determined that the processor should be taken away from the * currently executing thread and given to the heir thread. @@ -49,54 +51,56 @@ extern "C" { SCORE_EXTERN volatile boolean _Context_Switch_necessary; /** - * @ingroup ScoreContext + * @brief Initialize Context Area * This routine initializes @a _the_context such that the stack * pointer, interrupt level, and entry point are correct for the * thread's initial state. * - * @param _the_context (in) will be initialized - * @param _stack (in) is the lowest physical address of the thread's + * @param[in] _the_context will be initialized + * @param[in] _stack is the lowest physical address of the thread's * context - * @param _size (in) is the size in octets of the thread's context - * @param _isr (in) is the ISR enable level for this thread - * @param _entry (in) is this thread's entry point - * @param _is_fp (in) is set to TRUE if this thread has floating point + * @param[in] _size is the size in octets of the thread's context + * @param[in] _isr is the ISR enable level for this thread + * @param[in] _entry is this thread's entry point + * @param[in] _is_fp is set to TRUE if this thread has floating point * enabled */ -#define \ - _Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) \ +#define _Context_Initialize(_the_context, _stack, _size, _isr, _entry, _is_fp) \ _CPU_Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) /** - * @ingroup ScoreContext + * @brief Perform Context Switch + * * This routine saves the current context into the @a _executing * context record and restores the context specified by @a _heir. * - * @param _executing (in) is the currently executing thread's context - * @param _heir (in) is the context of the thread to be switched to + * @param[in] _executing is the currently executing thread's context + * @param[in] _heir is the context of the thread to be switched to */ #define _Context_Switch( _executing, _heir ) \ _CPU_Context_switch( _executing, _heir ) /** - * @ingroup ScoreContext + * @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. * - * @param _the_context (in) is the context of the thread to restart + * @param[in] _the_context is the context of the thread to restart */ #define _Context_Restart_self( _the_context ) \ _CPU_Context_Restart_self( _the_context ) /** - * @ingroup ScoreContext + * @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 * for the floating point save area is large enough. * - * @param _base (in) is lowest physical address of the floating point + * @param[in] _base is lowest physical address of the floating point * context save area. - * @param _offset (in) is XXX + * @param[in] _offset is the offset into the floating point area * * @return the initial FP context pointer */ @@ -104,34 +108,37 @@ SCORE_EXTERN volatile boolean _Context_Switch_necessary; _CPU_Context_Fp_start( (_base), (_offset) ) /** - * @ingroup ScoreContext + * @brief Initialize Floating Point Context Area + * * This routine initializes the floating point context save * area to contain an initial known state. * - * @param _fp_area (in) is the base address of the floating point + * @param[in] _fp_area is the base address of the floating point * context save area to initialize. */ #define _Context_Initialize_fp( _fp_area ) \ _CPU_Context_Initialize_fp( _fp_area ) /** - * @ingroup ScoreContext + * @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 * floating point context has been saved by a previous invocation * of @a _Context_Save_fp. * - * @param _fp (in) points to the floating point context area to restore. + * @param[in] _fp points to the floating point context area to restore. */ #define _Context_Restore_fp( _fp ) \ _CPU_Context_restore_fp( _fp ) /** - * @ingroup ScoreContext + * @brief Save Floating Point Context Area + * * This routine saves the current floating point context * in the @a _fp area. * - * @param _fp (in) points to the floating point context area to restore. + * @param[in] _fp points to the floating point context area to restore. */ #define _Context_Save_fp( _fp ) \ _CPU_Context_save_fp( _fp ) diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h index 55817f3ff4..08343a1e19 100644 --- a/cpukit/score/include/rtems/score/coremsg.h +++ b/cpukit/score/include/rtems/score/coremsg.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,7 @@ /** * @defgroup ScoreMessageQueue Message Queue Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Message Queue services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -38,6 +38,8 @@ extern "C" { #include <rtems/score/watchdog.h> /** + * @brief Message Queue MP Callback Prototype + * * The following type defines the callout which the API provides * to support global/multiprocessor operations on message_queues. */ @@ -47,6 +49,8 @@ typedef void ( *CORE_message_queue_API_mp_support_callout )( ); /** + * @brief Message Buffer Contents Management Structure + * * The following defines the data types needed to manipulate * the contents of message buffers. * @@ -61,6 +65,8 @@ typedef struct { } CORE_message_queue_Buffer; /** + * @brief Message Structure + * * The following records define the organization of a message * buffer. */ @@ -74,7 +80,10 @@ typedef struct { } CORE_message_queue_Buffer_control; /** - * Blocking disciplines for a message queue. + * @brief Message Queue Blocking Disciplines + * + * This enumerated types defines the possible blocking disciplines + * for a message queue. */ typedef enum { /** This value indicates that pending messages are in FIFO order. */ @@ -84,19 +93,25 @@ typedef enum { } CORE_message_queue_Disciplines; /** + * @brief Message Priority for Appending + * * This is the priority constant used when appending messages onto * a message queue. */ #define CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX /** + * @brief Message Priority for Prepending + * * This is the priority constant used when prepending messages onto * a message queue. */ #define CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN /** - * The following enumerated type details the modes in which a message + * @brief Message Insertion Operation Types + * + * The following type details the modes in which a message * may be submitted to a message queue. The message may be posted * in a send or urgent fashion. * @@ -106,7 +121,10 @@ typedef enum { typedef int CORE_message_queue_Submit_types; /** - * Core Message queue handler return statuses. + * @brief Core Message Queue Return Statuses + * + * This enumerated type defines the possible set of Core Message + * Queue handler return statuses. */ typedef enum { /** This value indicates the operation completed sucessfully. */ @@ -132,6 +150,8 @@ typedef enum { } CORE_message_queue_Status; /** + * @brief Message Queue Attributes Type + * * The following defines the control block used to manage the * attributes of each message queue. */ @@ -141,6 +161,8 @@ typedef struct { } CORE_message_queue_Attributes; /** + * @brief Message Queue Notification Callback Prototype + * * The following defines the type for a Notification handler. A notification * handler is invoked when the message queue makes a 0->1 transition on * pending messages. @@ -148,8 +170,10 @@ typedef struct { typedef void (*CORE_message_queue_Notify_Handler)( void * ); /** + * @brief Core Message Queue Control Structure + * * The following defines the control block used to manage each - * counting message_queue. + * Message Queue */ typedef struct { /** This field is the Waiting Queue used to manage the set of tasks @@ -193,14 +217,16 @@ typedef struct { } CORE_message_queue_Control; /** - * This routine initializes the message_queue based on the parameters passed. + * @brief Initialize a Message Queue * - * @param the_message_queue (in) points to the message queue to initialize - * @param the_message_queue_attributes (in) points to the attributes that + * This routine initializes @a the_message_queue based on the parameters passed. + * + * @param[in] the_message_queue points to the message queue to initialize + * @param[in] the_message_queue_attributes points to the attributes that * will be used with this message queue instance - * @param maximum_pending_messages (in) is the maximum number of messages + * @param[in] maximum_pending_messages is the maximum number of messages * that will be allowed to pend at any given time - * @param maximum_message_size (in) is the size of largest message that + * @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, @@ -215,13 +241,15 @@ boolean _CORE_message_queue_Initialize( ); /** + * @brief Close a Message Queue + * * This function closes a message by returning all allocated space and - * flushing the message_queue's task wait queue. + * flushing @a the_message_queue's task wait queue. * - * @param the_message_queue (in) points to the message queue to close - * @param remote_extract_callout (in) is the routine to call for each thread + * @param[in] the_message_queue points to the message queue to close + * @param[in] remote_extract_callout is the routine to call for each thread * that is extracted from the set of waiting threads - * @param status (in) is the status that each waiting thread will return + * @param[in] status is the status that each waiting thread will return * from it's blocking service */ void _CORE_message_queue_Close( @@ -231,50 +259,60 @@ void _CORE_message_queue_Close( ); /** - * This function flushes the message_queue's pending message queue. The + * @brief Flush Pending Messages + * + * This function flushes @a the_message_queue's pending message queue. The * number of messages flushed from the queue is returned. * - * @param the_message_queue (in) points to the message queue to flush - * @return the number of message pending messages flushed + * @param[in] the_message_queue points to the message queue to flush + * + * @return 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 + * * This routine flushes all outstanding messages and returns * them to the inactive message chain. * - * @param the_message_queue (in) points to the message queue to flush - * @return the number of message pending messages flushed + * @param[in] the_message_queue points to the message queue to flush + * + * @return This method returns the number of message pending messages flushed. */ uint32_t _CORE_message_queue_Flush_support( CORE_message_queue_Control *the_message_queue ); /** - * This function flushes the threads which are blocked on this - * message_queue's pending message queue. They are unblocked whether - * blocked sending or receiving. + * @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. * - * @param the_message_queue (in) points to the message queue to flush + * @param[in] the_message_queue points to the message queue to flush */ void _CORE_message_queue_Flush_waiting_threads( CORE_message_queue_Control *the_message_queue ); /** + * @brief Broadcast a Message to the Message Queue + * * This function sends a message for every thread waiting on the queue and * returns the number of threads made ready by the message. * - * @param the_message_queue (in) points to the message queue - * @param buffer (in) is the starting address of the message to broadcast - * @param size (in) is the size of the message being broadcast - * @param id (in) is the RTEMS object Id associated with this message queue. + * @param[in] the_message_queue points to the message queue + * @param[in] buffer is the starting address of the message to broadcast + * @param[in] size is the size of the message being broadcast + * @param[in] id is the RTEMS object Id associated with this message queue. * It is used when unblocking a remote thread. - * @param api_message_queue_mp_support (in) is the routine to invoke if + * @param[in] api_message_queue_mp_support is the routine to invoke if * a thread that is unblocked is actually a remote thread. - * @param count (out) points to the variable that will contain the + * @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 @@ -289,6 +327,8 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast( ); /** + * @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 * message queue. The message will either be processed as a @@ -296,18 +336,18 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast( * or it will be processed as an urgent message which will be inserted * at the front of the queue. * - * @param the_message_queue (in) points to the message queue - * @param buffer (in) is the starting address of the message to send - * @param size (in) is the size of the message being send - * @param id (in) is the RTEMS object Id associated with this message queue. + * @param[in] the_message_queue points to the message queue + * @param[in] buffer is the starting address of the message to send + * @param[in] size is the size of the message being send + * @param[in] id is the RTEMS object Id associated with this message queue. * It is used when unblocking a remote thread. - * @param api_message_queue_mp_support (in) is the routine to invoke if + * @param[in] api_message_queue_mp_support is the routine to invoke if * a thread that is unblocked is actually a remote thread. - * @param submit_type (in) determines whether the message is prepended, + * @param[in] submit_type determines whether the message is prepended, * appended, or enqueued in priority order. - * @param wait (in) indicates whether the calling thread is willing to block + * @param[in] wait indicates whether the calling thread is willing to block * if the message queue is full. - * @param timeout (in) is the maximum number of clock ticks that the calling + * @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 */ @@ -323,21 +363,23 @@ CORE_message_queue_Status _CORE_message_queue_Submit( ); /** + * @brief Size a Message from the Message Queue + * * This kernel routine dequeues a message, copies the message buffer to * a given destination buffer, and frees the message buffer to the * inactive message pool. The thread will be blocked if wait is TRUE, * otherwise an error will be given to the thread if no messages are available. * - * @param the_message_queue (in) points to the message queue - * @param id (in) is the RTEMS object Id associated with this message queue. + * @param[in] the_message_queue points to the message queue + * @param[in] id is the RTEMS object Id associated with this message queue. * It is used when unblocking a remote thread. - * @param buffer (in) is the starting address of the message buffer to + * @param[in] buffer is the starting address of the message buffer to * to be filled in with a message - * @param size (in) is the size of the @a buffer and indicates the maximum + * @param[in] size is the size of the @a buffer and indicates the maximum * size message that the caller can receive. - * @param wait (in) indicates whether the calling thread is willing to block + * @param[in] wait indicates whether the calling thread is willing to block * if the message queue is empty. - * @param timeout (in) is the maximum number of clock ticks that the calling + * @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 @@ -357,9 +399,9 @@ void _CORE_message_queue_Seize( * message queue. It is assumed that the message has been filled * in before this routine is called. * - * @param the_message_queue (in) points to the message queue - * @param the_message (in) is the message to enqueue - * @param submit_type (in) determines whether the message is prepended, + * @param[in] the_message_queue points to the message queue + * @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. */ void _CORE_message_queue_Insert_message( diff --git a/cpukit/score/include/rtems/score/coremutex.h b/cpukit/score/include/rtems/score/coremutex.h index 1d95f8265e..4015ac97e4 100644 --- a/cpukit/score/include/rtems/score/coremutex.h +++ b/cpukit/score/include/rtems/score/coremutex.h @@ -8,7 +8,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,7 +24,7 @@ /** * @defgroup ScoreMutex Mutex Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Mutex services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -41,6 +41,8 @@ extern "C" { #include <rtems/score/sysstate.h> /** + * @brief MP Support Callback Prototype + * * The following type defines the callout which the API provides * to support global/multiprocessor operations on mutexes. */ @@ -50,7 +52,9 @@ typedef void ( *CORE_mutex_API_mp_support_callout )( ); /** - * Blocking disciplines for a mutex. + * @brief Blocking Disciplines Enumerated Type + * + * This enumerated type defines the blocking disciplines for a mutex. */ typedef enum { /** This specifies that threads will wait for the mutex in FIFO order. */ @@ -68,7 +72,9 @@ typedef enum { } CORE_mutex_Disciplines; /** - * Mutex handler return statuses. + * @brief Mutex method return statuses + * + * This enumerated type defines the possible Mutex handler return statuses. */ typedef enum { /** This status indicates that the operation completed successfully. */ @@ -102,32 +108,35 @@ typedef enum { } CORE_mutex_Status; /** - * Mutex lock nesting behavior - * - * + CORE_MUTEX_NESTING_ACQUIRES: - * This sequence has no blocking or errors: - * - * + lock(m) - * + lock(m) - * + unlock(m) - * + unlock(m) + * @brief Mutex Lock Nesting Behavior Enumeration * - * + CORE_MUTEX_NESTING_IS_ERROR - * This sequence returns an error at the indicated point: - * - * + lock(m) - * + lock(m) - already locked error - * + unlock(m) - * - * + CORE_MUTEX_NESTING_BLOCKS - * This sequence performs as indicated: - * + lock(m) - * + lock(m) - deadlocks or timeouts - * + unlock(m) - releases + * This enumerated type defines the possible behaviors for + * lock nesting. */ typedef enum { + /** + * This sequence has no blocking or errors: + * + * + lock(m) + * + lock(m) + * + unlock(m) + * + unlock(m) + */ CORE_MUTEX_NESTING_ACQUIRES, + /** + * This sequence returns an error at the indicated point: + * + * + lock(m) + * + lock(m) - already locked error + * + unlock(m) + */ CORE_MUTEX_NESTING_IS_ERROR, + /** + * This sequence performs as indicated: + * + lock(m) + * + lock(m) - deadlocks or timeouts + * + unlock(m) - releases + */ CORE_MUTEX_NESTING_BLOCKS } CORE_mutex_Nesting_behaviors; @@ -142,6 +151,8 @@ typedef enum { #define CORE_MUTEX_LOCKED 0 /** + * @brief Core Mutex Attributes + * * The following defines the control block used to manage the * attributes of each mutex. */ @@ -165,6 +176,8 @@ typedef struct { } CORE_mutex_Attributes; /** + * @brief Core Mutex Control Structure + * * The following defines the control block used to manage each mutex. */ typedef struct { @@ -195,13 +208,14 @@ typedef struct { } CORE_mutex_Control; /** + * @brief Initialize a Core Mutex * * This routine initializes the mutex based on the parameters passed. * - * @param the_mutex (in) is the mutex to initalize - * @param the_mutex_attributes (in) is the attributes associated with this + * @param[in] the_mutex is the mutex to initalize + * @param[in] the_mutex_attributes is the attributes associated with this * mutex instance - * @param initial_lock (in) is the initial value of the mutex + * @param[in] initial_lock is the initial value of the mutex */ void _CORE_mutex_Initialize( CORE_mutex_Control *the_mutex, @@ -211,13 +225,20 @@ void _CORE_mutex_Initialize( #ifndef __RTEMS_APPLICATION__ /** + * @brief Seize Mutex with Quick Success Path + * * 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 * returns. Otherwise, the calling task is blocked until a unit becomes * available. * - * @param the_mutex (in) is the mutex to attempt to lock - * @param level_p (in) is the interrupt level holder + * @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 + * 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. * * @note For performance reasons, this routine is implemented as * a macro that uses two support routines. @@ -228,12 +249,14 @@ RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock( ); /** + * @brief Seize Mutex with Blockign + * * This routine performs the blocking portion of a mutex obtain. * It is an actual subroutine and is not implemented as something * that may be inlined. * - * @param the_mutex (in) is the mutex to attempt to lock - * @param timeout (in) is the maximum number of ticks to block + * @param[in] the_mutex is the mutex to attempt to lock + * @param[in] timeout is the maximum number of ticks to block */ void _CORE_mutex_Seize_interrupt_blocking( CORE_mutex_Control *the_mutex, @@ -241,16 +264,22 @@ void _CORE_mutex_Seize_interrupt_blocking( ); /** + * @brief Sieze Interrupt Wrapper + * * This routine attempts to obtain the mutex. If the mutex is available, * then it will return immediately. Otherwise, it will invoke the * support routine @a _Core_mutex_Seize_interrupt_blocking. * - * @param _the_mutex (in) is the mutex to attempt to lock - * @param _id (in) is the Id of the owning API level Semaphore object - * @param _wait (in) is TRUE if the thread is willing to wait - * @param _timeout (in) is the maximum number of ticks to block - * @param _level (in) is a temporary variable used to contain the ISR + * @param[in] _the_mutex is the mutex to attempt to lock + * @param[in] _id is the Id of the owning API level Semaphore object + * @param[in] _wait is TRUE if the thread is willing to wait + * @param[in] _timeout is the maximum number of ticks to block + * @param[in] _level is a temporary variable used to contain the ISR * disable level cookie + * + * @note If the mutex is called from an interrupt service routine, + * with context switching disabled, or before multitasking, + * then a fatal error is generated. */ #define _CORE_mutex_Seize( \ _the_mutex, _id, _wait, _timeout, _level ) \ @@ -281,13 +310,15 @@ void _CORE_mutex_Seize_interrupt_blocking( } while (0) /** + * @brief Surrender 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 * given to that task. Otherwise, the unit will be returned to the mutex. * - * @param the_mutex (in) is the mutex to surrender - * @param id (in) is the id of the RTEMS Object associated with this mutex - * @param api_mutex_mp_support (in) is the routine that will be called when + * @param[in] the_mutex is the mutex to surrender + * @param[in] id is the id of the RTEMS Object associated with this mutex + * @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 @@ -299,13 +330,15 @@ CORE_mutex_Status _CORE_mutex_Surrender( ); /** + * @brief Flush all waiting threads + * * This routine assists in the deletion of a mutex by flushing the associated * wait queue. * - * @param the_mutex (in) is the mutex to flush - * @param remote_extract_callout (in) is the routine to invoke when a remote + * @param[in] the_mutex is the mutex to flush + * @param[in] remote_extract_callout is the routine to invoke when a remote * thread is extracted - * @param status (in) is the status value which each unblocked thread will + * @param[in] status is the status value which each unblocked thread will * return to its caller. */ void _CORE_mutex_Flush( diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h index 866e59d360..54621fce84 100644 --- a/cpukit/score/include/rtems/score/coresem.h +++ b/cpukit/score/include/rtems/score/coresem.h @@ -8,7 +8,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,7 +24,7 @@ /** * @defgroup ScoreSemaphore Semaphore Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Semaphore services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -118,9 +118,9 @@ typedef struct { /** * This routine initializes the semaphore based on the parameters passed. * - * @param the_semaphore (in) is the semaphore to initialize - * @param the_semaphore_attributes (in) define the behavior of this instance - * @param initial_value (in) is the initial count of the semaphore + * @param[in] the_semaphore is the semaphore to initialize + * @param[in] the_semaphore_attributes define the behavior of this instance + * @param[in] initial_value is the initial count of the semaphore */ void _CORE_semaphore_Initialize( CORE_semaphore_Control *the_semaphore, @@ -134,11 +134,11 @@ void _CORE_semaphore_Initialize( * returns. Otherwise, the calling task is blocked until a unit becomes * available. * - * @param the_semaphore (in) is the semaphore to seize - * @param id (in) is the Id of the API level Semaphore object associated + * @param[in] the_semaphore is the semaphore to seize + * @param[in] id is the Id of the API level Semaphore object associated * with this instance of a SuperCore Semaphore - * @param wait (in) is TRUE if the calling thread is willing to wait - * @param timeout (in) is the number of ticks the calling thread is willing + * @param[in] wait is TRUE if the calling thread is willing to wait + * @param[in] timeout is the number of ticks the calling thread is willing * to wait if @a wait is TRUE. */ void _CORE_semaphore_Seize( @@ -153,10 +153,10 @@ void _CORE_semaphore_Seize( * for a unit from this semaphore, then that task will be readied and the unit * given to that task. Otherwise, the unit will be returned to the semaphore. * - * @param the_semaphore (in) is the semaphore to surrender - * @param id (in) is the Id of the API level Semaphore object associated + * @param[in] the_semaphore is the semaphore to surrender + * @param[in] id is the Id of the API level Semaphore object associated * with this instance of a SuperCore Semaphore - * @param api_semaphore_mp_support (in) is the routine to invoke if the + * @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 @@ -171,10 +171,10 @@ CORE_semaphore_Status _CORE_semaphore_Surrender( * This routine assists in the deletion of a semaphore by flushing the * associated wait queue. * - * @param the_semaphore (in) is the semaphore to flush - * @param remote_extract_callout (in) is the routine to invoke if the + * @param[in] the_semaphore is the semaphore to flush + * @param[in] remote_extract_callout is the routine to invoke if the * thread unblocked is remote - * @param status (in) is the status to be returned to the unblocked thread + * @param[in] status is the status to be returned to the unblocked thread */ void _CORE_semaphore_Flush( CORE_semaphore_Control *the_semaphore, diff --git a/cpukit/score/include/rtems/score/heap.h b/cpukit/score/include/rtems/score/heap.h index 4ec7396854..c00e2c7098 100644 --- a/cpukit/score/include/rtems/score/heap.h +++ b/cpukit/score/include/rtems/score/heap.h @@ -18,7 +18,7 @@ * required to be multiple of CPU_ALIGNMENT and explicitly not * required to be a power of two. * - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -34,7 +34,7 @@ /** * @defgroup ScoreHeap Heap Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Heap services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -251,12 +251,14 @@ typedef struct { * @a page_size byte units. If @a page_size is 0 or is not multiple of * CPU_ALIGNMENT, it's aligned up to the nearest CPU_ALIGNMENT boundary. * - * @param the_heap (in) is the heap to operate upon - * @param starting_address (in) is the starting address of the memory for + * @param[in] the_heap is the heap to operate upon + * @param[in] starting_address is the starting address of the memory for * the heap - * @param size (in) is the size in bytes of the memory area for the heap - * @param page_size (in) is the size in bytes of the allocation unit - * @return XXX + * @param[in] size is the size in bytes of the memory area for the heap + * @param[in] page_size is the size in bytes of the allocation unit + * + * @return This method returns the maximum memory available. If + * unsuccessful, 0 will be returned. */ uint32_t _Heap_Initialize( Heap_Control *the_heap, @@ -269,11 +271,11 @@ uint32_t _Heap_Initialize( * This routine grows @a the_heap memory area using the size bytes which * begin at @a starting_address. * - * @param the_heap (in) is the heap to operate upon - * @param starting_address (in) is the starting address of the memory + * @param[in] the_heap is the heap to operate upon + * @param[in] starting_address is the starting address of the memory * to add to the heap - * @param size (in) is the size in bytes of the memory area to add - * @param amount_extended (in) points to a user area to return the + * @param[in] size is the size in bytes of the memory area to add + * @param[in] amount_extended points to a user area to return the * @return a status indicating success or the reason for failure * @return *size filled in with the amount of memory added to the heap */ @@ -289,8 +291,8 @@ Heap_Extend_status _Heap_Extend( * @a the_heap. If insufficient memory is free in @a the_heap to allocate * a block of the requested size, then NULL is returned. * - * @param the_heap (in) is the heap to operate upon - * @param size (in) is the amount of memory to allocate in bytes + * @param[in] the_heap is the heap to operate upon + * @param[in] size is the amount of memory to allocate in bytes * @return NULL if unsuccessful and a pointer to the block if successful */ void *_Heap_Allocate( @@ -307,9 +309,9 @@ void *_Heap_Allocate( * Returns pointer to the start of the memory block if success, NULL if * failure. * - * @param the_heap (in) is the heap to operate upon - * @param size (in) is the amount of memory to allocate in bytes - * @param alignment (in) the required alignment + * @param[in] the_heap is the heap to operate upon + * @param[in] size is the amount of memory to allocate in bytes + * @param[in] alignment the required alignment * @return NULL if unsuccessful and a pointer to the block if successful */ void *_Heap_Allocate_aligned( @@ -325,10 +327,10 @@ void *_Heap_Allocate_aligned( * Returns TRUE if the @a starting_address is in the heap, and FALSE * otherwise. * - * @param the_heap (in) is the heap to operate upon - * @param starting_address (in) is the starting address of the user block + * @param[in] the_heap is the heap to operate upon + * @param[in] starting_address is the starting address of the user block * to obtain the size of - * @param size (in) points to a user area to return the size in + * @param[in] size points to a user area to return the size in * @return TRUE if successfully able to determine the size, FALSE otherwise * @return *size filled in with the size of the user area for this block */ @@ -338,17 +340,17 @@ boolean _Heap_Size_of_user_area( size_t *size ); -/* +/** * This function tries to resize in place the block that is pointed to by the * @a starting_address to the new @a size. * - * @param the_heap (in) is the heap to operate upon - * @param starting_address (in) is the starting address of the user block + * @param[in] the_heap is the heap to operate upon + * @param[in] starting_address is the starting address of the user block * to be resized - * @param size (in) is the new size - * @param old_mem_size (in) points to a user area to return the size of the + * @param[in] size is the new size + * @param[in] old_mem_size points to a user area to return the size of the * user memory area of the block before resizing. - * @param avail_mem_size (in) points to a user area to return the size of + * @param[in] avail_mem_size points to a user area to return the size of * the user memory area of the free block that has been enlarged or * created due to resizing, 0 if none. * @return HEAP_RESIZE_SUCCESSFUL if successfully able to resize the block, @@ -373,8 +375,8 @@ Heap_Resize_status _Heap_Resize_block( * at @a starting_address to @a the_heap. Any coalescing which is * possible with the freeing of this routine is performed. * - * @param the_heap (in) is the heap to operate upon - * @param starting_address (in) is the starting address of the user block + * @param[in] the_heap is the heap to operate upon + * @param[in] start_address is the starting address of the user block * to free * @return TRUE if successfully freed, FALSE otherwise */ @@ -386,12 +388,12 @@ boolean _Heap_Free( /** * This routine walks the heap to verify its integrity. * - * @param the_heap (in) is the heap to operate upon - * @param source (in) XXX - * @param do_dump (in) is set to TRUE if errors should be printed + * @param[in] the_heap is the heap to operate upon + * @param[in] source is a user specified integer which may be used to + * indicate where in the application this was invoked from + * @param[in] do_dump is set to TRUE if errors should be printed * @return TRUE if the test passed fine, FALSE otherwise. */ - boolean _Heap_Walk( Heap_Control *the_heap, int source, @@ -402,8 +404,8 @@ boolean _Heap_Walk( * This routine walks the heap and tots up the free and allocated * sizes. * - * @param the_heap (in) pointer to heap header - * @param the_info (in) pointer to a status information area + * @param[in] the_heap pointer to heap header + * @param[in] the_info pointer to a status information area * @return *the_info is filled with status information * @return 0=success, otherwise heap is corrupt. */ @@ -416,12 +418,11 @@ Heap_Get_information_status _Heap_Get_information( * This heap routine returns information about the free blocks * in the specified heap. * - * @param the_heap (in) pointer to heap header. - * @param info (in) pointer to the free block information. + * @param[in] the_heap pointer to heap header. + * @param[in] info pointer to the free block information. * * @return free block information filled in. */ - void _Heap_Get_free_information( Heap_Control *the_heap, Heap_Information *info @@ -429,27 +430,53 @@ void _Heap_Get_free_information( #if !defined(__RTEMS_APPLICATION__) -/* +/** * A pointer to unsigned integer conversion. */ #define _H_p2u(_p) ((_H_uptr_t)(_p)) #include <rtems/score/heap.inl> -/* - * Internal routines shared by _Heap_Allocate() and _Heap_Allocate_aligned(). - * Refer to 'heap.c' for details. +/** + * Convert user requested 'size' of memory block to the block size. + * + * @note This is an internal routine used by _Heap_Allocate() and + * _Heap_Allocate_aligned(). Refer to 'heap.c' for details. + * + * @param[in] size is the size of the block requested + * @param[in] page_size is the page size of this heap instance + * @param[in] min_size is minimum size block that should be allocated + * from this heap instance + * + * @return This method returns block size on success, 0 if overflow occured. */ - extern uint32_t _Heap_Calc_block_size( uint32_t size, uint32_t page_size, - uint32_t min_size); + uint32_t min_size +); +/** + * This method allocates a block of size @a alloc_size from @a the_block + * belonging to @a the_heap. Split @a the_block if possible, otherwise + * allocate it entirely. When split, make the lower part used, and leave + * the upper part free. + * + * This is an internal routines used by _Heap_Allocate() and + * _Heap_Allocate_aligned(). Refer to 'heap.c' for details. + * + * @param[in] the_heap is the heap to operate upon + * @param[in] the_block is the block to allocates the requested size from + * @param[in] alloc_size is the requested number of bytes to take out of + * the block + * + * @return This methods returns the size of the allocated block. + */ extern uint32_t _Heap_Block_allocate( Heap_Control* the_heap, - Heap_Block* the_block, - uint32_t alloc_size); + Heap_Block* the_block, + uint32_t alloc_size +); /* * Debug support @@ -459,16 +486,14 @@ extern uint32_t _Heap_Block_allocate( #define RTEMS_HEAP_DEBUG #endif -#if defined(RTEMS_HEAP_DEBUG) - -#include <assert.h> - -/* +/** * We do asserts only for heaps with instance number greater than 0 assuming * that the heap used for malloc is initialized first and thus has instance * number 0. Asserting malloc heap may lead to troubles as printf may invoke * malloc thus probably leading to infinite recursion. */ +#if defined(RTEMS_HEAP_DEBUG) +#include <assert.h> #define _HAssert(cond_) \ do { \ diff --git a/cpukit/score/include/rtems/score/interr.h b/cpukit/score/include/rtems/score/interr.h index cdc4551b84..a9fb98c0ae 100644 --- a/cpukit/score/include/rtems/score/interr.h +++ b/cpukit/score/include/rtems/score/interr.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,7 @@ /** * @defgroup ScoreIntErr Internal Error Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * Semaphore services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -42,7 +42,7 @@ typedef enum { INTERNAL_ERROR_ITRON_API } Internal_errors_Source; -/* +/** * A list of errors which are generated internally by the executive core. */ typedef enum { @@ -65,16 +65,19 @@ typedef enum { INTERNAL_ERROR_BAD_ATTRIBUTES } Internal_errors_Core_list; -/* +/** * This type holds the fatal error information. */ typedef struct { + /** This is the source of the error. */ Internal_errors_Source the_source; + /** This indicates if the error is internal of external. */ boolean is_internal; + /** This is the error code. */ uint32_t the_error; } Internal_errors_Information; -/* +/** * When a fatal error occurs, the error information is stored here. */ SCORE_EXTERN Internal_errors_Information Internal_errors_What_happened; diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h index 45a4f1f676..320332dfd7 100644 --- a/cpukit/score/include/rtems/score/isr.h +++ b/cpukit/score/include/rtems/score/isr.h @@ -8,7 +8,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,7 +24,7 @@ /** * @defgroup ScoreISR ISR Handler * - * This group contains functionality which provides the foundation + * This handler encapsulates functionality which provides the foundation * ISR services used in all of the APIs supported by RTEMS. */ /**@{*/ @@ -123,7 +123,7 @@ void _ISR_Handler_initialization ( void ); * critical code when a point is reached at which interrupts can * be temporarily enabled. Deciding where to flash interrupts * in a long critical section is often difficult and the point - * must be selected with care to insure that the critical section + * must be selected with care to ensure that the critical section * properly protects itself. */ #define _ISR_Flash( _level ) \ @@ -158,7 +158,7 @@ void _ISR_Handler_initialization ( void ); * interrupt service routine is invoked. After the application's * interrupt service routine returns control to this routine, it * will determine if a thread dispatch is necessary. If so, it will - * insure that the necessary thread scheduling operations are + * ensure that the necessary thread scheduling operations are * performed when the outermost interrupt service routine exits. * * @note Implemented in assembly language. diff --git a/cpukit/score/include/rtems/score/mpci.h b/cpukit/score/include/rtems/score/mpci.h index cf82d2f3eb..d6fc3aa0c1 100644 --- a/cpukit/score/include/rtems/score/mpci.h +++ b/cpukit/score/include/rtems/score/mpci.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,8 +22,12 @@ /** * @defgroup ScoreMPCI MPCI Handler * - * This group contains functionality which XXX - */ + * The MPCI Handler encapsulates functionality which is related to the + * generation, receipt, and processing of remote operations in a + * multiprocessor system. This handler contains the message passing + * support for making remote service calls as well as the server thread + * which processes requests from remote nodes. +*/ /**@{*/ #ifdef __cplusplus @@ -38,7 +42,7 @@ extern "C" { #include <rtems/score/watchdog.h> #include <rtems/score/coresem.h> -/* +/** * The following constants define the stack size requirements for * the system threads. */ @@ -48,12 +52,12 @@ extern "C" { _CPU_Table.extra_mpci_receive_server_stack \ ) -/* +/** * The following defines the node number used when a broadcast is desired. */ #define MPCI_ALL_NODES 0 -/* +/** * For packets associated with requests that don't already have a timeout, * use the one specified by this MPCI driver. The value specified by * the MPCI driver sets an upper limit on how long a remote request @@ -61,71 +65,83 @@ extern "C" { */ #define MPCI_DEFAULT_TIMEOUT 0xFFFFFFFF -/* - * The following records define the Multiprocessor Communications - * Interface (MPCI) Table. This table defines the user-provided - * MPCI which is a required part of a multiprocessor system. - * - * For non-blocking local operations that become remote operations, - * we need a timeout. This is a per-driver timeout: default_timeout - */ - /** * This type is returned by all user provided MPCI routines. */ typedef void MPCI_Entry; /** - * This type is XXX + * This type defines the prototype for the initization entry point + * in an Multiprocessor Communications Interface. */ typedef MPCI_Entry ( *MPCI_initialization_entry )( void ); /** - * This type is XXX + * This type defines the prototype for the get packet entry point + * in an Multiprocessor Communications Interface. The single + * parameter will point to the packet allocated. */ typedef MPCI_Entry ( *MPCI_get_packet_entry )( - MP_packet_Prefix ** - ); + MP_packet_Prefix ** + ); /** - * This type is XXX + * This type defines the prototype for the return packet entry point + * in an Multiprocessor Communications Interface. The single + * parameter will point to a packet previously allocated by the + * get packet MPCI entry. */ typedef MPCI_Entry ( *MPCI_return_packet_entry )( - MP_packet_Prefix * - ); + MP_packet_Prefix * + ); /** - * This type is XXX + * This type defines the prototype for send get packet entry point + * in an Multiprocessor Communications Interface. The single + * parameter will point to a packet previously allocated by the + * get packet entry point that has been filled in by the caller. */ typedef MPCI_Entry ( *MPCI_send_entry )( - uint32_t , - MP_packet_Prefix * - ); + uint32_t, + MP_packet_Prefix * + ); /** - * This type is XXX + * This type defines the prototype for the receive packet entry point + * in an Multiprocessor Communications Interface. The single + * parameter will point to a packet allocated and filled in by the + * receive packet handler. The caller will block until a packet is + * received. */ typedef MPCI_Entry ( *MPCI_receive_entry )( - MP_packet_Prefix ** - ); + MP_packet_Prefix ** + ); /** - * This type is XXX + * This type defines the Multiprocessor Communications + * Interface (MPCI) Table. This table defines the user-provided + * MPCI which is a required part of a multiprocessor system. + * + * For non-blocking local operations that become remote operations, + * we need a timeout. This is a per-driver timeout: default_timeout */ typedef struct { - /** timeout for MPCI operations in ticks */ + /** This fields contains the timeout for MPCI operations in ticks. */ uint32_t default_timeout; - /** XXX */ + /** This field contains the maximum size of a packet supported by this + * MPCI layer. This size places a limit on the size of a message + * which can be transmitted over this interface. + **/ uint32_t maximum_packet_size; - /** XXX */ + /** This field points to the MPCI initialization entry point. */ MPCI_initialization_entry initialization; - /** XXX */ + /** This field points to the MPCI get packet entry point. */ MPCI_get_packet_entry get_packet; - /** XXX */ + /** This field points to the MPCI return packet entry point. */ MPCI_return_packet_entry return_packet; - /** XXX */ + /** This field points to the MPCI send packet entry point. */ MPCI_send_entry send_packet; - /** XXX */ + /** This field points to the MPCI receive packet entry point. */ MPCI_receive_entry receive_packet; } MPCI_Control; @@ -148,13 +164,17 @@ typedef enum { * remote event operations. */ typedef struct { - /** XXX */ + /** This field is the general header for all packets. */ MP_packet_Prefix Prefix; - /** XXX */ + /** This value specifies the operation. */ MPCI_Internal_Remote_operations operation; - /** XXX */ + /** This is the maximum number of nodes in the system. It must agree + * on all nodes. + */ uint32_t maximum_nodes; - /** XXX */ + /** This field is the maximum number of concurrently existent + * globally offered objects. + */ uint32_t maximum_global_objects; } MPCI_Internal_packet; @@ -189,6 +209,12 @@ SCORE_EXTERN MPCI_Packet_processor /** * This routine performs the initialization necessary for this handler. + * + * @param[in] users_mpci_table is a pointer to the application configured + * MPCI Table. This table contains pointers to the MPCI Layers + * entry points. + * @param[in] timeout_status is the value which should be returned to + * blocking threads when they timeout on a remote operation. */ void _MPCI_Handler_initialization( MPCI_Control *users_mpci_table, @@ -209,6 +235,11 @@ void _MPCI_Initialization ( void ); /** * This routine registers the MPCI packet processor for the * designated object class. + * + * @param[in] the_class is the class indicator for packets which will + * be processed by @a the_packet_processor method. + * @param[in] the_packet_processor is a pointer to a method which is + * invoked when packets with @a the_class are received. */ void _MPCI_Register_packet_processor( MP_packet_Classes the_class, @@ -219,12 +250,18 @@ 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 + * filled in by the caller and used to perform a subsequent + * remote operation. */ MP_packet_Prefix *_MPCI_Get_packet ( void ); /** - * This routine returns a packet by invoking the user provided + * This routine deallocates a packet by invoking the user provided * MPCI return packet callout. + * + * @param[in] the_packet is the MP packet to deallocate. */ void _MPCI_Return_packet ( MP_packet_Prefix *the_packet @@ -233,6 +270,9 @@ void _MPCI_Return_packet ( /** * This routine sends a process packet by invoking the user provided * MPCI send callout. + * + * @param[in] destination is the node which should receive this packet. + * @param[in] the_packet is the packet to be sent. */ void _MPCI_Send_process_packet ( uint32_t destination, @@ -242,8 +282,17 @@ void _MPCI_Send_process_packet ( /** * This routine sends a request packet by invoking the user provided * MPCI send callout. + * + * @param[in] destination is the node which should receive this packet. + * @param[in] the_packet is the packet to be sent. + * @param[in] extra_state is the extra thread state bits which should be + * set in addition to the remote operation pending state. It + * may indicate the caller is blocking on a message queue + * operation. + * + * @return This method returns the operation status from the remote node. */ -uint32_t _MPCI_Send_request_packet ( +uint32_t _MPCI_Send_request_packet ( uint32_t destination, MP_packet_Prefix *the_packet, States_Control extra_state @@ -252,6 +301,9 @@ uint32_t _MPCI_Send_request_packet ( /** * This routine sends a response packet by invoking the user provided * MPCI send callout. + * + * @param[in] destination is the node which should receive this packet. + * @param[in] the_packet is the packet to be sent. */ void _MPCI_Send_response_packet ( uint32_t destination, @@ -261,12 +313,20 @@ void _MPCI_Send_response_packet ( /** * This routine receives a packet by invoking the user provided * MPCI receive callout. + * + * @return This method returns the packet received. */ MP_packet_Prefix *_MPCI_Receive_packet ( void ); /** - * This routine obtains a packet by invoking the user provided - * MPCI get packet callout. + * This routine is responsible for passing @a the_packet to the thread + * waiting on the remote operation to complete. The unblocked thread is + * responsible for eventually freeing @a the_packet. + * + * @param[in] the_packet is the response packet to be processed. + * + * @return 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 ( MP_packet_Prefix *the_packet @@ -274,6 +334,8 @@ Thread_Control *_MPCI_Process_response ( /** * This is the server thread which receives and processes all MCPI packets. + * + * @param[in] ignored is the thread argument. It is not used. */ Thread _MPCI_Receive_server( uint32_t ignored @@ -287,12 +349,14 @@ void _MPCI_Announce ( void ); /** * This routine performs a remote procedure call so that a * process operation can be performed on another node. + * + * @param[in] operation is the remote operation to perform. */ void _MPCI_Internal_packets_Send_process_packet ( MPCI_Internal_Remote_operations operation ); -/* +/** * _MPCI_Internal_packets_Send_request_packet * * This routine performs a remote procedure call so that a @@ -302,7 +366,7 @@ void _MPCI_Internal_packets_Send_process_packet ( * packets to be sent by this manager. */ -/* +/** * _MPCI_Internal_packets_Send_response_packet * * This routine performs a remote procedure call so that a @@ -320,7 +384,7 @@ void _MPCI_Internal_packets_Process_packet ( MP_packet_Prefix *the_packet_prefix ); -/* +/** * _MPCI_Internal_packets_Send_object_was_deleted * * This routine is invoked indirectly by the thread queue @@ -331,7 +395,7 @@ void _MPCI_Internal_packets_Process_packet ( * deleted by this manager. */ -/* +/** * _MPCI_Internal_packets_Send_extract_proxy * * This routine is invoked when a task is deleted and it diff --git a/cpukit/score/include/rtems/score/mppkt.h b/cpukit/score/include/rtems/score/mppkt.h index 1867ae45a9..b194610500 100644 --- a/cpukit/score/include/rtems/score/mppkt.h +++ b/cpukit/score/include/rtems/score/mppkt.h @@ -9,7 +9,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -25,7 +25,9 @@ /** * @defgroup ScoreMPPacket MP Packet Handler * - * This group contains functionality which XXX + * This handler encapsulates the primary definition of MPCI packets. This + * handler defines the part of the packet that is common to all remote + * operations. */ /**@{*/ @@ -56,12 +58,12 @@ typedef enum { } MP_packet_Classes; /** - * XXX + * This constant defines the first entry in the MP_packet_Classes enumeration. */ #define MP_PACKET_CLASSES_FIRST MP_PACKET_MPCI_INTERNAL /** - * XXX + * This constant defines the last entry in the MP_packet_Classes enumeration. */ #define MP_PACKET_CLASSES_LAST MP_PACKET_SIGNAL @@ -74,21 +76,21 @@ typedef enum { * alignment rule encountered yet. */ typedef struct { - /** XXX */ + /** This field indicates the API class of the operation being performed. */ MP_packet_Classes the_class; - /** XXX */ + /** This field is the id of the object to be acted upon. */ Objects_Id id; - /** XXX */ + /** This field is the ID of the originating thread. */ Objects_Id source_tid; - /** XXX */ + /** This field is the priority of the originating thread. */ Priority_Control source_priority; - /** XXX */ + /** This field is where the status of the operation will be returned. */ uint32_t return_code; - /** XXX */ + /** This field is the length of the data following the prefix. */ uint32_t length; - /** XXX */ + /** This field is the length of the data which required network conversion. */ uint32_t to_convert; - /** XXX */ + /** This field is the requested timeout for this operation. */ Watchdog_Interval timeout; } MP_packet_Prefix; diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h index 145b003147..661f53eb11 100644 --- a/cpukit/score/include/rtems/score/object.h +++ b/cpukit/score/include/rtems/score/object.h @@ -8,7 +8,7 @@ * can be used to initialize and manipulate all objects which have * ids. * - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -28,25 +28,22 @@ extern "C" { #include <rtems/score/chain.h> #include <rtems/score/isr.h> -/* +/** * The following type defines the control block used to manage * object names. */ - typedef void * Objects_Name; -/* +/** * Space for object names is allocated in multiples of this. * * NOTE: Must be a power of 2. Matches the name manipulation routines. */ - #define OBJECTS_NAME_ALIGNMENT sizeof( uint32_t ) -/* +/** * Functions which compare names are prototyped like this. */ - typedef boolean (*Objects_Name_comparators)( void * /* name_1 */, void * /* name_2 */, @@ -54,7 +51,7 @@ typedef boolean (*Objects_Name_comparators)( ); #if defined(RTEMS_USE_16_BIT_OBJECT) -/* +/** * The following type defines the control block used to manage * object IDs. The format is as follows (0=LSB): * @@ -62,8 +59,12 @@ typedef boolean (*Objects_Name_comparators)( * Bits 8 .. 10 = API (up to 7 API classes) * Bits 11 .. 15 = class (up to 31 object types per API) */ - typedef uint16_t Objects_Id; + +/** + * This type is used to store the maximum number of allowed objects + * of each type. + */ typedef uint8_t Objects_Maximum; #define OBJECTS_INDEX_START_BIT 0 @@ -81,8 +82,11 @@ typedef uint8_t Objects_Maximum; #define OBJECTS_UNLIMITED_OBJECTS 0x8000 +#define OBJECTS_ID_INITIAL_INDEX (0) +#define OBJECTS_ID_FINAL_INDEX (0xff) + #else -/* +/** * The following type defines the control block used to manage * object IDs. The format is as follows (0=LSB): * @@ -91,39 +95,103 @@ typedef uint8_t Objects_Maximum; * Bits 24 .. 26 = API (up to 7 API classes) * Bits 27 .. 31 = class (up to 31 object types per API) */ - typedef uint32_t Objects_Id; + +/** + * This type is used to store the maximum number of allowed objects + * of each type. + */ typedef uint16_t Objects_Maximum; +/** + * This is the bit position of the starting bit of the index portion of + * the object Id. + */ #define OBJECTS_INDEX_START_BIT 0 + + +/** + * This is the bit position of the starting bit of the node portion of + * the object Id. + */ #define OBJECTS_NODE_START_BIT 16 + +/** + * This is the bit position of the starting bit of the API portion of + * the object Id. + */ #define OBJECTS_API_START_BIT 24 + +/** + * This is the bit position of the starting bit of the class portion of + * the object Id. + */ #define OBJECTS_CLASS_START_BIT 27 +/** + * This mask is used to extract the index portion of an object Id. + */ #define OBJECTS_INDEX_MASK (Objects_Id)0x0000ffff + +/** + * This mask is used to extract the node portion of an object Id. + */ #define OBJECTS_NODE_MASK (Objects_Id)0x00ff0000 + +/** + * This mask is used to extract the API portion of an object Id. + */ #define OBJECTS_API_MASK (Objects_Id)0x07000000 + +/** + * This mask is used to extract the class portion of an object Id. + */ #define OBJECTS_CLASS_MASK (Objects_Id)0xf8000000 +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the index portion of an object Id. + */ #define OBJECTS_INDEX_VALID_BITS (Objects_Id)0x0000ffff + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the node portion of an object Id. + */ #define OBJECTS_NODE_VALID_BITS (Objects_Id)0x000000ff + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the API portion of an object Id. + */ #define OBJECTS_API_VALID_BITS (Objects_Id)0x00000007 + +/** + * This mask represents the bits that is used to ensure no extra bits + * are set after shifting to extract the class portion of an object Id. + */ #define OBJECTS_CLASS_VALID_BITS (Objects_Id)0x0000001f -/* +/** * Mask to enable unlimited objects. This is used in the configuration * table when specifying the number of configured objects. */ #define OBJECTS_UNLIMITED_OBJECTS 0x80000000 +/** + * This is the lowest value for the index portion of an object Id. + */ +#define OBJECTS_ID_INITIAL_INDEX (0) + +/** + * This is the highest value for the index portion of an object Id. + */ +#define OBJECTS_ID_FINAL_INDEX (0xff) #endif -/* +/** * This enumerated type is used in the class field of the object ID. */ - -#define OBJECTS_NO_CLASS 0 - typedef enum { OBJECTS_NO_API = 0, OBJECTS_INTERNAL_API = 1, @@ -132,16 +200,26 @@ typedef enum { OBJECTS_ITRON_API = 4 } Objects_APIs; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_APIS_LAST OBJECTS_ITRON_API +/** + * This enumerated type is used in the class field of the object ID + * for RTEMS internal object classes. + */ typedef enum { OBJECTS_INTERNAL_NO_CLASS = 0, OBJECTS_INTERNAL_THREADS = 1, OBJECTS_INTERNAL_MUTEXES = 2 } Objects_Internal_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_INTERNAL_CLASSES_LAST OBJECTS_INTERNAL_MUTEXES +/** + * This enumerated type is used in the class field of the object ID + * for the RTEMS Classic API. + */ typedef enum { OBJECTS_CLASSIC_NO_CLASS = 0, OBJECTS_RTEMS_TASKS = 1, @@ -155,8 +233,13 @@ typedef enum { OBJECTS_RTEMS_EXTENSIONS = 9 } Objects_Classic_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_RTEMS_CLASSES_LAST OBJECTS_RTEMS_EXTENSIONS +/** + * This enumerated type is used in the class field of the object ID + * for the POSIX API. + */ typedef enum { OBJECTS_POSIX_NO_CLASS = 0, OBJECTS_POSIX_THREADS = 1, @@ -169,8 +252,13 @@ typedef enum { OBJECTS_POSIX_CONDITION_VARIABLES = 8 } Objects_POSIX_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_POSIX_CLASSES_LAST OBJECTS_POSIX_CONDITION_VARIABLES +/** + * This enumerated type is used in the class field of the object ID + * for the ITRON API. + */ typedef enum { OBJECTS_ITRON_NO_CLASS = 0, OBJECTS_ITRON_TASKS = 1, @@ -183,161 +271,186 @@ typedef enum { OBJECTS_ITRON_FIXED_MEMORY_POOLS = 8 } Objects_ITRON_API; +/** This macro is used to generically specify the last API index. */ #define OBJECTS_ITRON_CLASSES_LAST OBJECTS_ITRON_FIXED_MEMORY_POOLS -/* +/** * This enumerated type lists the locations which may be returned * by _Objects_Get. These codes indicate the success of locating * an object with the specified ID. */ - typedef enum { OBJECTS_LOCAL = 0, /* object is local */ OBJECTS_REMOTE = 1, /* object is remote */ OBJECTS_ERROR = 2 /* id was invalid */ } Objects_Locations; -/* +/** * The following type defines the callout used when a local task * is extracted from a remote thread queue (i.e. it's proxy must * extracted from the remote queue). */ - typedef void ( *Objects_Thread_queue_Extract_callout )( void * ); -/* +/** * The following defines the Object Control Block used to manage * each object local to this node. */ - typedef struct { + /** This is the chain node portion of an object. */ Chain_Node Node; + /** This is the object's ID. */ Objects_Id id; + /** This is the object's name. */ Objects_Name name; } Objects_Control; -/* +/** * The following defines the structure for the information used to * manage each class of objects. */ - typedef struct { - Objects_APIs the_api; /* API of this object */ - uint16_t the_class; /* class of this object */ - Objects_Id minimum_id; /* minimum valid id of this type */ - Objects_Id maximum_id; /* maximum valid id of this type */ - Objects_Maximum maximum; /* maximum number of objects */ - boolean auto_extend; /* TRUE if unlimited objects */ - uint32_t allocation_size; /* number of objects in a block */ - uint32_t size; /* size of the objects */ + /** This field indicates the API of this object class. */ + Objects_APIs the_api; + /** This is the class of this object set. */ + uint16_t the_class; + /** This is the minimum valid id of this object class. */ + Objects_Id minimum_id; + /** This is the maximum valid id of this object class. */ + Objects_Id maximum_id; + /** This is the maximum number of objects in this class. */ + Objects_Maximum maximum; + /** This is the TRUE if unlimited objects in this class. */ + boolean auto_extend; + /** This is the number of objects in a block. */ + uint32_t allocation_size; + /** This is the size in bytes of each object instance. */ + uint32_t size; + /** This points to the table of local objects. */ Objects_Control **local_table; + /** This points to the table of local object names. */ Objects_Name *name_table; - Chain_Control Inactive; /* chain of inactive ctl blocks */ - Objects_Maximum inactive; /* number of objects on the InActive list */ - uint32_t *inactive_per_block; /* used to release a block */ - void **object_blocks; /* the object memory to remove */ - boolean is_string; /* TRUE if names are strings */ - uint16_t name_length; /* maximum length of names */ + /** This is the chain of inactive control blocks. */ + Chain_Control Inactive; + /** This is the number of objects on the Inactive list. */ + Objects_Maximum inactive; + /** This is the number of inactive objects per block. */ + uint32_t *inactive_per_block; + /** This is a table to the chain of inactive object memory blocks. */ + void **object_blocks; + /** This is the TRUE if names are strings. */ + boolean is_string; + /** This is the maximum length of names. */ + uint16_t name_length; + /** This is this object class' method called when extracting a thread. */ Objects_Thread_queue_Extract_callout extract; #if defined(RTEMS_MULTIPROCESSING) - Chain_Control *global_table; /* pointer to global table */ + /** This is this object class' pointer to the global name table */ + Chain_Control *global_table; #endif } Objects_Information; -/* - * The following defines the data storage which contains the - * node number of the local node. +/** + * The following is referenced to the node number of the local node. */ - #if defined(RTEMS_MULTIPROCESSING) SCORE_EXTERN uint16_t _Objects_Local_node; -SCORE_EXTERN uint16_t _Objects_Maximum_nodes; #else #define _Objects_Local_node 1 +#endif + +/** + * The following is referenced to the number of nodes in the system. + */ +#if defined(RTEMS_MULTIPROCESSING) +SCORE_EXTERN uint16_t _Objects_Maximum_nodes; +#else #define _Objects_Maximum_nodes 1 #endif -/* +/** * The following is the list of information blocks per API for each object * class. From the ID, we can go to one of these information blocks, * and obtain a pointer to the appropriate object control block. */ - SCORE_EXTERN Objects_Information **_Objects_Information_table[OBJECTS_APIS_LAST + 1]; -/* +/** * The following defines the constant which may be used * with _Objects_Get to manipulate the calling task. - * */ - #define OBJECTS_ID_OF_SELF ((Objects_Id) 0) -/* - * The following define the constants which may be used in name searches. +/** + * The following constant is used to specify that a name to ID search + * should search through all nodes. */ - #define OBJECTS_SEARCH_ALL_NODES 0 + +/** + * The following constant is used to specify that a name to ID search + * should search through all nodes except the current node. + */ #define OBJECTS_SEARCH_OTHER_NODES 0x7FFFFFFE -#define OBJECTS_SEARCH_LOCAL_NODE 0x7FFFFFFF -#define OBJECTS_WHO_AM_I 0 -/* - * Parameters and return id's for _Objects_Get_next +/** + * The following constant is used to specify that a name to ID search + * should search only on this node. */ +#define OBJECTS_SEARCH_LOCAL_NODE 0x7FFFFFFF -#define OBJECTS_ID_INITIAL_INDEX (0) -#define OBJECTS_ID_FINAL_INDEX (0xffff) +/** + * The following constant is used to specify that a name to ID search + * is being asked for the ID of the currently executing task. + */ +#define OBJECTS_WHO_AM_I 0 +/** + * This macros calculates the lowest ID for the specified api, class, + * and node. + */ #define OBJECTS_ID_INITIAL(_api, _class, _node) \ _Objects_Build_id( (_api), (_class), (_node), OBJECTS_ID_INITIAL_INDEX ) + +/** + * This macro specifies the highest object ID value + */ #define OBJECTS_ID_FINAL ((Objects_Id)~0) -/* - * _Objects_Handler_initialization - * - * DESCRIPTION: - * +/** * This function performs the initialization necessary for this handler. * + * @param[in] node indicates the identifying number of this node. + * @param[in] maximum_nodes is the maximum number of nodes in this system. + * @param[in] maximum_global_objects is maximum number of global objects + * concurrently offered in the system. */ - void _Objects_Handler_initialization( uint32_t node, uint32_t maximum_nodes, uint32_t maximum_global_objects ); -/* - * _Objects_Extend_information - * - * DESCRIPTION: - * +/** * This function extends an object class information record. + * + * @param[in] information points to an object class information block. */ - void _Objects_Extend_information( Objects_Information *information ); -/* - * _Objects_Shrink_information - * - * DESCRIPTION: - * +/** * This function shrink an object class information record. + * + * @param[in] information points to an object class information block. */ - void _Objects_Shrink_information( Objects_Information *information ); -/* - * _Objects_Initialize_information - * - * DESCRIPTION: - * +/** * This function initializes an object class information record. * SUPPORTS_GLOBAL is TRUE if the object class supports global * objects, and FALSE otherwise. Maximum indicates the number @@ -345,8 +458,17 @@ void _Objects_Shrink_information( * in bytes of each control block for this object class. The * name length and string designator are also set. In addition, * the class may be a task, therefore this information is also included. + * + * @param[in] information points to an object class information block. + * @param[in] the_api indicates the API associated with this information block. + * @param[in] the_class indicates the class of object being managed + * by this information block. It is specific to @a the_api. + * @param[in] maximum is the maximum number of instances of this object + * class which may be concurrently active. + * @param[in] size is the size of the data structure for this class. + * @param[in] is_string is TRUE if this object uses string style names. + * @param[in] maximum_name_length is the maximum length of object names. */ - void _Objects_Initialize_information ( Objects_Information *information, Objects_APIs the_api, @@ -362,125 +484,108 @@ void _Objects_Initialize_information ( #endif ); -/*PAGE - * - * _Objects_Allocate - * - * DESCRIPTION: - * +/** * This function allocates a object control block from * the inactive chain of free object control blocks. + * + * @param[in] information points to an object class information block. */ - Objects_Control *_Objects_Allocate( Objects_Information *information ); -/* - * _Objects_Allocate_by_index - * - * DESCRIPTION: - * +/** * This function allocates the object control block * specified by the index from the inactive chain of * free object control blocks. + * + * @param[in] information points to an object class information block. + * @param[in] index is the index of the object to allocate. + * @param[in] sizeof_control is the size of the object control block. */ - Objects_Control *_Objects_Allocate_by_index( Objects_Information *information, uint16_t index, uint16_t sizeof_control ); -/*PAGE - * - * _Objects_Free - * - * DESCRIPTION: +/** * * This function frees a object control block to the * inactive chain of free object control blocks. + * + * @param[in] information points to an object class information block. + * @param[in] the_object points to the object to deallocate. */ - void _Objects_Free( Objects_Information *information, Objects_Control *the_object ); -/* - * _Objects_Clear_name - * - * DESCRIPTION: - * +/** * This method zeroes out the name. + * + * @param[in] name points to the name to be zeroed out. + * @param[in] length is the length of the object name field. */ - void _Objects_Clear_name( void *name, uint16_t length ); -/* - * _Objects_Copy_name_string - * - * DESCRIPTION: - * +/** * This method copies a string style object name from source to destination. + * + * @param[in] source is the source name to copy. + * @param[in] destination is the destination of the copy. + * @param[in] length is the number of bytes to copy. */ - void _Objects_Copy_name_string( void *source, void *destination, uint16_t length ); -/* - * _Objects_Copy_name_raw - * - * DESCRIPTION: - * +/** * This method copies a raw style object name from source to destination. + * + * @param[in] source is the source name to copy. + * @param[in] destination is the destination of the copy. + * @param[in] length is the number of bytes to copy. */ - void _Objects_Copy_name_raw( void *source, void *destination, uint16_t length ); -/* - * _Objects_Compare_name_string - * - * DESCRIPTION: - * +/** * This method compares two string style object names. + * + * @param[in] name_1 is the left hand name to compare. + * @param[in] name_2 is the right hand name to compare. + * @param[in] length is the length of the names to compare. */ - boolean _Objects_Compare_name_string( void *name_1, void *name_2, uint16_t length ); -/* - * _Objects_Compare_name_raw - * - * DESCRIPTION: - * +/** * This method compares two raw style object names. + * + * @param[in] name_1 is the left hand name to compare. + * @param[in] name_2 is the right hand name to compare. + * @param[in] length is the length of the names to compare. */ - boolean _Objects_Compare_name_raw( void *name_1, void *name_2, uint16_t length ); -/* - * _Objects_Name_to_id - * - * DESCRIPTION: - * +/** * This function implements the common portion of the object * identification directives. This directive returns the object * id associated with name. If more than one object of this class @@ -489,9 +594,7 @@ boolean _Objects_Compare_name_raw( * id of the object named name. If the object class supports global * objects, then the search can be limited to a particular node * or allowed to encompass all nodes. - * */ - typedef enum { OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL, OBJECTS_INVALID_NAME, @@ -500,9 +603,30 @@ typedef enum { OBJECTS_INVALID_NODE } Objects_Name_or_id_lookup_errors; +/** This macro defines the first entry in the + * @ref Objects_Name_or_id_lookup_errors enumerated list. + */ #define OBJECTS_NAME_ERRORS_FIRST OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL + +/** This macro defines the last entry in the + * @ref Objects_Name_or_id_lookup_errors enumerated list. + */ #define OBJECTS_NAME_ERRORS_LAST OBJECTS_INVALID_NODE +/** + * This method converts an object name to an Id. It performs a look up + * using the object information block for this object class. + * + * @param[in] information points to an object class information block. + * @param[in] name is the name of the object to find. + * @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 + * @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. + */ Objects_Name_or_id_lookup_errors _Objects_Name_to_id( Objects_Information *information, Objects_Name name, @@ -510,30 +634,27 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id( Objects_Id *id ); -/* - * _Objects_Id_to_Name - * - * DESCRIPTION: - * +/** * This function implements the common portion of the object Id * to name directives. This function returns the name * associated with object id. * - * NOTE: + * @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 + * @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. * - * This function currently does not support string names. + * @note This function currently does not support string names. */ - Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( Objects_Id id, Objects_Name *name ); -/* - * _Objects_Get - * - * DESCRIPTION: - * +/** * 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 @@ -543,19 +664,51 @@ Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( * is undefined. Otherwise, location is set to OBJECTS_ERROR * and the_object is undefined. * - * NOTE: _Objects_Get returns with dispatching disabled for - * local and remote objects. - * _Objects_Get_isr_disable returns with dispatching - * disabled for remote objects and interrupts for local - * objects. + * @param[in] information points to an object class information block. + * @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 + * @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. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. */ - Objects_Control *_Objects_Get ( Objects_Information *information, Objects_Id id, Objects_Locations *location ); +/** + * 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 + * is set to OBJECTS_LOCAL. If the object class supports global + * objects and the object id is global and resides on a remote + * node, then location is set to OBJECTS_REMOTE, and the_object + * is undefined. Otherwise, location is set to OBJECTS_ERROR + * and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @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. + * @param[in] level is the interrupt level being turned. + * + * @return 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. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_isr_disable( Objects_Information *information, Objects_Id id, @@ -563,27 +716,75 @@ Objects_Control *_Objects_Get_isr_disable( ISR_Level *level ); +/** + * This function maps object index to object control blocks which must. + * be local. The parameter the_object control pointer which maps to id + * and location is set to OBJECTS_LOCAL. Otherwise, location is set to + OBJECTS_ERROR and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @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 a pointer to the object associated with ID. + * + * @return 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. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_by_index ( Objects_Information *information, Objects_Id id, Objects_Locations *location ); +/** + * 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 + * is set to OBJECTS_LOCAL. If the object class supports global + * objects and the object id is global and resides on a remote + * node, then location is set to OBJECTS_REMOTE, and the_object + * is undefined. Otherwise, location is set to OBJECTS_ERROR + * and the_object is undefined. + * + * @param[in] information points to an object class information block. + * @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 + * @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. + * + * @note _Objects_Get returns with dispatching disabled for + * local and remote objects. _Objects_Get_isr_disable returns with + * dispatching disabled for remote objects and interrupts for local + * objects. + */ Objects_Control *_Objects_Get_no_protection( Objects_Information *information, Objects_Id id, Objects_Locations *location ); -/* - * _Objects_Get_next - * - * DESCRIPTION: +/** + * Like @ref _Objects_Get, but is used to find "next" open object. * - * Like _Objects_Get, but is used to find "next" open object. + * @param[in] information points to an object class information block. + * @param[in] id is the Id of the object whose name we are locating. + * @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 + * NULL on error. */ - Objects_Control *_Objects_Get_next( Objects_Information *information, Objects_Id id, diff --git a/cpukit/score/include/rtems/score/objectmp.h b/cpukit/score/include/rtems/score/objectmp.h index 7f9e25b707..6275304012 100644 --- a/cpukit/score/include/rtems/score/objectmp.h +++ b/cpukit/score/include/rtems/score/objectmp.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,9 @@ /** * @defgroup ScoreObjectMP Object Handler Multiprocessing Support * - * This group contains functionality which XXX + * This handler encapsulates functionality which is used to manage + * objects which have been declared to be globally visible. This handler + * knows objects from all of the nodes in the system. */ /**@{*/ @@ -30,20 +32,29 @@ extern "C" { #endif -/* +/** * This defines the Global Object Control Block used to manage - * objects resident on other nodes. + * objects resident on other nodes. It is derived from Object. */ typedef struct { + /** This is an object control structure. */ Objects_Control Object; - uint32_t name; /* XXX broken but works */ - /* XXX If any API is MP with variable length names .. BOOM!!!! */ + /** This is the name of the object. Using an unsigned thirty two + * bit value is broken but works. If any API is MP with variable + * length names .. BOOM!!!! + */ + uint32_t name; } Objects_MP_Control; /** @brief Objects MP Handler initialization * * This routine intializes the inactive global object chain * based on the maximum number of global objects configured. + * + * @param[in] node is this node's number. + * @param[in] maximum_nodes is the maximum number of nodes in the system. + * @param[in] maximum_global_objects is the maximum number of concurrently + * created global objects. */ void _Objects_MP_Handler_initialization ( uint32_t node, @@ -55,12 +66,20 @@ void _Objects_MP_Handler_initialization ( * * This routine place the specified global object in the * specified information table. + * + * @param[in] information points to the object information table for this + * object class. + * @param[in] the_global_object points to the object being opened. + * @param[in] the_name is the name of the object being opened. + * @param[in] the_id is the Id of the object being opened. + * + * @todo This method only works for object types with 4 byte object names. + * It does not support variable length object names. */ - void _Objects_MP_Open ( Objects_Information *information, Objects_MP_Control *the_global_object, - uint32_t the_name, /* XXX -- wrong for variable */ + uint32_t the_name, Objects_Id the_id ); @@ -70,10 +89,20 @@ void _Objects_MP_Open ( * and places it in the specified information table. If the * allocation fails, then is_fatal_error determines the * error processing actions taken. + * + * @param[in] information points to the object information table for this + * object class. + * @param[in] the_name is the name of the object being opened. + * @param[in] the_id is the Id of the object being opened. + * @param[in] is_fatal_error is TRUE if not being able to allocate the + * object is considered a fatal error. + * + * @todo This method only works for object types with 4 byte object names. + * It does not support variable length object names. */ boolean _Objects_MP_Allocate_and_open ( Objects_Information *information, - uint32_t the_name, /* XXX -- wrong for variable length */ + uint32_t the_name, Objects_Id the_id, boolean is_fatal_error ); @@ -93,6 +122,16 @@ void _Objects_MP_Close ( * This routine looks for the object with the_name in the global * object tables indicated by information. It returns the ID of the * object with that name if one is found. + * + * @param[in] information points to the object information table for this + * object class. + * @param[in] the_name is the name of the object being searched for. + * @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 + * @ref Objects_Name_or_id_lookup_errors. If successful, @a the_id + * will contain the Id of the object. */ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( Objects_Information *information, @@ -108,6 +147,16 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( * is found, then location is set to objects_remote, otherwise * location is set to objects_error. In both cases, the_object * is undefined. + * + * @param[in] information points to the object information table for this + * object class. + * @param[in] the_id is the Id of the object being opened. + * @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 + * of the object or error. On success, @a the_object will be + * filled in. */ void _Objects_MP_Is_remote ( Objects_Information *information, @@ -116,11 +165,15 @@ void _Objects_MP_Is_remote ( Objects_Control **the_object ); -/* +/** + * This is the maximum number of global objects configured. + */ +SCORE_EXTERN uint32_t _Objects_MP_Maximum_global_objects; + +/** * The following chain header is used to manage the set of * inactive global object control blocks. */ -SCORE_EXTERN uint32_t _Objects_MP_Maximum_global_objects; SCORE_EXTERN Chain_Control _Objects_MP_Inactive_global_objects; #ifndef __RTEMS_APPLICATION__ diff --git a/cpukit/score/include/rtems/score/priority.h b/cpukit/score/include/rtems/score/priority.h index 58b70add1b..bfe43e282d 100644 --- a/cpukit/score/include/rtems/score/priority.h +++ b/cpukit/score/include/rtems/score/priority.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,16 @@ /** * @defgroup ScorePriority Priority Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality which is used to manage + * thread priorities. At the SuperCore level 256 priority levels + * are supported with lower numbers representing logically more important + * threads. The priority level 0 is reserved for internal RTEMS use. + * Typically it is assigned to threads which defer internal RTEMS + * actions from an interrupt to thread level to improve interrupt response. + * Priority level 255 is assigned to the IDLE thread and really should not + * be used by application threads. The default IDLE thread implementation + * is an infinite "branch to self" loop which never yields to other threads + * at the same priority. */ /**@{*/ @@ -31,43 +40,48 @@ extern "C" { #endif -/* +/** * The following type defines the control block used to manage * thread priorities. * * @note Priority 0 is reserved for internal threads only. */ - typedef uint32_t Priority_Control; -#define PRIORITY_MINIMUM 0 /* highest thread priority */ -#define PRIORITY_MAXIMUM 255 /* lowest thread priority */ +/** This defines the highest (most important) thread priority. */ +#define PRIORITY_MINIMUM 0 +/** This defines the lowest (least important) thread priority. */ +#define PRIORITY_MAXIMUM 255 -/* +/** * The following record defines the information associated with * each thread to manage its interaction with the priority bit maps. */ - typedef struct { - Priority_Bit_map_control *minor; /* addr of minor bit map slot */ - Priority_Bit_map_control ready_major; /* priority bit map ready mask */ - Priority_Bit_map_control ready_minor; /* priority bit map ready mask */ - Priority_Bit_map_control block_major; /* priority bit map block mask */ - Priority_Bit_map_control block_minor; /* priority bit map block mask */ + /** This is the address of minor bit map slot. */ + Priority_Bit_map_control *minor; + /** This is the priority bit map ready mask. */ + Priority_Bit_map_control ready_major; + /** This is the priority bit map ready mask. */ + Priority_Bit_map_control ready_minor; + /** This is the priority bit map block mask. */ + Priority_Bit_map_control block_major; + /** This is the priority bit map block mask. */ + Priority_Bit_map_control block_minor; } Priority_Information; -/* - * The following data items are the priority bit map. - * Each of the sixteen bits used in the _Priority_Major_bit_map is - * associated with one of the sixteen entries in the _Priority_Bit_map. - * Each bit in the _Priority_Bit_map indicates whether or not there are +/** + * Each sixteen bit entry in this array is associated with one of + * the sixteen entries in the Priority Bit map. + */ +SCORE_EXTERN volatile Priority_Bit_map_control _Priority_Major_bit_map; + +/** Each bit in the Priority Bitmap indicates whether or not there are * threads ready at a particular priority. The mapping of * individual priority levels to particular bits is processor * dependent as is the value of each bit used to indicate that * threads are ready at that priority. */ - -SCORE_EXTERN volatile Priority_Bit_map_control _Priority_Major_bit_map; SCORE_EXTERN Priority_Bit_map_control _Priority_Bit_map[16] CPU_STRUCTURE_ALIGNMENT; @@ -76,22 +90,33 @@ SCORE_EXTERN Priority_Bit_map_control * */ -/* - * Priority Bitfield Manipulation Routines +#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE ) +/** + * This method returns the priority bit mask for the specified major + * or minor bit number. * - * @note + * @param[in] _bit_number is the bit number for which we need a mask * - * These may simply be pass throughs to CPU dependent routines. + * @return the priority bit mask + * + * @note This may simply be a pass through to a CPU dependent implementation. */ - -#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE ) - #define _Priority_Mask( _bit_number ) \ _CPU_Priority_Mask( _bit_number ) +#endif +#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE ) +/** + * This method returns the bit index position for the specified priority. + * + * @param[in] _priority is the priority for which we need the index. + * + * @return This method returns the array index into the priority bit map. + * + * @note This may simply be a pass through to a CPU dependent implementation. + */ #define _Priority_Bits_index( _priority ) \ _CPU_Priority_bits_index( _priority ) - #endif #ifndef __RTEMS_APPLICATION__ diff --git a/cpukit/score/include/rtems/score/stack.h b/cpukit/score/include/rtems/score/stack.h index d0f61ab8c6..f7e3456569 100644 --- a/cpukit/score/include/rtems/score/stack.h +++ b/cpukit/score/include/rtems/score/stack.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,8 @@ /** * @defgroup ScoreStack Stack Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality which is used in the management + * of thread stacks. */ /**@{*/ @@ -31,20 +32,20 @@ extern "C" { #endif -/* +/** * The following constant defines the minimum stack size which every * thread must exceed. */ - #define STACK_MINIMUM_SIZE CPU_STACK_MINIMUM_SIZE -/* +/** * The following defines the control block used to manage each stack. */ - typedef struct { - uint32_t size; /* stack size */ - void *area; /* low memory addr of stack */ + /** This is the stack size. */ + uint32_t size; + /** This is the low memory address of stack. */ + void *area; } Stack_Control; #ifndef __RTEMS_APPLICATION__ diff --git a/cpukit/score/include/rtems/score/states.h b/cpukit/score/include/rtems/score/states.h index 2b3cac9eb8..8e0b07f138 100644 --- a/cpukit/score/include/rtems/score/states.h +++ b/cpukit/score/include/rtems/score/states.h @@ -5,7 +5,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,7 +21,8 @@ /** * @defgroup ScoreStates Thread States Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality which relates to the management of + * the state bitmap associated with each thread. */ /**@{*/ @@ -29,11 +30,10 @@ extern "C" { #endif -/* +/** * The following type defines the control block used to manage a * thread's state. */ - typedef uint32_t States_Control; /* @@ -41,26 +41,48 @@ typedef uint32_t States_Control; * be used to compose and manipulate a thread's state. */ +/** This macro corresponds to all states being set. */ #define STATES_ALL_SET 0xfffff /* all states */ +/** This macro corresponds to a task being ready. */ #define STATES_READY 0x00000 /* ready to run */ +/** This macro corresponds to a task being created but not yet started. */ #define STATES_DORMANT 0x00001 /* created not started */ +/** This macro corresponds to a task being suspended. */ #define STATES_SUSPENDED 0x00002 /* waiting for resume */ +/** This macro corresponds to a task being in an internal state transition. */ #define STATES_TRANSIENT 0x00004 /* in transition */ +/** This macro corresponds to a task which is waiting for a timeout. */ #define STATES_DELAYING 0x00008 /* wait for timeout */ +/** This macro corresponds to a task waiting until a specific TOD. */ #define STATES_WAITING_FOR_TIME 0x00010 /* wait for TOD */ +/** This macro corresponds to a task waiting for a variable length buffer. */ #define STATES_WAITING_FOR_BUFFER 0x00020 +/** This macro corresponds to a task waiting for a fixed size segment. */ #define STATES_WAITING_FOR_SEGMENT 0x00040 +/** This macro corresponds to a task waiting for a message. */ #define STATES_WAITING_FOR_MESSAGE 0x00080 +/** This macro corresponds to a task waiting for an event. */ #define STATES_WAITING_FOR_EVENT 0x00100 +/** This macro corresponds to a task waiting for a semaphore. */ #define STATES_WAITING_FOR_SEMAPHORE 0x00200 +/** This macro corresponds to a task waiting for a mutex. */ #define STATES_WAITING_FOR_MUTEX 0x00400 +/** This macro corresponds to a task waiting for a condition variable. */ #define STATES_WAITING_FOR_CONDITION_VARIABLE 0x00800 +/** This macro corresponds to a task waiting for a join while exiting. */ #define STATES_WAITING_FOR_JOIN_AT_EXIT 0x01000 +/** This macro corresponds to a task waiting for a reply to an MPCI request. */ #define STATES_WAITING_FOR_RPC_REPLY 0x02000 +/** This macro corresponds to a task waiting for a period. */ #define STATES_WAITING_FOR_PERIOD 0x04000 +/** This macro corresponds to a task waiting for a signal. */ #define STATES_WAITING_FOR_SIGNAL 0x08000 +/** This macro corresponds to a task which is in an interruptible + * blocking state. + */ #define STATES_INTERRUPTIBLE_BY_SIGNAL 0x10000 +/** This macro corresponds to a task waiting for a local object operation. */ #define STATES_LOCALLY_BLOCKED ( STATES_WAITING_FOR_BUFFER | \ STATES_WAITING_FOR_SEGMENT | \ STATES_WAITING_FOR_MESSAGE | \ @@ -70,10 +92,13 @@ typedef uint32_t States_Control; STATES_WAITING_FOR_JOIN_AT_EXIT | \ STATES_WAITING_FOR_SIGNAL ) +/** This macro corresponds to a task waiting which is blocked on + * a thread queue. */ #define STATES_WAITING_ON_THREAD_QUEUE \ ( STATES_LOCALLY_BLOCKED | \ STATES_WAITING_FOR_RPC_REPLY ) +/** This macro corresponds to a task waiting which is blocked. */ #define STATES_BLOCKED ( STATES_DELAYING | \ STATES_WAITING_FOR_TIME | \ STATES_WAITING_FOR_PERIOD | \ diff --git a/cpukit/score/include/rtems/score/sysstate.h b/cpukit/score/include/rtems/score/sysstate.h index 314c0bb2aa..fa53602688 100644 --- a/cpukit/score/include/rtems/score/sysstate.h +++ b/cpukit/score/include/rtems/score/sysstate.h @@ -5,7 +5,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,7 +21,8 @@ /** * @defgroup ScoreSysState System State Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of the + * internal system state of RTEMS. */ /**@{*/ @@ -33,33 +34,45 @@ extern "C" { /* enumerated constants */ -/* +/** * The following type defines the possible system states. */ - typedef enum { - SYSTEM_STATE_BEFORE_INITIALIZATION, /* start -> end of 1st init part */ - SYSTEM_STATE_BEFORE_MULTITASKING, /* end of 1st -> beginning of 2nd */ - SYSTEM_STATE_BEGIN_MULTITASKING, /* just before multitasking starts */ - SYSTEM_STATE_UP, /* normal operation */ - SYSTEM_STATE_SHUTDOWN, /* shutdown */ - SYSTEM_STATE_FAILED /* fatal error occurred */ + /** This indicates that the system state is between the start + * of rtems_initialize_executive_early and the end of the first + * phase of initialization. + */ + SYSTEM_STATE_BEFORE_INITIALIZATION, + /** This indicates that the system state is between end of the first + * phase of initializatin but before multitasking is started. + */ + SYSTEM_STATE_BEFORE_MULTITASKING, + /** This indicates that the system state is attempting to initiate + * multitasking. + */ + SYSTEM_STATE_BEGIN_MULTITASKING, + /** This indicates that the system is up and operating normally. */ + SYSTEM_STATE_UP, + /** This indicates that the system is in the midst of a shutdown. */ + SYSTEM_STATE_SHUTDOWN, + /** This indicates that a fatal error has occurred. */ + SYSTEM_STATE_FAILED } System_state_Codes; +/** This defines the first system state. */ #define SYSTEM_STATE_CODES_FIRST SYSTEM_STATE_BEFORE_INITIALIZATION +/** This defines the highest value system state. */ #define SYSTEM_STATE_CODES_LAST SYSTEM_STATE_FAILED -/* +/** * The following variable indicates whether or not this is * an multiprocessing system. */ - SCORE_EXTERN boolean _System_state_Is_multiprocessing; -/* +/** * The following variable contains the current system state. */ - SCORE_EXTERN System_state_Codes _System_state_Current; /* diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index 02bf0cbd86..7fbae11397 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,8 @@ /** * @defgroup ScoreThread Thread Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of + * threads. This includes the creation, deletion, and scheduling of threads. */ /**@{*/ @@ -67,21 +68,27 @@ typedef enum { THREAD_START_BOTH_NUMERIC_FIRST } Thread_Start_types; -/** - */ +/** This type corresponds to a very simple style thread entry point. */ typedef Thread ( *Thread_Entry )(); /* basic type */ +/** This type corresponds to a thread entry point which takes a single + * unsigned thirty-two bit integer as an argument. + */ typedef Thread ( *Thread_Entry_numeric )( uint32_t ); -/** +/** This type corresponds to a thread entry point which takes a single + * untyped pointer as an argument. */ typedef Thread ( *Thread_Entry_pointer )( void * ); -/** +/** This type corresponds to a thread entry point which takes a single + * untyped pointer and an unsigned thirty-two bit integer as arguments. */ typedef Thread ( *Thread_Entry_both_pointer_first )( void *, uint32_t ); -/** +/** This type corresponds to a thread entry point which takes a single + * unsigned thirty-two bit integer and an untyped pointer and an + * as arguments. */ typedef Thread ( *Thread_Entry_both_numeric_first )( uint32_t , void * ); @@ -99,11 +106,12 @@ typedef enum { THREAD_CPU_BUDGET_ALGORITHM_CALLOUT } Thread_CPU_budget_algorithms; -/** +/** This type defines the Thread Control Block structure. */ typedef struct Thread_Control_struct Thread_Control; -/** +/** This defines thes the entry point for the thread specific timeslice + * budget management algorithm. */ typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * ); @@ -117,7 +125,7 @@ struct rtems_task_variable_tt; * * This is the internal structure used to manager per Task Variables. */ -struct rtems_task_variable_tt { +typedef struct { /** This field points to the next per task variable for this task. */ struct rtems_task_variable_tt *next; /** This field points to the physical memory location of this per @@ -130,33 +138,46 @@ struct rtems_task_variable_tt { void *tval; /** This field points to the destructor for this per task variable. */ void (*dtor)(void *); -}; - -/** - */ -typedef struct rtems_task_variable_tt rtems_task_variable_t; +} rtems_task_variable_t; /** * The following structure contains the information which defines * the starting state of a thread. */ typedef struct { - Thread_Entry entry_point; /* starting thread address */ - Thread_Start_types prototype; /* how task is invoked */ - void *pointer_argument; /* pointer argument */ - uint32_t numeric_argument; /* numeric argument */ - /* initial execution modes */ + /** This field is the starting address for the thread. */ + Thread_Entry entry_point; + /** This field indicatres the how task is invoked. */ + Thread_Start_types prototype; + /** This field is the pointer argument passed at thread start. */ + void *pointer_argument; + /** This field is the numeric argument passed at thread start. */ + uint32_t numeric_argument; + /*-------------- initial execution modes ----------------- */ + /** This field indicates whether the thread was preemptible when + * it started. + */ boolean is_preemptible; + /** This field indicates the CPU budget algorith. */ Thread_CPU_budget_algorithms budget_algorithm; + /** This field is the routine to invoke when the CPU allotment is + * consumed. + */ Thread_CPU_budget_algorithm_callout budget_callout; + /** This field is the initial ISR disable level of this thread. */ uint32_t isr_level; - Priority_Control initial_priority; /* initial priority */ + /** This field is the initial priority. */ + Priority_Control initial_priority; + /** This field indicates whether the SuperCore allocated the stack. */ boolean core_allocated_stack; - Stack_Control Initial_stack; /* stack information */ + /** This field is the stack information. */ + Stack_Control Initial_stack; #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE ) - void *fp_context; /* initial FP context area address */ + /** This field is the initial FP context area address. */ + void *fp_context; #endif - void *stack; /* initial stack area address */ + /** This field is the initial stack area address. */ + void *stack; } Thread_Start_information; /** @@ -204,17 +225,26 @@ typedef struct { * memory images for the shared part. */ typedef struct { + /** This field is the object management structure for each proxy. */ Objects_Control Object; + /** This field is the current execution state of this proxy. */ States_Control current_state; + /** This field is the current priority state of this proxy. */ Priority_Control current_priority; + /** This field is the base priority of this proxy. */ Priority_Control real_priority; + /** This field is the number of mutexes currently held by this proxy. */ uint32_t resource_count; + /** This field is the blocking information for this proxy. */ Thread_Wait_information Wait; + /** This field is the Watchdog used to manage proxy delays and timeouts. */ Watchdog_Control Timer; #if defined(RTEMS_MULTIPROCESSING) + /** This field is the received response packet in an MP system. */ MP_packet_Prefix *receive_packet; #endif /****************** end of common block ********************/ + /** This field is used to manage the set of proxies in the system. */ Chain_Node Active; } Thread_Proxy_control; @@ -226,54 +256,95 @@ typedef struct { * memory images for the shared part. */ typedef enum { + /** This value is for the Classic RTEMS API. */ THREAD_API_RTEMS, + /** This value is for the POSIX API. */ THREAD_API_POSIX, + /** This value is for the ITRON API. */ THREAD_API_ITRON } Thread_APIs; -/** - */ +/** This macro defines the first API which has threads. */ #define THREAD_API_FIRST THREAD_API_RTEMS -/** - */ +/** This macro defines the last API which has threads. */ #define THREAD_API_LAST THREAD_API_ITRON /** + * This structure defines the Thread Control Block (TCB). */ struct Thread_Control_struct { - Objects_Control Object; - States_Control current_state; - Priority_Control current_priority; - Priority_Control real_priority; - uint32_t resource_count; - Thread_Wait_information Wait; - Watchdog_Control Timer; + /** This field is the object management structure for each thread. */ + Objects_Control Object; + /** This field is the current execution state of this thread. */ + States_Control current_state; + /** This field is the current priority state of this thread. */ + Priority_Control current_priority; + /** This field is the base priority of this thread. */ + Priority_Control real_priority; + /** This field is the number of mutexes currently held by this thread. */ + uint32_t resource_count; + /** This field is the blocking information for this thread. */ + Thread_Wait_information Wait; + /** This field is the Watchdog used to manage thread delays and timeouts. */ + Watchdog_Control Timer; #if defined(RTEMS_MULTIPROCESSING) - MP_packet_Prefix *receive_packet; + /** This field is the received response packet in an MP system. */ + MP_packet_Prefix *receive_packet; #endif - /****************** end of common block ********************/ + /*================= end of common block =================*/ + /** This field is the number of nested suspend calls. */ uint32_t suspend_count; + /** This field is true if the thread is offered globally */ boolean is_global; + /** This field is is true if the post task context switch should be + * executed for this thread at the next context switch. + */ boolean do_post_task_switch_extension; - + /** This field is true if the thread is preemptible. */ boolean is_preemptible; + /** This field is the GNAT self context pointer. */ void *rtems_ada_self; + /** This field is the length of the time quantum that this thread is + * allowed to consume. The algorithm used to manage limits on CPU usage + * is specified by budget_algorithm. + */ uint32_t cpu_time_budget; + /** This field is the algorithm used to manage this thread's time + * quantum. The algorithm may be specified as none which case, + * no limit is in place. + */ Thread_CPU_budget_algorithms budget_algorithm; + /** This field is the method invoked with the budgeted time is consumed. */ Thread_CPU_budget_algorithm_callout budget_callout; + /** This field is the number of clock ticks executed by this thread + * since it was created. + */ uint32_t ticks_executed; + /** This field points to the Ready FIFO for this priority. */ Chain_Control *ready; + /** This field contains precalculated priority map indices. */ Priority_Information Priority_map; + /** This field contains information about the starting state of + * this thread. + */ Thread_Start_information Start; + /** This field contains the context of this thread. */ Context_Control Registers; #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE ) + /** This field points to the floating point context for this thread. + * If NULL, the thread is integer only. + */ void *fp_context; #endif + /** This field points to the newlib reentrancy structure for this thread. */ struct _reent *libc_reent; + /** This array contains the API extension area pointers. */ void *API_Extensions[ THREAD_API_LAST + 1 ]; + /** This field points to the user extension pointers. */ void **extensions; + /** This field points to the set of per task variables. */ rtems_task_variable_t *task_variables; }; @@ -303,7 +374,7 @@ SCORE_EXTERN Thread_Control *_Thread_Idle; */ SCORE_EXTERN Context_Control _Thread_BSP_context; -/*** +/** * The following declares the dispatch critical section nesting * counter which is used to prevent context switches at inopportune * moments. @@ -651,7 +722,7 @@ Thread _Thread_Idle_body( ); #endif -/** +/** This defines the type for a method which operates on a single thread. */ typedef void (*rtems_per_thread_routine)( Thread_Control * ); diff --git a/cpukit/score/include/rtems/score/threadmp.h b/cpukit/score/include/rtems/score/threadmp.h index b3ecea6199..6b0ced7307 100644 --- a/cpukit/score/include/rtems/score/threadmp.h +++ b/cpukit/score/include/rtems/score/threadmp.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,10 @@ /** * @defgroup ScoreThreadMP Thread Handler Multiprocessing Support * - * This group contains functionality which XXX + * 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 + * operations. */ /**@{*/ @@ -37,6 +40,7 @@ extern "C" { void _Thread_MP_Handler_initialization ( uint32_t maximum_proxies ); + /** @brief _Thread_MP_Allocate_proxy * * This allocates a proxy control block from @@ -66,7 +70,7 @@ Thread_Control *_Thread_MP_Find_proxy ( */ SCORE_EXTERN Thread_Control *_Thread_MP_Receive; -/* @brief Active Proxy Set +/** @brief Active Proxy Set * * The following chain is used to manage the active set proxies. */ diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h index 572993e72a..86dcbac39b 100644 --- a/cpukit/score/include/rtems/score/threadq.h +++ b/cpukit/score/include/rtems/score/threadq.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,8 @@ /** * @defgroup ScoreThreadQ Thread Queue Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to managing sets of threads + * blocked waiting for resources. */ /**@{*/ diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h index 904541f311..af416a529d 100644 --- a/cpukit/score/include/rtems/score/tod.h +++ b/cpukit/score/include/rtems/score/tod.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,7 @@ /** * @defgroup ScoreTOD Time Of Day (TOD) Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality used to manage time of day. */ /**@{*/ @@ -39,62 +39,62 @@ extern "C" { /**@{*/ /** - * XXX + * This constant represents the number of seconds in a minute. */ -#define TOD_SECONDS_PER_MINUTE (uint32_t )60 +#define TOD_SECONDS_PER_MINUTE (uint32_t)60 /** - * XXX + * This constant represents the number of minutes per hour. */ -#define TOD_MINUTES_PER_HOUR (uint32_t )60 +#define TOD_MINUTES_PER_HOUR (uint32_t)60 /** - * XXX + * This constant represents the number of months in a year. */ -#define TOD_MONTHS_PER_YEAR (uint32_t )12 +#define TOD_MONTHS_PER_YEAR (uint32_t)12 /** - * XXX + * This constant represents the number of days in a non-leap year. */ -#define TOD_DAYS_PER_YEAR (uint32_t )365 +#define TOD_DAYS_PER_YEAR (uint32_t)365 /** - * XXX + * This constant represents the number of hours per day. */ -#define TOD_HOURS_PER_DAY (uint32_t )24 +#define TOD_HOURS_PER_DAY (uint32_t)24 /** - * XXX + * This constant represents the number of seconds in a day which does + * not include a leap second. */ -#define TOD_SECONDS_PER_DAY (uint32_t ) (TOD_SECONDS_PER_MINUTE * \ +#define TOD_SECONDS_PER_DAY (uint32_t) (TOD_SECONDS_PER_MINUTE * \ TOD_MINUTES_PER_HOUR * \ TOD_HOURS_PER_DAY) - /** - * XXX + * This constant represents the number of seconds in a non-leap year. */ #define TOD_SECONDS_PER_NON_LEAP_YEAR (365 * TOD_SECONDS_PER_DAY) /** - * XXX + * This constant represents the number of seconds in a millisecond. */ -#define TOD_MILLISECONDS_PER_SECOND (uint32_t )1000 +#define TOD_MILLISECONDS_PER_SECOND (uint32_t)1000 /** - * XXX + * This constant represents the number of microseconds in a second. */ -#define TOD_MICROSECONDS_PER_SECOND (uint32_t )1000000 +#define TOD_MICROSECONDS_PER_SECOND (uint32_t)1000000 /** - * XXX + * This constant represents the number of nanoseconds in a second. */ -#define TOD_NANOSECONDS_PER_SECOND (uint32_t )1000000000 +#define TOD_NANOSECONDS_PER_SECOND (uint32_t)1000000000 /** - * XXX + * This constant represents the number of nanoseconds in a second. */ -#define TOD_NANOSECONDS_PER_MICROSECOND (uint32_t )1000 +#define TOD_NANOSECONDS_PER_MICROSECOND (uint32_t)1000 /**@}*/ @@ -204,18 +204,24 @@ const uint16_t _TOD_Days_since_last_leap_year[4] = { 0, 366, 731, 1096 }; #else -/** @brief +/** @brief Convert Month to Julian Days * + * This is a prototype for a table which assists in converting the + * current day into the Julian days since the first of the year. */ extern const uint16_t _TOD_Days_to_date[2][13]; /* Julian days */ -/** @brief +/** @brief Days since Beginning of Last Leap Year * + * This is a prototype for a table which assists in calculating the + * number of days since the beginning of the last leap year. */ extern const uint16_t _TOD_Days_since_last_leap_year[4]; -/** @brief +/** @brief Days Per Month Table * + * This is a prototype for a table which holds the number of days + * per month for a leap year and non-leap year. */ extern const uint32_t _TOD_Days_per_month[2][13]; diff --git a/cpukit/score/include/rtems/score/tqdata.h b/cpukit/score/include/rtems/score/tqdata.h index 4b72aed609..b70124ff9e 100644 --- a/cpukit/score/include/rtems/score/tqdata.h +++ b/cpukit/score/include/rtems/score/tqdata.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -22,7 +22,9 @@ /** * @defgroup ScoreThreadQData Thread Queue Handler Data Definition * - * This group contains functionality which XXX + * This handler defines the data shared between the thread and thread + * queue handlers. Having this handler define these data structure + * avoids potentially circular references. */ /**@{*/ @@ -34,21 +36,19 @@ extern "C" { #include <rtems/score/priority.h> #include <rtems/score/states.h> -/* +/** * The following enumerated type details all of the disciplines * supported by the Thread Queue Handler. */ - typedef enum { THREAD_QUEUE_DISCIPLINE_FIFO, /* FIFO queue discipline */ THREAD_QUEUE_DISCIPLINE_PRIORITY /* PRIORITY queue discipline */ } Thread_queue_Disciplines; -/* +/** * The following enumerated types indicate what happened while the thread * queue was in the synchronization window. */ - typedef enum { THREAD_QUEUE_SYNCHRONIZED, THREAD_QUEUE_NOTHING_HAPPENED, @@ -56,8 +56,8 @@ typedef enum { THREAD_QUEUE_SATISFIED } Thread_queue_States; -/* - * The following constants are used to manage the priority queues. +/** + * This is one of the constants used to manage the priority queues. * * There are four chains used to maintain a priority -- each chain * manages a distinct set of task priorities. The number of chains @@ -70,20 +70,45 @@ typedef enum { * is in, then the search is performed from the rear of the chain. * This halves the search time to find the insertion point. */ - #define TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS 4 + +/** + * This is one of the constants used to manage the priority queues. + * @ref TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS for more details. + */ #define TASK_QUEUE_DATA_PRIORITIES_PER_HEADER 64 + +/** + * This is one of the constants used to manage the priority queues. + * @ref TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS for more details. + */ #define TASK_QUEUE_DATA_REVERSE_SEARCH_MASK 0x20 +/** + * This is the structure used to manage sets of tasks which are blocked + * waiting to acquire a resource. + */ typedef struct { + /** This union contains the data structures used to manage the blocked + * set of tasks which varies based upon the discipline. + */ union { - Chain_Control Fifo; /* FIFO discipline list */ + /** This is the FIFO discipline list. */ + Chain_Control Fifo; + /** This is the set of lists for priority discipline waiting. */ Chain_Control Priority[TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS]; - /* priority discipline list */ } Queues; - Thread_queue_States sync_state; /* alloc/dealloc critical section */ - Thread_queue_Disciplines discipline; /* queue discipline */ - States_Control state; /* state of threads on Thread_q */ + /** This field is used to manage the critical section. */ + Thread_queue_States sync_state; + /** This field indicates the thread queue's blocking discipline. */ + Thread_queue_Disciplines discipline; + /** This indicates the blocking state for threads waiting on this + * thread queue. + */ + States_Control state; + /** This is the status value returned to threads which timeout while + * waiting on this thread queue. + */ uint32_t timeout_status; } Thread_queue_Control; diff --git a/cpukit/score/include/rtems/score/userext.h b/cpukit/score/include/rtems/score/userext.h index bb443ce2f6..dcc8c80031 100644 --- a/cpukit/score/include/rtems/score/userext.h +++ b/cpukit/score/include/rtems/score/userext.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,8 @@ /** * @defgroup ScoreUserExt User Extension Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of + * the user extensions to the SuperCore that are available to the user. */ /**@{*/ @@ -35,6 +36,8 @@ extern "C" { #include <rtems/score/chain.h> #include <rtems/score/thread.h> +/*@}*/ + /** @defgroup ScoreUserExtStruct User Extension Handler Structures * * The following records defines the User Extension Table. @@ -45,12 +48,13 @@ extern "C" { /*@{*/ /** - * XXX + * This type indicates the return type of a user extension method. */ typedef void User_extensions_routine; /** - * XXX + * This type defines the prototype of a thread creation extension handler. + * The handler is passed the thread executing and the thread being created. */ typedef boolean ( *User_extensions_thread_create_extension )( Thread_Control *, @@ -58,7 +62,8 @@ typedef boolean ( *User_extensions_thread_create_extension )( ); /** - * XXX + * This type defines the prototype of a thread deletion extension handler. + * The handler is passed the thread executing and the thread being deleted. */ typedef User_extensions_routine ( *User_extensions_thread_delete_extension )( Thread_Control *, @@ -66,7 +71,8 @@ typedef User_extensions_routine ( *User_extensions_thread_delete_extension )( ); /** - * XXX + * This type defines the prototype of thread starting extension handler. + * The handler is passed the thread executing and the thread being started. */ typedef User_extensions_routine ( *User_extensions_thread_start_extension )( Thread_Control *, @@ -74,7 +80,8 @@ typedef User_extensions_routine ( *User_extensions_thread_start_extension )( ); /** - * XXX + * This type defines the prototype of a thread restarting extension handler. + * The handler is passed the thread executing and the thread being restarted. */ typedef User_extensions_routine ( *User_extensions_thread_restart_extension )( Thread_Control *, @@ -82,7 +89,9 @@ typedef User_extensions_routine ( *User_extensions_thread_restart_extension )( ); /** - * XXX + * This type defines the prototype of thread context switch extension handler. + * The handler is passed the thread currently executing and the thread being + * switched to. */ typedef User_extensions_routine ( *User_extensions_thread_switch_extension )( Thread_Control *, @@ -90,29 +99,34 @@ typedef User_extensions_routine ( *User_extensions_thread_switch_extension )( ); /** - * XXX + * This type defines the prototype of a post context switch extension handler. + * The handler is passed the thread thread being switched to. */ -typedef User_extensions_routine ( - *User_extensions_thread_post_switch_extension )( +typedef User_extensions_routine (*User_extensions_thread_post_switch_extension)( Thread_Control * ); /** - * XXX + * This type defines the prototype of a thread beginning to execute + * extension handler. The handler is passed the thread executing. This + * extension is executed in the context of the beginning thread. */ typedef User_extensions_routine ( *User_extensions_thread_begin_extension )( Thread_Control * ); /** - * XXX + * This type defines the prototype of a thread exiting extension handler. + * The handler is passed the thread exiting. */ typedef User_extensions_routine ( *User_extensions_thread_exitted_extension )( Thread_Control * ); /** - * XXX + * This type defines the prototype of the fatal error extension handler. + * The handler is passed an indicator of the source of the fatal error, + * whether it is internal to RTEMS and an error code. */ typedef User_extensions_routine ( *User_extensions_fatal_extension )( Internal_errors_Source /* the_source */, @@ -121,36 +135,37 @@ typedef User_extensions_routine ( *User_extensions_fatal_extension )( ); /** - * XXX + * This type defines a set of user extensions. */ typedef struct { - /** This field is XXX */ + /** This field is the thread creation handler. */ User_extensions_thread_create_extension thread_create; - /** This field is XXX */ + /** This field is the thread starting handler. */ User_extensions_thread_start_extension thread_start; - /** This field is XXX */ + /** This field is the thread restarting handler. */ User_extensions_thread_restart_extension thread_restart; - /** This field is XXX */ + /** This field is the thread deleting handler */ User_extensions_thread_delete_extension thread_delete; - /** This field is XXX */ + /** This field is thread context switch handler. */ User_extensions_thread_switch_extension thread_switch; - /** This field is XXX */ + /** This field is the thread beginning handler. */ User_extensions_thread_begin_extension thread_begin; - /** This field is XXX */ + /** This field is thread exiting handler. */ User_extensions_thread_exitted_extension thread_exitted; - /** This field is XXX */ + /** This field is the fatal error extension. */ User_extensions_fatal_extension fatal; } User_extensions_Table; -/*@}*/ - /** - * This is used to manage the list of switch handlers. + * This is used to manage the list of switch handlers. They are managed + * separately from other extensions for performance reasons. */ typedef struct { - /** This field is XXX */ + /** This field is a Chain Node structure and allows this to be placed on + * chains for set management. + */ Chain_Node Node; - /** This field is XXX */ + /** This field is the thread switch extension. */ User_extensions_thread_switch_extension thread_switch; } User_extensions_Switch_control; @@ -161,11 +176,13 @@ typedef struct { * handler. */ typedef struct { - /** This field is XXX */ + /** This field is a Chain Node structure and allows this to be placed on + * chains for set management. + */ Chain_Node Node; - /** This field is XXX */ + /** This field is the thread switch user extension. */ User_extensions_Switch_control Switch; - /** This field is XXX */ + /** This field is the rest of this user extension's entry points. */ User_extensions_Table Callouts; } User_extensions_Control; @@ -180,10 +197,20 @@ SCORE_EXTERN Chain_Control _User_extensions_List; */ SCORE_EXTERN Chain_Control _User_extensions_Switches_list; +/*@}*/ +/** @addtogroup ScoreUserExt */ + +/*@{*/ + /** @brief User extensions Thread create * * This routine is used to invoke the user extension for * the thread creation operate. + * + * @param[in] the_thread is the thread being created. + * + * @return This method returns TRUE if the user extension executed + * successfully. */ boolean _User_extensions_Thread_create ( Thread_Control *the_thread @@ -193,6 +220,8 @@ boolean _User_extensions_Thread_create ( * * This routine is used to invoke the user extension for * the thread deletion operation. + * + * @param[in] the_thread is the thread being deleted. */ void _User_extensions_Thread_delete ( Thread_Control *the_thread @@ -202,6 +231,8 @@ void _User_extensions_Thread_delete ( * * This routine is used to invoke the user extension for * the thread start operation. + * + * @param[in] the_thread is the thread being started. */ void _User_extensions_Thread_start ( Thread_Control *the_thread @@ -211,6 +242,8 @@ void _User_extensions_Thread_start ( * * This routine is used to invoke the user extension for * the thread restart operation. + * + * @param[in] the_thread is the thread being restarted. */ void _User_extensions_Thread_restart ( Thread_Control *the_thread @@ -220,6 +253,8 @@ void _User_extensions_Thread_restart ( * * This routine is used to invoke the user extension which * is invoked when a thread begins. + * + * @param[in] executing is the thread beginning to execute. */ void _User_extensions_Thread_begin ( Thread_Control *executing @@ -229,6 +264,8 @@ void _User_extensions_Thread_begin ( * * This routine is used to invoke the user extension which * is invoked when a thread exits. + * + * @param[in] executing is the thread voluntarily exiting. */ void _User_extensions_Thread_exitted ( Thread_Control *executing @@ -238,6 +275,10 @@ void _User_extensions_Thread_exitted ( * * This routine is used to invoke the user extension invoked * when a fatal error occurs. + * + * @param[in] the_source is the source of the fatal error. + * @param[in] is_internal is TRUE if the error originated inside RTEMS. + * @param[in] the_error is an indication of the actual error. */ void _User_extensions_Fatal ( Internal_errors_Source the_source, diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h index 124187c899..fc902ad8c7 100644 --- a/cpukit/score/include/rtems/score/watchdog.h +++ b/cpukit/score/include/rtems/score/watchdog.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,11 @@ /** * @defgroup ScoreWatchdog Watchdog Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the scheduling of + * watchdog functions to be called at specific times in the future. + * + * @note This handler does not have anything to do with hardware watchdog + * timers. */ /**@{*/ @@ -109,14 +113,27 @@ typedef enum { * to manage each watchdog timer. */ typedef struct { + /** This field is a Chain Node structure and allows this to be placed on + * chains for set management. + */ Chain_Node Node; + /** This field is the state of the watchdog. */ Watchdog_States state; + /** This field is the initially requested interval. */ Watchdog_Interval initial; + /** This field is the remaining portion of the interval. */ Watchdog_Interval delta_interval; + /** This field is the number of system clock ticks when this was scheduled. */ Watchdog_Interval start_time; + /** This field is the number of system clock ticks when this was suspended. */ Watchdog_Interval stop_time; + /** This field is the function to invoke. */ Watchdog_Service_routine_entry routine; + /** This field is the Id to pass as an argument to the routine. */ Objects_Id id; + /** This field is an untyped pointer to user data that is passed to the + * watchdog handler routine. + */ void *user_data; } Watchdog_Control; @@ -166,7 +183,7 @@ void _Watchdog_Handler_initialization( void ); * 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 the_watchdog (in) will be removed + * @param[in] the_watchdog will be removed * @return the state in which @a the_watchdog was in when removed */ Watchdog_States _Watchdog_Remove ( @@ -178,9 +195,9 @@ Watchdog_States _Watchdog_Remove ( * This routine adjusts the @a header watchdog chain in the forward * or backward @a direction for @a units ticks. * - * @param header (in) is the watchdog chain to adjust - * @param direction (in) is the direction to adjust @a header - * @param units (in) is the number of units to adjust @a header + * @param[in] header is the watchdog chain to adjust + * @param[in] direction is the direction to adjust @a header + * @param[in] units is the number of units to adjust @a header */ void _Watchdog_Adjust ( Chain_Control *header, @@ -193,8 +210,8 @@ void _Watchdog_Adjust ( * This routine inserts @a the_watchdog into the @a header watchdog chain * for a time of @a units. * - * @param header (in) is @a the_watchdog list to insert @a the_watchdog on - * @param the_watchdog (in) is the watchdog to insert + * @param[in] header is @a the_watchdog list to insert @a the_watchdog on + * @param[in] the_watchdog is the watchdog to insert */ void _Watchdog_Insert ( Chain_Control *header, @@ -206,7 +223,7 @@ void _Watchdog_Insert ( * This routine is invoked at appropriate intervals to update * the @a header watchdog chain. * - * @param header (in) is the watchdog chain to tickle + * @param[in] header is the watchdog chain to tickle */ void _Watchdog_Tickle ( diff --git a/cpukit/score/include/rtems/score/wkspace.h b/cpukit/score/include/rtems/score/wkspace.h index f438c39e1e..2fcc22a0aa 100644 --- a/cpukit/score/include/rtems/score/wkspace.h +++ b/cpukit/score/include/rtems/score/wkspace.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -23,7 +23,8 @@ /** * @defgroup ScoreWorkspace Workspace Handler * - * This group contains functionality which XXX + * This handler encapsulates functionality related to the management of + * the RTEMS Executive Workspace. */ /**@{*/ @@ -45,9 +46,9 @@ SCORE_EXTERN Heap_Control _Workspace_Area; /* executive heap header */ * * This routine performs the initialization necessary for this handler. * - * @param starting_address (in) is the base address of the RTEMS Executive + * @param[in] starting_address is the base address of the RTEMS Executive * Workspace - * @param size (in) is the number of bytes in the RTEMS Executive Workspace + * @param[in] size is the number of bytes in the RTEMS Executive Workspace */ void _Workspace_Handler_initialization( void *starting_address, @@ -60,7 +61,7 @@ void _Workspace_Handler_initialization( * bytes. If a block of the appropriate size cannot be allocated * from the workspace, then the internal error handler is invoked. * - * @param size (in) is the desired number of bytes to allocate + * @param[in] size is the desired number of bytes to allocate * @return If successful, the starting address of the allocated memory */ void *_Workspace_Allocate_or_fatal_error( diff --git a/cpukit/score/include/rtems/seterr.h b/cpukit/score/include/rtems/seterr.h index 9e5ebe931e..2548258d87 100644 --- a/cpukit/score/include/rtems/seterr.h +++ b/cpukit/score/include/rtems/seterr.h @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -19,9 +19,25 @@ #ifndef _RTEMS_SETERR_H #define _RTEMS_SETERR_H +/** + * This is a helper macro which will set the variable errno and return + * -1 to the caller. This pattern is common to many POSIX methods. + * + * @param[in] _error is the error code + */ #define rtems_set_errno_and_return_minus_one( _error ) \ do { errno = (_error); return -1; } while(0) +/** + * This is a helper macro which will set the variable errno and return + * -1 to the caller. This pattern is common to many POSIX methods. + * + * @param[in] _error is the error code + * @param[in] _cast is the type to which -1 must be cast + * + * @note It is similar to @ref rtems_set_errno_and_return_minus_one but + * this -1 value is cast to something other than an int. + */ #define rtems_set_errno_and_return_minus_one_cast( _error, _cast ) \ do { errno = (_error); return (_cast) -1; } while(0) diff --git a/cpukit/score/include/rtems/system.h b/cpukit/score/include/rtems/system.h index 27b6ecd432..59d5b293af 100644 --- a/cpukit/score/include/rtems/system.h +++ b/cpukit/score/include/rtems/system.h @@ -7,7 +7,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,12 +24,22 @@ extern "C" { #endif -/* - * Major, minor, revision version numbers of RTEMS. - * Use these macros to test for features in specific releases. +/** This macro defines the major version portion of an RTEMS release. + * + * @note Use this macros to test for features in specific releases. */ #define __RTEMS_MAJOR__ 4 + +/** This macro defines the minor version portion of an RTEMS release. + * + * @note Use this macros to test for features in specific releases. + */ #define __RTEMS_MINOR__ 6 + +/** This macro defines the revision version portion of an RTEMS release. + * + * @note Use this macros to test for features in specific releases. + */ #define __RTEMS_REVISION__ 99 /* @@ -37,16 +47,14 @@ extern "C" { * parameters for this build of RTEMS. It must be included * first so the basic macro definitions are in place. */ - #include <rtems/score/cpuopts.h> -/* +/** * The following ensures that all data is declared in the space * of the initialization routine for either the Initialization Manager * or the initialization file for the appropriate API. It is * referenced as "external" in every other file. */ - #ifdef SCORE_INIT #undef SCORE_EXTERN #define SCORE_EXTERN @@ -55,6 +63,12 @@ extern "C" { #define SCORE_EXTERN extern #endif +/** + * The following ensures that all data is declared in the space + * of the initialization routine for either the Initialization Manager + * or the initialization file for the appropriate API. It is + * referenced as "external" in every other file. + */ #ifdef SAPI_INIT #undef SAPI_EXTERN #define SAPI_EXTERN @@ -63,6 +77,12 @@ extern "C" { #define SAPI_EXTERN extern #endif +/** + * The following ensures that all data is declared in the space + * of the initialization routine for either the Initialization Manager + * or the initialization file for the appropriate API. It is + * referenced as "external" in every other file. + */ #ifdef RTEMS_API_INIT #undef RTEMS_EXTERN #define RTEMS_EXTERN @@ -71,6 +91,12 @@ extern "C" { #define RTEMS_EXTERN extern #endif +/** + * The following ensures that all data is declared in the space + * of the initialization routine for either the Initialization Manager + * or the initialization file for the appropriate API. It is + * referenced as "external" in every other file. + */ #ifdef POSIX_API_INIT #undef POSIX_EXTERN #define POSIX_EXTERN @@ -79,6 +105,12 @@ extern "C" { #define POSIX_EXTERN extern #endif +/** + * The following ensures that all data is declared in the space + * of the initialization routine for either the Initialization Manager + * or the initialization file for the appropriate API. It is + * referenced as "external" in every other file. + */ #ifdef ITRON_API_INIT #undef ITRON_EXTERN #define ITRON_EXTERN @@ -87,13 +119,12 @@ extern "C" { #define ITRON_EXTERN extern #endif -/* +/** * The following (in conjunction with compiler arguments) are used * to choose between the use of static inline functions and macro * functions. The static inline implementation allows better * type checking with no cost in code size or execution speed. */ - #ifdef RTEMS_INLINES # ifdef __GNUC__ # define RTEMS_INLINE_ROUTINE static __inline__ @@ -104,13 +135,14 @@ extern "C" { # define RTEMS_INLINE_ROUTINE #endif -/* - * The following are used by the POSIX implementation to catch bad paths. - */ - #ifdef RTEMS_POSIX_API +/** The following is used by the POSIX implementation to catch bad paths. */ int POSIX_MP_NOT_IMPLEMENTED( void ); + +/** The following is used by the POSIX implementation to catch bad paths. */ int POSIX_NOT_IMPLEMENTED( void ); + +/** The following is used by the POSIX implementation to catch bad paths. */ int POSIX_BOTTOM_REACHED( void ); #endif @@ -118,24 +150,21 @@ int POSIX_BOTTOM_REACHED( void ); * Include a base set of files. */ -/* +/** * XXX: Eventually proc_ptr needs to disappear!!! */ - typedef void * proc_ptr; #include <stddef.h> -/* - * Boolean constants - */ - #if !defined( TRUE ) || (TRUE != 1) +/** Boolean constant TRUE */ #undef TRUE #define TRUE (1) #endif #if !defined( FALSE ) || (FALSE != 0) +/** Boolean constant TRUE */ #undef FALSE #define FALSE (0) #endif @@ -143,67 +172,81 @@ typedef void * proc_ptr; #include <rtems/stdint.h> #include <rtems/score/cpu.h> /* processor specific information */ +/** + * This macro is used to obtain the offset of a field in a structure. + */ #define RTEMS_offsetof(type, field) \ - ((uint32_t ) &(((type *) 0)->field)) + ((uint32_t ) &(((type *) 0)->field)) -/* +/** * The following is the extern for the RTEMS version string. - * The contents of this string are CPU specific. + * + * @note The contents of this string are CPU specific. */ +extern const char _RTEMS_version[]; -extern const char _RTEMS_version[]; /* RTEMS version string */ -extern const char _Copyright_Notice[]; /* RTEMS copyright string */ +/** + * The following is the extern for the RTEMS copyright string. + */ +extern const char _Copyright_Notice[]; -/* +/** * The following defines the CPU dependent information table. */ - -SCORE_EXTERN rtems_cpu_table _CPU_Table; /* CPU dependent info */ +SCORE_EXTERN rtems_cpu_table _CPU_Table; /* * Macros to access CPU Table fields required by ALL ports. - * - * @note Similar macros to access port specific fields in in the - * appropriate cpu.h file. */ -#define rtems_cpu_configuration_get_table() \ - (&_CPU_Table) +/** This macro assists in accessing the CPU Specific Configuration Table. */ +#define rtems_cpu_configuration_get_table() (&_CPU_Table) + +/** This macro assists in accessing the pretasking BSP hook. */ #define rtems_cpu_configuration_get_pretasking_hook() \ (_CPU_Table.pretasking_hook) +/** This macro assists in accessing the predriver BSP hook. */ #define rtems_cpu_configuration_get_predriver_hook() \ (_CPU_Table.predriver_hook) +/** This macro assists in accessing the postdriver BSP hook. */ #define rtems_cpu_configuration_get_postdriver_hook() \ (_CPU_Table.postdriver_hook) +/** This macro assists in accessing the BSP specific IDLE task entry point. */ #define rtems_cpu_configuration_get_idle_task() \ (_CPU_Table.idle_task) +/** + * This macro assists in accessing the field which indicates whether + * RTEMS is responsible for zeroing the Executive Workspace. + */ #define rtems_cpu_configuration_get_do_zero_of_workspace() \ (_CPU_Table.do_zero_of_workspace) +/** This macro assists in accessing the IDLE task stack point size. */ #define rtems_cpu_configuration_get_idle_task_stack_size() \ (_CPU_Table.idle_task_stack_size) +/** This macro assists in accessing the interrupt stack size. */ #define rtems_cpu_configuration_get_interrupt_stack_size() \ (_CPU_Table.interrupt_stack_size) +/** This macro assists in accessing the size of the MPCI receiver server. */ #define rtems_cpu_configuration_get_extra_mpci_receive_server_stack() \ (_CPU_Table.extra_mpci_receive_server_stack) +/** This macro assists in accessing the BSP stack allocation hook. */ #define rtems_cpu_configuration_get_stack_allocate_hook() \ (_CPU_Table.stack_allocate_hook) +/** This macro assists in accessing the BSP stack allocation free hook. */ #define rtems_cpu_configuration_get_stack_free_hook() \ (_CPU_Table.stack_free_hook) -/* - * XXX weird RTEMS stuff that probably should be somewhere else. - */ - +/** This macro defines the maximum length of a Classic API name. */ #define RTEMS_MAXIMUM_NAME_LENGTH sizeof(rtems_name) #ifdef __cplusplus |