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 '')
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 |