diff options
| author | Joel Sherrill <joel.sherrill@OARcorp.com> | 2004-11-01 13:22:41 +0000 |
|---|---|---|
| committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 2004-11-01 13:22:41 +0000 |
| commit | baff4dafe1ff85d128a55e7b73780ca28f5c7faf (patch) | |
| tree | e2acdf92de467f283ecd11fe621a67e79301e1cc /cpukit/score/include | |
| parent | 2004-11-01 Ralf Corsepius <ralf_corsepius@rtems.org> (diff) | |
| download | rtems-baff4dafe1ff85d128a55e7b73780ca28f5c7faf.tar.bz2 | |
2004-11-01 Joel Sherrill <joel@oarcorp.com>
* score/cpu/no_cpu/rtems/score/cpu.h, 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/copyrt.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/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/coremsg.inl,
score/inline/rtems/score/coremutex.inl,
score/inline/rtems/score/coresem.inl,
score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl,
score/inline/rtems/score/mppkt.inl,
score/inline/rtems/score/objectmp.inl,
score/inline/rtems/score/priority.inl,
score/inline/rtems/score/stack.inl,
score/inline/rtems/score/states.inl,
score/inline/rtems/score/sysstate.inl,
score/inline/rtems/score/thread.inl,
score/inline/rtems/score/threadmp.inl,
score/inline/rtems/score/tod.inl,
score/inline/rtems/score/tqdata.inl,
score/inline/rtems/score/userext.inl,
score/inline/rtems/score/watchdog.inl,
score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working
modifications which are not complete and may have broken code.
Committing so work and testing can proceed.
* score/Doxyfile, score/mainpage.h: New files.
Diffstat (limited to 'cpukit/score/include')
31 files changed, 1694 insertions, 1444 deletions
diff --git a/cpukit/score/include/rtems/debug.h b/cpukit/score/include/rtems/debug.h index 0946cd5b91..9cfd989e19 100644 --- a/cpukit/score/include/rtems/debug.h +++ b/cpukit/score/include/rtems/debug.h @@ -1,11 +1,13 @@ -/* debug.h +/** + * @file debug.h * * This include file contains the information pertaining to the debug * support within RTEMS. It is currently cast in the form of a * Manager since it is externally accessible. - * - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be diff --git a/cpukit/score/include/rtems/score/address.h b/cpukit/score/include/rtems/score/address.h index 587d42a07f..66c7c62a95 100644 --- a/cpukit/score/include/rtems/score/address.h +++ b/cpukit/score/include/rtems/score/address.h @@ -1,9 +1,12 @@ -/* address.h +/** + * @file address.h * * This include file contains the information required to manipulate * physical addresses. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,6 +19,14 @@ #ifndef __RTEMS_ADDRESSES_h #define __RTEMS_ADDRESSES_h +/** + * @defgroup ScoreAddress Address Handler + * + * This group contains functionality which abstracts address manipulation + * in a portable manner. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -26,5 +37,7 @@ extern "C" { } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/apiext.h b/cpukit/score/include/rtems/score/apiext.h index d5e496c001..cdf09f8013 100644 --- a/cpukit/score/include/rtems/score/apiext.h +++ b/cpukit/score/include/rtems/score/apiext.h @@ -1,8 +1,11 @@ -/* apiext.h +/** + * @file apiext.h * * This is the API Extensions Handler. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -12,90 +15,109 @@ * $Id$ */ - #ifndef __API_EXTENSIONS_h #define __API_EXTENSIONS_h +/** + * @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 + * 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. + */ +/**@{*/ + #include <rtems/score/chain.h> #include <rtems/score/thread.h> -/* - * The control structure which defines the points at which an API - * can add an extension to the system initialization thread. +/** + * This type defines the prototype of the Predriver Hook. */ - typedef void (*API_extensions_Predriver_hook)(void); + +/** + * This type defines the prototype of the Postdriver Hook. + */ typedef void (*API_extensions_Postdriver_hook)(void); + +/** + * This type defines the prototype of the Postswitch Hook. + */ typedef void (*API_extensions_Postswitch_hook)( Thread_Control * ); - +/** + * The control structure which defines the points at which an API + * can add an extension to the system initialization thread. + */ typedef struct { + /** This field allows this structure to be used with the Chain Handler. */ Chain_Node Node; + /** + * This field is the callout invoked during RTEMS initialization after + * RTEMS data structures are initialized before device driver initialization + * has occurred. + * + * @note If this field is NULL, no extension is invoked. + */ API_extensions_Predriver_hook predriver_hook; + /** + * This field is the callout invoked during RTEMS initialization after + * RTEMS data structures and device driver initialization has occurred + * but before multitasking is initiated. + * + * @note If this field is NULL, no extension is invoked. + */ API_extensions_Postdriver_hook postdriver_hook; + /** + * This field is the callout invoked during each context switch + * in the context of the heir thread. + * + * @note If this field is NULL, no extension is invoked. + */ API_extensions_Postswitch_hook postswitch_hook; } API_extensions_Control; -/* +/** * This is the list of API extensions to the system initialization. */ - SCORE_EXTERN Chain_Control _API_extensions_List; -/* - * _API_extensions_Initialization - * - * DESCRIPTION: - * +/** * This routine initializes the API extension handler. - * */ - void _API_extensions_Initialization( void ); -/* - * _API_extensions_Add +/** + * This routine adds an extension to the active set of API extensions. * - * DESCRIPTION: - * - * XXX + * @param the_extension (in) is the extension set to add. */ - void _API_extensions_Add( API_extensions_Control *the_extension ); -/* - * _API_extensions_Run_predriver - * - * DESCRIPTION: - * - * XXX +/** + * This routine executes all of the predriver callouts. */ - void _API_extensions_Run_predriver( void ); -/* - * _API_extensions_Run_postdriver - * - * DESCRIPTION: - * - * XXX +/** + * This routine executes all of the postdriver callouts. */ - void _API_extensions_Run_postdriver( void ); -/* - * _API_extensions_Run_postswitch - * - * DESCRIPTION: - * - * XXX +/** + * This routine executes all of the post context switch callouts. + */ */ - void _API_extensions_Run_postswitch( void ); +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h index ed345c7c76..ad30e0b18b 100644 --- a/cpukit/score/include/rtems/score/apimutex.h +++ b/cpukit/score/include/rtems/score/apimutex.h @@ -1,10 +1,13 @@ -/* apimutex.h +/** + * @file apimutex.h * * This include file contains all the constants and structures associated * with the API Mutex Handler. This handler is used by API level * routines to manage mutual exclusion. - * - * COPYRIGHT (c) 1989-2002. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -17,6 +20,14 @@ #ifndef __API_MUTEX_h #define __API_MUTEX_h +/** + * @defgroup ScoreAPIMutex API Mutex Handler + * + * This group contains functionality which provides mutexes to be used + * in the implementation of API functionality. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -25,30 +36,29 @@ extern "C" { #include <rtems/score/isr.h> #include <rtems/score/object.h> -/* - * The following defines the control block used to manage each mutex. +/** + * The following defines the control block used to manage each API mutex. + * An API Mutex is an aggregration of an Object and a SuperCore Mutex. */ - typedef struct { + /** This field allows each API Mutex to be a full-fledged RTEMS object. Objects_Control Object; + /** This field contains the SuperCore mutex information. */ CORE_mutex_Control Mutex; } API_Mutex_Control; -/* - * The following defines the information control block used to manage +/** + * The following variable is the information control block used to manage * this class of objects. */ - SCORE_EXTERN Objects_Information _API_Mutex_Information; -/* - * _API_Mutex_Initialization - * - * DESCRIPTION: - * +/** * This routine performs the initialization necessary for this handler. + * + * @param _maximum_mutexes (in) is the maximum number of API mutexes + * that may exist at any time */ - #if defined(RTEMS_MULTIPROCESSING) #define _API_Mutex_Initialization( _maximum_mutexes ) \ _Objects_Initialize_information( \ @@ -75,14 +85,11 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; ); #endif -/* - * _API_Mutex_Allocate - * - * DESCRIPTION: +/** + * This routine allocates an API mutex from the inactive set. * - * This routine allocates an api mutex from the inactive set. + * @param _the_mutex (out) will contain the allocated mutex. */ - #define _API_Mutex_Allocate( _the_mutex ) \ do { \ CORE_mutex_Attributes attr = \ @@ -94,14 +101,11 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; &(_the_mutex)->Mutex, &attr, CORE_MUTEX_UNLOCKED ); \ } while (0) -/* - * _API_Mutex_Lock +/** + * This routine acquires the specified API mutex. * - * DESCRIPTION: - * - * This routine acquires the specified api mutex. + * @param _the_mutex (in) is the mutex to acquire. */ - #define _API_Mutex_Lock( _the_mutex ) \ do { \ ISR_Level _level; \ @@ -110,12 +114,10 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; &(_the_mutex)->Mutex, (_the_mutex)->Object.id, TRUE, 0, (_level) ); \ } while (0) -/* - * _API_Mutex_Unlock - * - * DESCRIPTION: +/** + * This routine releases the specified API mutex. * - * This routine releases the specified api mutex. + * @param _the_mutex (in) is the mutex to release. */ #define _API_Mutex_Unlock( _the_mutex ) \ @@ -126,15 +128,29 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; _Thread_Enable_dispatch(); \ } while (0); -/*XXX when the APIs all use this for allocation and deallocation - *XXX protection, then they should be renamed and probably moved +/** + * This variable points to the API Mutex instance that is used + * to protect all memory allocation and deallocation in RTEMS. + * + * @note When the APIs all use this for allocation and deallocation + * protection, then this possibly should be renamed and moved to a + * higher level in the hierarchy. */ - SCORE_EXTERN API_Mutex_Control *_RTEMS_Allocator_Mutex; +/** + * This macro locks the RTEMS Allocation Mutex. + * + * @see _RTEMS_Allocator_Mutex + */ #define _RTEMS_Lock_allocator() \ _API_Mutex_Lock( _RTEMS_Allocator_Mutex ) +/** + * This macro unlocks the RTEMS Allocation Mutex. + * + * @see _RTEMS_Allocator_Mutex + */ #define _RTEMS_Unlock_allocator() \ _API_Mutex_Unlock( _RTEMS_Allocator_Mutex ) @@ -150,5 +166,7 @@ SCORE_EXTERN API_Mutex_Control *_RTEMS_Allocator_Mutex; } #endif +/*!@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/bitfield.h b/cpukit/score/include/rtems/score/bitfield.h index 5b4c678457..2f097a0c1a 100644 --- a/cpukit/score/include/rtems/score/bitfield.h +++ b/cpukit/score/include/rtems/score/bitfield.h @@ -1,8 +1,11 @@ -/* bitfield.h +/** + * @file bitfield.h * * This include file contains all bit field manipulation routines. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -15,30 +18,26 @@ #ifndef __RTEMS_BITFIELD_h #define __RTEMS_BITFIELD_h +/** + * @defgroup ScoreBitfield Bitfield Handler + * + * This group contains functionality that is used to manipulate the + * priority bitfields used to lookup which priority has the highest + * priority ready to execute thread. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif -/* - * _Bitfield_Find_first_bit - * - * DESCRIPTION: - * - * This routine returns the bit_number of the first bit set - * in the specified value. The correspondence between bit_number - * and actual bit position is processor dependent. The search for - * the first bit set may run from most to least significant bit - * or vice-versa. - * - * NOTE: - * - * This routine is used when the executing thread is removed - * from the ready state and, as a result, its performance has a - * significant impact on the performance of the executive as a whole. - */ - #if ( CPU_USE_GENERIC_BITFIELD_DATA == TRUE ) +/** + * This table is used by the generic bitfield routines to perform + * a highly optimized bit scan without the use of special CPU + * instructions. + */ #ifndef SCORE_INIT extern const unsigned char __log2table[256]; #else @@ -64,18 +63,27 @@ const unsigned char __log2table[256] = { #endif +/** + * This routine returns the @a _bit_number of the first bit set + * in the specified value. The correspondence between @a _bit_number + * and actual bit position is processor dependent. The search for + * 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. + * + * @note This routine is used when the executing thread is removed + * from the ready state and, as a result, its performance has a + * significant impact on the performance of the executive as a whole. + * + * @note This routine must be a macro because if a CPU specific version + * is used it will most likely use inline assembly. + */ #if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE ) - #define _Bitfield_Find_first_bit( _value, _bit_number ) \ _CPU_Bitfield_Find_first_bit( _value, _bit_number ) - #else - -/* - * The following must be a macro because if a CPU specific version - * is used it will most likely use inline assembly. - */ - #define _Bitfield_Find_first_bit( _value, _bit_number ) \ { \ register uint32_t __value = (uint32_t ) (_value); \ @@ -86,12 +94,13 @@ const unsigned char __log2table[256] = { else \ (_bit_number) = __p[ __value >> 8 ]; \ } - #endif #ifdef __cplusplus } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h index 5e70652f43..fc739fc5dd 100644 --- a/cpukit/score/include/rtems/score/chain.h +++ b/cpukit/score/include/rtems/score/chain.h @@ -1,9 +1,12 @@ -/* chain.h +/** + * @file chain.h * * This include file contains all the constants and structures associated - * with the Doubly Linked Chain Handler. - * - * COPYRIGHT (c) 1989-1999. + * with the Doubly-Linked Chain Handler. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,140 +19,158 @@ #ifndef __RTEMS_CHAIN_h #define __RTEMS_CHAIN_h +/** + * @defgroup ScoreChain Chain Handler + * + * The Chain Handler contains XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif #include <rtems/score/address.h> -/* +/** + * @typedef Chain_Node + * + * 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. + */ +typedef struct Chain_Node_struct Chain_Node; + +/** + * @struct Chain_Node_struct + * * This is used to manage each element (node) which is placed * on a chain. * - * NOTE: Typically, a more complicated structure will use the - * chain package. The more complicated structure will - * include a chain node as the first element in its - * control structure. It will then call the chain package - * with a pointer to that node element. The node pointer - * and the higher level structure start at the same address - * so the user can cast the pointers back and forth. + * @note Typically, a more complicated structure will use the + * chain package. The more complicated structure will + * include a chain node as the first element in its + * control structure. It will then call the chain package + * with a pointer to that node element. The node pointer + * and the higher level structure start at the same address + * so the user can cast the pointers back and forth. * */ - -typedef struct Chain_Node_struct Chain_Node; - struct Chain_Node_struct { + /** This points to the node after to this one on this chain. */ Chain_Node *next; + /** This points to the node immediate prior to this one on this chain. */ Chain_Node *previous; }; -/* - * This is used to manage a chain. A chain consists of a doubly - * linked list of zero or more nodes. - * - * NOTE: This implementation does not require special checks for - * manipulating the first and last elements on the chain. - * To accomplish this the chain control structure is - * treated as two overlapping chain nodes. The permanent - * head of the chain overlays a node structure on the - * first and permanent_null fields. The permanent tail - * of the chain overlays a node structure on the - * permanent_null and last elements of the structure. +/** + * @struct Chain_Control + * + * This is used to manage a chain. A chain consists of a doubly + * linked list of zero or more nodes. + * + * @note This implementation does not require special checks for + * manipulating the first and last elements on the chain. + * To accomplish this the @a Chain_Control structure is + * treated as two overlapping @ref Chain_Node structures. + * The permanent head of the chain overlays a node structure on the + * @a first and @a permanent_null fields. The permanent tail + * of the chain overlays a node structure on the + * @a permanent_null and @a last elements of the structure. * */ - typedef struct { + /** This points to the first node on this chain. */ Chain_Node *first; + /** This field is always 0. */ Chain_Node *permanent_null; + /** This points to the last node on this chain. */ Chain_Node *last; } Chain_Control; -/* - * _Chain_Initialize - * - * DESCRIPTION: +/** + * @brief Initialize a Chain Header * - * This routine initializes the_chain structure to manage the - * contiguous array of number_nodes nodes which starts at - * starting_address. Each node is of node_size bytes. + * This routine initializes @a the_chain structure to manage the + * contiguous array of @a number_nodes nodes which starts at + * @a starting_address. Each node is of @a node_size bytes. * + * @param the_chain (in) specifies the chain to initialize + * @param starting_address (in) 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 */ - void _Chain_Initialize( Chain_Control *the_chain, void *starting_address, - uint32_t number_nodes, - uint32_t node_size + unsigned32 number_nodes, + unsigned32 node_size ); -/* - * _Chain_Get_first_unprotected - */ - #ifndef RTEMS_INLINES +/** + * @brief Get the first node (do not disable interrupts) + * + * This method attempts to obtain the first node from \a the_chain. + * + * @param the_chain (in) points to the chain to operate upon + * @return If successful, a chain node is returned. Otherwise, NULL + * is returned. + */ Chain_Node *_Chain_Get_first_unprotected( Chain_Control *the_chain ); #endif -/* - * _Chain_Extract - * - * DESCRIPTION: +/** + * @brief Extract the specified node from a chain * - * This routine extracts the_node from the chain on which it resides. + * This routine extracts \a the_node from the chain on which it resides. * It disables interrupts to insure the atomicity of the * extract operation. * + * @arg the_node specifies the node to extract */ - void _Chain_Extract( Chain_Node *the_node ); -/* - * _Chain_Get +/** + * @brief Obtain the first node on a chain * - * DESCRIPTION: + * 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 the_chain and returns - * a pointer to that node. If the_chain is empty, then NULL is returned. - * It disables interrupts to insure the atomicity of the + * @note It disables interrupts to insure the atomicity of the * get operation. - * */ - Chain_Node *_Chain_Get( Chain_Control *the_chain ); -/* - * _Chain_Insert +/** + * @brief Insert a node on a chain * - * DESCRIPTION: + * This routine inserts \a the_node on a chain immediately following + * \a after_node. * - * This routine inserts the_node on a chain immediately following - * after_node. It disables interrupts to insure the atomicity + * @note It disables interrupts to insure the atomicity * of the extract operation. - * */ - void _Chain_Insert( Chain_Node *after_node, Chain_Node *the_node ); -/* - * _Chain_Append +/** + * @brief Append a node on the end of a chain * - * DESCRIPTION: + * This routine appends \a the_node onto the end of \a the_chain. * - * This routine appends the_node onto the end of the_chain. - * It disables interrupts to insure the atomicity of the + * @note It disables interrupts to insure the atomicity of the * append operation. - * */ - void _Chain_Append( Chain_Control *the_chain, Chain_Node *the_node @@ -163,5 +184,7 @@ void _Chain_Append( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/context.h b/cpukit/score/include/rtems/score/context.h index f1ea268c13..7c0b5df16d 100644 --- a/cpukit/score/include/rtems/score/context.h +++ b/cpukit/score/include/rtems/score/context.h @@ -1,8 +1,11 @@ -/* context.h +/** + * @file context.h * - * This include file contains all information about a context. - * - * COPYRIGHT (c) 1989-1999. + * This include file contains all information about each thread's context. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -15,113 +18,121 @@ #ifndef __RTEMS_CONTEXT_h #define __RTEMS_CONTEXT_h +/** + * @defgroup ScoreContext Context Handler + * + * This group contains functionality which abstracts thread context + * management in a portable manner. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif #include <rtems/score/cpu.h> -/* - * The following constant defines the number of bytes required +/** + * @ingroup ScoreContext + * This constant defines the number of bytes required * to store a full floating point context. */ - #define CONTEXT_FP_SIZE CPU_CONTEXT_FP_SIZE -/* - * The following variable is set to TRUE when a reschedule operation +/** + * @ingroup ScoreContext + * 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. */ SCORE_EXTERN volatile boolean _Context_Switch_necessary; -/* - * _Context_Initialize - * - * DESCRIPTION: - * - * This routine initializes THE_CONTEXT such that the stack +/** + * @ingroup ScoreContext + * 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 + * 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 + * enabled */ - #define \ _Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) \ _CPU_Context_Initialize( _the_context, _stack, _size, _isr, _entry, _is_fp ) -/* - * _Context_Switch - * - * DESCRIPTION: +/** + * @ingroup ScoreContext + * This routine saves the current context into the @a _executing + * context record and restores the context specified by @a _heir. * - * This routine saves the current context into the EXECUTING - * context record and restores the context specified by HEIR. + * @param _executing (in) is the currently executing thread's context + * @param _heir (in) is the context of the thread to be switched to */ - #define _Context_Switch( _executing, _heir ) \ _CPU_Context_switch( _executing, _heir ) -/* - * _Context_Restart_self - * - * DESCRIPTION: - * +/** + * @ingroup ScoreContext * 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 */ - #define _Context_Restart_self( _the_context ) \ _CPU_Context_Restart_self( _the_context ) -/* - * _Context_Fp_start - * - * DESCRIPTION: - * +/** + * @ingroup ScoreContext * 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 + * context save area. + * @param _offset (in) is XXX + * + * @return the initial FP context pointer */ - #define _Context_Fp_start( _base, _offset ) \ _CPU_Context_Fp_start( (_base), (_offset) ) -/* - * _Context_Initialize_fp - * - * DESCRIPTION: - * +/** + * @ingroup ScoreContext * 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 + * context save area to initialize. */ - #define _Context_Initialize_fp( _fp_area ) \ _CPU_Context_Initialize_fp( _fp_area ) -/* - * _Context_Restore_fp - * - * DESCRIPTION: - * +/** + * @ingroup ScoreContext * This routine restores the floating point context contained - * in the FP_CONTEXT area. It is assumed that the current + * in the @a _fp area. It is assumed that the current * floating point context has been saved by a previous invocation - * of SAVE_FP. + * of @a _Context_Save_fp. + * + * @param _fp (in) points to the floating point context area to restore. */ - #define _Context_Restore_fp( _fp ) \ _CPU_Context_restore_fp( _fp ) -/* - * _Context_Save_fp - * - * DESCRIPTION: - * +/** + * @ingroup ScoreContext * This routine saves the current floating point context - * in the FP_CONTEXT area. + * in the @a _fp area. + * + * @param _fp (in) points to the floating point context area to restore. */ - #define _Context_Save_fp( _fp ) \ _CPU_Context_save_fp( _fp ) @@ -129,5 +140,7 @@ SCORE_EXTERN volatile boolean _Context_Switch_necessary; } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/copyrt.h b/cpukit/score/include/rtems/score/copyrt.h index f18e3c675e..e300f4276a 100644 --- a/cpukit/score/include/rtems/score/copyrt.h +++ b/cpukit/score/include/rtems/score/copyrt.h @@ -1,9 +1,12 @@ -/* copyrt.h +/** + * @file copyrt.h * * This include file contains the copyright notice for RTEMS * which is included in every binary copy of the executive. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -20,16 +23,15 @@ extern "C" { #endif +/** + * This is the copyright string for RTEMS. + */ #ifdef SCORE_INIT - const char _Copyright_Notice[] = -"COPYRIGHT (c) 1989-1999.\n\ +"COPYRIGHT (c) 1989-2004.\n\ On-Line Applications Research Corporation (OAR).\n"; - #else - extern const char _Copyright_Notice[]; - #endif #ifdef __cplusplus diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h index 70906135a4..a1789ab111 100644 --- a/cpukit/score/include/rtems/score/coremsg.h +++ b/cpukit/score/include/rtems/score/coremsg.h @@ -1,9 +1,12 @@ -/* coremsg.h +/** + * @file coremsg.h * * This include file contains all the constants and structures associated * with the Message queue Handler. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,6 +19,14 @@ #ifndef __RTEMS_CORE_MESSAGE_QUEUE_h #define __RTEMS_CORE_MESSAGE_QUEUE_h +/** + * @defgroup ScoreMessageQueue Message Queue Handler + * + * This group contains functionality which provides the foundation + * Message Queue services used in all of the APIs supported by RTEMS. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -26,122 +37,176 @@ extern "C" { #include <rtems/score/priority.h> #include <rtems/score/watchdog.h> -/* +/** * The following type defines the callout which the API provides * to support global/multiprocessor operations on message_queues. */ - typedef void ( *CORE_message_queue_API_mp_support_callout )( Thread_Control *, Objects_Id ); -/* +/** * The following defines the data types needed to manipulate * the contents of message buffers. * - * NOTE: The buffer field is normally longer than a single uint32_t . + * @note The buffer field is normally longer than a single uint32_t * but since messages are variable length we just make a ptr to 1. */ - typedef struct { - uint32_t size; - uint32_t buffer[1]; + /** This field is the size of this message. */ + uint32_t size; + /** This field contains the actual message. */ + uint32_t buffer[1]; } CORE_message_queue_Buffer; -/* +/** * The following records define the organization of a message * buffer. */ - typedef struct { + /** This element allows this structure to be placed on chains. */ Chain_Node Node; + /** This field is the priority of this message. */ int priority; + /** This field points to the contents of the message. */ CORE_message_queue_Buffer Contents; } CORE_message_queue_Buffer_control; -/* - * Blocking disciplines for a message_queue. +/** + * Blocking disciplines for a message queue. */ - typedef enum { + /** This value indicates that pending messages are in FIFO order. */ CORE_MESSAGE_QUEUE_DISCIPLINES_FIFO, + /** This value indicates that pending messages are in priority order. */ CORE_MESSAGE_QUEUE_DISCIPLINES_PRIORITY } CORE_message_queue_Disciplines; -/* +/** + * This is the priority constant used when appending messages onto + * a message queue. + */ +#define CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX + +/** + * 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 * may be submitted to a message queue. The message may be posted * in a send or urgent fashion. * - * NOTE: All other values are message priorities. Numerically smaller + * @note All other values are message priorities. Numerically smaller * priorities indicate higher priority messages. - * */ - -#define CORE_MESSAGE_QUEUE_SEND_REQUEST INT_MAX -#define CORE_MESSAGE_QUEUE_URGENT_REQUEST INT_MIN - typedef int CORE_message_queue_Submit_types; -/* +/** * Core Message queue handler return statuses. */ - typedef enum { + /** This value indicates the operation completed sucessfully. */ CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL, + /** This value indicates that the message was too large for this queue. */ CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE, + /** This value indicates that there are too many messages pending. */ CORE_MESSAGE_QUEUE_STATUS_TOO_MANY, + /** This value indicates that a receive was unsuccessful. */ CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED, + /** This value indicates that a blocking send was unsuccessful. */ CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_NOWAIT, + /** This value indicates that the message queue being blocked upon + * was deleted while the thread was waiting. + */ CORE_MESSAGE_QUEUE_STATUS_WAS_DELETED, + /** This value indicates that the thread had to timeout while waiting + * to receive a message because one did not become available. + */ CORE_MESSAGE_QUEUE_STATUS_TIMEOUT, + /** This value indicates that a blocking receive was unsuccessful. */ CORE_MESSAGE_QUEUE_STATUS_UNSATISFIED_WAIT } CORE_message_queue_Status; -/* +/** * The following defines the control block used to manage the * attributes of each message queue. */ - typedef struct { + /** This field specifies the order in which blocking tasks will be ordered. */ CORE_message_queue_Disciplines discipline; } CORE_message_queue_Attributes; -/* +/** * 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. */ - typedef void (*CORE_message_queue_Notify_Handler)( void * ); -/* +/** * The following defines the control block used to manage each * counting message_queue. */ - typedef struct { + /** This field is the Waiting Queue used to manage the set of tasks + * which are blocked waiting to receive a message from this queue. + */ Thread_queue_Control Wait_queue; + /** This element is the set of attributes which define this instance's + * behavior. + */ CORE_message_queue_Attributes Attributes; + /** This element is maximum number of messages which may be pending + * at any given time. + */ uint32_t maximum_pending_messages; + /** This element is the number of messages which are currently pending. + */ uint32_t number_of_pending_messages; + /** This is the size in bytes of the largest message which may be + * sent via this queue. + */ uint32_t maximum_message_size; + /** This chain is the set of pending messages. It may be ordered by + * message priority or in FIFO order. + */ Chain_Control Pending_messages; + /** This is the address of the memory allocated for message buffers. + * It is allocated are part of message queue initialization and freed + * as part of destroying it. + */ CORE_message_queue_Buffer *message_buffers; + /** This is the routine invoked when the message queue transitions + * from zero (0) messages pending to one (1) message pending. + */ CORE_message_queue_Notify_Handler notify_handler; + /** This field is the argument passed to the @ref notify_argument. */ void *notify_argument; + /** This chain is the set of inactive messages. A message is inactive + * when it does not contain a pending message. + */ Chain_Control Inactive_messages; } CORE_message_queue_Control; -/* - * _CORE_message_queue_Initialize +/** + * This routine initializes the message_queue based on the parameters passed. * - * DESCRIPTION: + * @param the_message_queue (in) points to the message queue to initialize + * @param the_message_queue_attributes (in) points to the attributes that + * will be used with this message queue instance + * @param maximum_pending_messages (in) 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 + * may be sent to this message queue instance * - * This routine initializes the message_queue based on the parameters passed. + * @return TRUE if the message queue can be initialized. In general, + * FALSE will only be returned if memory for the pending + * messages cannot be allocated. */ - boolean _CORE_message_queue_Initialize( CORE_message_queue_Control *the_message_queue, CORE_message_queue_Attributes *the_message_queue_attributes, @@ -149,72 +214,71 @@ boolean _CORE_message_queue_Initialize( uint32_t maximum_message_size ); -/* - * _CORE_message_queue_Close - * - * DESCRIPTION: - * +/** * This function closes a message by returning all allocated space and * flushing 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 + * that is extracted from the set of waiting threads + * @param status (in) is the status that each waiting thread will return + * from it's blocking service */ - void _CORE_message_queue_Close( CORE_message_queue_Control *the_message_queue, Thread_queue_Flush_callout remote_extract_callout, uint32_t status ); -/* - * _CORE_message_queue_Flush - * - * DESCRIPTION: - * +/** * This function flushes 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 */ - uint32_t _CORE_message_queue_Flush( CORE_message_queue_Control *the_message_queue ); -/* - * _CORE_message_queue_Flush_support - * - * DESCRIPTION: - * +/** * 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 */ - uint32_t _CORE_message_queue_Flush_support( CORE_message_queue_Control *the_message_queue ); -/* - * _CORE_message_queue_Flush_waiting_threads - * - * DESCRIPTION: - * +/** * This function flushes the threads which are blocked on this * 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 */ - void _CORE_message_queue_Flush_waiting_threads( CORE_message_queue_Control *the_message_queue ); -/* - * _CORE_message_queue_Broadcast - * - * DESCRIPTION: - * +/** * 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. + * It is used when unblocking a remote thread. + * @param api_message_queue_mp_support (in) 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 + * 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 */ - CORE_message_queue_Status _CORE_message_queue_Broadcast( CORE_message_queue_Control *the_message_queue, void *buffer, @@ -224,11 +288,7 @@ CORE_message_queue_Status _CORE_message_queue_Broadcast( uint32_t *count ); -/* - * _CORE_message_queue_Submit - * - * DESCRIPTION: - * +/** * 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 @@ -236,8 +296,21 @@ 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. + * It is used when unblocking a remote thread. + * @param api_message_queue_mp_support (in) 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, + * appended, or enqueued in priority order. + * @param wait (in) 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 + * thread is willing to block if the message queue is full. + * @return indication of the successful completion or reason for failure */ - CORE_message_queue_Status _CORE_message_queue_Submit( CORE_message_queue_Control *the_message_queue, void *buffer, @@ -249,19 +322,27 @@ CORE_message_queue_Status _CORE_message_queue_Submit( Watchdog_Interval timeout ); -/* - * _CORE_message_queue_Seize - * - * DESCRIPTION: - * +/** * 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. * - * NOTE: Returns message priority via return are in TCB. + * @param the_message_queue (in) points to the message queue + * @param id (in) 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 + * to be filled in with a message + * @param size (in) 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 + * if the message queue is empty. + * @param timeout (in) is the maximum number of clock ticks that the calling + * thread is willing to block if the message queue is empty. + * + * @return indication of the successful completion or reason for failure + * @note Returns message priority via return are in TCB. */ - void _CORE_message_queue_Seize( CORE_message_queue_Control *the_message_queue, Objects_Id id, @@ -271,16 +352,16 @@ void _CORE_message_queue_Seize( Watchdog_Interval timeout ); -/* - * _CORE_message_queue_Insert_message - * - * DESCRIPTION: - * +/** * This kernel routine inserts the specified message into the * message queue. It is assumed that the message has been filled * in before this routine is called. + * + * @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, + * appended, or enqueued in priority order. */ - void _CORE_message_queue_Insert_message( CORE_message_queue_Control *the_message_queue, CORE_message_queue_Buffer_control *the_message, @@ -295,5 +376,7 @@ void _CORE_message_queue_Insert_message( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/coremutex.h b/cpukit/score/include/rtems/score/coremutex.h index ec55009843..5be229f2ea 100644 --- a/cpukit/score/include/rtems/score/coremutex.h +++ b/cpukit/score/include/rtems/score/coremutex.h @@ -1,11 +1,14 @@ -/* mutex.h +/** + * @file coremutex.h * * This include file contains all the constants and structures associated * with the Mutex Handler. A mutex is an enhanced version of the standard * Dijkstra binary semaphore used to provide synchronization and mutual * exclusion capabilities. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -18,6 +21,14 @@ #ifndef __RTEMS_CORE_MUTEX_h #define __RTEMS_CORE_MUTEX_h +/** + * @defgroup ScoreMutex Mutex Handler + * + * This group contains functionality which provides the foundation + * Mutex services used in all of the APIs supported by RTEMS. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -29,155 +40,230 @@ extern "C" { #include <rtems/score/interr.h> #include <rtems/score/sysstate.h> -/* +/** * The following type defines the callout which the API provides * to support global/multiprocessor operations on mutexes. */ - typedef void ( *CORE_mutex_API_mp_support_callout )( Thread_Control *, Objects_Id ); -/* +/** * Blocking disciplines for a mutex. */ - typedef enum { + /** This specifies that threads will wait for the mutex in FIFO order. */ CORE_MUTEX_DISCIPLINES_FIFO, + /** This specifies that threads will wait for the mutex in priority order. */ CORE_MUTEX_DISCIPLINES_PRIORITY, + /** This specifies that threads will wait for the mutex in priority order. + * Additionally, the Priority Inheritance Protocol will be in effect. + */ CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT, + /** This specifies that threads will wait for the mutex in priority order. + * Additionally, the Priority Ceiling Protocol will be in effect. + */ CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING } CORE_mutex_Disciplines; -/* +/** * Mutex handler return statuses. */ - typedef enum { + /** This status indicates that the operation completed successfully. */ CORE_MUTEX_STATUS_SUCCESSFUL, + /** This status indicates that the calling task did not want to block + * and the operation was unable to complete immediately because the + * resource was unavailable. + */ CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT, + /** This status indicates that an attempt was made to relock a mutex + * for which nesting is not configured. + */ CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED, + /** This status indicates that an attempt was made to release a mutex + * by a thread other than the thread which locked it. + */ CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE, + /** This status indicates that the thread was blocked waiting for an + * operation to complete and the mutex was deleted. + */ CORE_MUTEX_WAS_DELETED, + /** This status indicates that the calling task was willing to block + * but the operation was unable to complete within the time allotted + * because the resource never became available. + */ CORE_MUTEX_TIMEOUT, + /** This status indicates that a thread of logically greater importance + * than the ceiling priority attempted to lock this mutex. + */ CORE_MUTEX_STATUS_CEILING_VIOLATED } CORE_mutex_Status; -/* +/** * Mutex lock nesting behavior * - * CORE_MUTEX_NESTING_ACQUIRES: + * + CORE_MUTEX_NESTING_ACQUIRES: * This sequence has no blocking or errors: - * lock(m) - * lock(m) - * unlock(m) - * unlock(m) * - * CORE_MUTEX_NESTING_IS_ERROR + * + lock(m) + * + lock(m) + * + unlock(m) + * + unlock(m) + * + * + 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 + * + 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 + * + lock(m) + * + lock(m) - deadlocks or timeouts + * + unlock(m) - releases */ - typedef enum { CORE_MUTEX_NESTING_ACQUIRES, CORE_MUTEX_NESTING_IS_ERROR, CORE_MUTEX_NESTING_BLOCKS } CORE_mutex_Nesting_behaviors; -/* - * Locked and unlocked values +/** + * This is the value of a mutex when it is unlocked. */ - #define CORE_MUTEX_UNLOCKED 1 + +/** + * This is the value of a mutex when it is locked. + */ #define CORE_MUTEX_LOCKED 0 -/* +/** * The following defines the control block used to manage the * attributes of each mutex. */ - typedef struct { + /** This field determines what the behavior of this mutex instance will + * be when attempting to acquire the mutex when it is already locked. + */ CORE_mutex_Nesting_behaviors lock_nesting_behavior; + /** When this field is TRUE, then only the thread that locked the mutex + * is allowed to unlock it. + */ boolean only_owner_release; + /** This field indicates whether threads waiting on the mutex block in + * FIFO or priority order. + */ CORE_mutex_Disciplines discipline; + /** This field contains the ceiling priority to be used if that protocol + * is selected. + */ Priority_Control priority_ceiling; } CORE_mutex_Attributes; -/* +/** * The following defines the control block used to manage each mutex. */ - typedef struct { + /** This field is the Waiting Queue used to manage the set of tasks + * which are blocked waiting to lock the mutex. + */ Thread_queue_Control Wait_queue; + /** This element is the set of attributes which define this instance's + * behavior. + */ CORE_mutex_Attributes Attributes; + /** This element contains the current state of the mutex. + */ uint32_t lock; + /** This element contains the number of times the mutex has been acquired + * nested. This must be zero (0) before the mutex is actually unlocked. + */ uint32_t nest_count; + /** This is the number of waiting threads. */ uint32_t blocked_count; + /** This element points to the thread which is currently holding this mutex. + * The holder is the last thread to successfully lock the mutex and which + * has not unlocked it. If the thread is not locked, there is no holder. + */ Thread_Control *holder; + /** This element contains the object Id of the holding thread. */ Objects_Id holder_id; } CORE_mutex_Control; -/* - * _CORE_mutex_Initialize - * - * DESCRIPTION: +/** * * 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 + * mutex instance + * @param initial_lock (in) is the initial value of the mutex */ - void _CORE_mutex_Initialize( CORE_mutex_Control *the_mutex, CORE_mutex_Attributes *the_mutex_attributes, uint32_t initial_lock ); -/* - * _CORE_mutex_Seize - * - * DESCRIPTION: - * +#ifndef __RTEMS_APPLICATION__ +/** * 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. * - * NOTE: For performance reasons, this routine is implemented as + * @param the_mutex (in) is the mutex to attempt to lock + * @param level_p (in) is the interrupt level holder + * + * @note For performance reasons, this routine is implemented as * a macro that uses two support routines. */ - - -#ifndef __RTEMS_APPLICATION__ RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock( CORE_mutex_Control *the_mutex, ISR_Level *level_p ); +/** + * 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 + */ void _CORE_mutex_Seize_interrupt_blocking( CORE_mutex_Control *the_mutex, Watchdog_Interval timeout ); +/** + * 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 + * disable level cookie + */ #define _CORE_mutex_Seize( \ _the_mutex, _id, _wait, _timeout, _level ) \ do { \ - if ( _Thread_Dispatch_disable_level \ - && (_wait) \ - && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \ - ) { \ - _Internal_error_Occurred( \ - INTERNAL_ERROR_CORE, \ - FALSE, \ - 18 /* called from wrong environment */); \ - } \ + if ( _Thread_Dispatch_disable_level \ + && (_wait) \ + && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \ + ) { \ + _Internal_error_Occurred( \ + INTERNAL_ERROR_CORE, \ + FALSE, \ + 18 /* called from wrong environment */); \ + } \ if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) { \ if ( !_wait ) { \ _ISR_Enable( _level ); \ @@ -194,31 +280,34 @@ void _CORE_mutex_Seize_interrupt_blocking( } \ } while (0) -/* - * _CORE_mutex_Surrender - * - * DESCRIPTION: - * +/** * 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 + * unblocking a remote mutex + * + * @return an indication of whether the routine succeeded or failed */ - CORE_mutex_Status _CORE_mutex_Surrender( CORE_mutex_Control *the_mutex, Objects_Id id, CORE_mutex_API_mp_support_callout api_mutex_mp_support ); -/* - * _CORE_mutex_Flush - * - * DESCRIPTION: - * +/** * 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 + * thread is extracted + * @param status (in) is the status value which each unblocked thread will + * return to its caller. */ - void _CORE_mutex_Flush( CORE_mutex_Control *the_mutex, Thread_queue_Flush_callout remote_extract_callout, @@ -232,5 +321,7 @@ void _CORE_mutex_Flush( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h index e9be0036ab..333cd1874f 100644 --- a/cpukit/score/include/rtems/score/coresem.h +++ b/cpukit/score/include/rtems/score/coresem.h @@ -1,11 +1,14 @@ -/* core_sem.h +/** + * @file coresem.h * * This include file contains all the constants and structures associated * with the Counting Semaphore Handler. A counting semaphore is the * standard Dijkstra binary semaphore used to provide synchronization * and mutual exclusion capabilities. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -18,6 +21,14 @@ #ifndef __RTEMS_CORE_COUNTING_SEMAPHORE_h #define __RTEMS_CORE_COUNTING_SEMAPHORE_h +/** + * @defgroup ScoreSemaphore Semaphore Handler + * + * This group contains functionality which provides the foundation + * Semaphore services used in all of the APIs supported by RTEMS. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -27,83 +38,108 @@ extern "C" { #include <rtems/score/priority.h> #include <rtems/score/watchdog.h> -/* +/** * The following type defines the callout which the API provides * to support global/multiprocessor operations on semaphores. */ - typedef void ( *CORE_semaphore_API_mp_support_callout )( Thread_Control *, Objects_Id ); -/* +/** * Blocking disciplines for a semaphore. */ - typedef enum { + /** This specifies that threads will wait for the semaphore in FIFO order. */ CORE_SEMAPHORE_DISCIPLINES_FIFO, + /** This specifies that threads will wait for the semaphore in + * priority order. + */ CORE_SEMAPHORE_DISCIPLINES_PRIORITY } CORE_semaphore_Disciplines; -/* +/** * Core Semaphore handler return statuses. */ - typedef enum { + /** This status indicates that the operation completed successfully. */ CORE_SEMAPHORE_STATUS_SUCCESSFUL, + /** This status indicates that the calling task did not want to block + * and the operation was unable to complete immediately because the + * resource was unavailable. + */ CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT, + /** This status indicates that the thread was blocked waiting for an + * operation to complete and the semaphore was deleted. + */ CORE_SEMAPHORE_WAS_DELETED, + /** This status indicates that the calling task was willing to block + * but the operation was unable to complete within the time allotted + * because the resource never became available. + */ CORE_SEMAPHORE_TIMEOUT, + /** This status indicates that an attempt was made to unlock the semaphore + * and this would have made its count greater than that allowed. CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED } CORE_semaphore_Status; -/* +/** * The following defines the control block used to manage the * attributes of each semaphore. */ - typedef struct { + /** This element indicates the maximum count this semaphore may have. */ uint32_t maximum_count; + /** This field indicates whether threads waiting on the semaphore block in + * FIFO or priority order. + */ CORE_semaphore_Disciplines discipline; } CORE_semaphore_Attributes; -/* +/** * The following defines the control block used to manage each * counting semaphore. */ - typedef struct { + /** This field is the Waiting Queue used to manage the set of tasks + * which are blocked waiting to obtain the semaphore. + */ Thread_queue_Control Wait_queue; + /** This element is the set of attributes which define this instance's + * behavior. + */ CORE_semaphore_Attributes Attributes; + /** This element contains the current count of this semaphore. */ uint32_t count; } CORE_semaphore_Control; -/* - * _CORE_semaphore_Initialize - * - * DESCRIPTION: - * +/** * 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 */ - void _CORE_semaphore_Initialize( CORE_semaphore_Control *the_semaphore, CORE_semaphore_Attributes *the_semaphore_attributes, uint32_t initial_value ); -/* - * _CORE_semaphore_Seize - * - * DESCRIPTION: - * +/** * This routine attempts to receive a unit from the_semaphore. * 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_semaphore (in) is the semaphore to seize + * @param id (in) 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 + * to wait if @a wait is TRUE. */ - void _CORE_semaphore_Seize( CORE_semaphore_Control *the_semaphore, Objects_Id id, @@ -111,31 +147,34 @@ void _CORE_semaphore_Seize( Watchdog_Interval timeout ); -/* - * _CORE_semaphore_Surrender - * - * DESCRIPTION: - * +/** * This routine frees a unit to the semaphore. If a task was blocked waiting * for a unit from this semaphore, then that task will be readied and the unit * 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 + * with this instance of a SuperCore Semaphore + * @param api_semaphore_mp_support (in) is the routine to invoke if the + * thread unblocked is remote + * + * @return an indication of whether the routine succeeded or failed */ - CORE_semaphore_Status _CORE_semaphore_Surrender( CORE_semaphore_Control *the_semaphore, Objects_Id id, CORE_semaphore_API_mp_support_callout api_semaphore_mp_support ); -/* - * _CORE_semaphore_Flush - * - * DESCRIPTION: - * +/** * 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 + * thread unblocked is remote + * @param status (in) is the status to be returned to the unblocked thread */ - void _CORE_semaphore_Flush( CORE_semaphore_Control *the_semaphore, Thread_queue_Flush_callout remote_extract_callout, @@ -150,5 +189,7 @@ void _CORE_semaphore_Flush( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/heap.h b/cpukit/score/include/rtems/score/heap.h index 9b1387ecbf..0745fab95f 100644 --- a/cpukit/score/include/rtems/score/heap.h +++ b/cpukit/score/include/rtems/score/heap.h @@ -1,4 +1,5 @@ -/* heap.h +/** + * @file heap.h * * This include file contains the information pertaining to the Heap * Handler. A heap is a doubly linked list of variable size @@ -7,8 +8,10 @@ * coalescing neighbor blocks. Control information for both allocated * and unallocated blocks is contained in the heap space. A heap header * contains control information for the heap. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -21,104 +24,122 @@ #ifndef __RTEMS_HEAP_h #define __RTEMS_HEAP_h +/** + * @defgroup ScoreHeap Heap Handler + * + * This group contains functionality which provides the foundation + * Heap services used in all of the APIs supported by RTEMS. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif -/* +/** * Status codes for heap_extend */ - typedef enum { HEAP_EXTEND_SUCCESSFUL, HEAP_EXTEND_ERROR, HEAP_EXTEND_NOT_IMPLEMENTED } Heap_Extend_status; -/* +/** * Status codes for _Heap_Get_information */ - typedef enum { HEAP_GET_INFORMATION_SUCCESSFUL = 0, HEAP_GET_INFORMATION_SYSTEM_STATE_ERROR, HEAP_GET_INFORMATION_BLOCK_ERROR } Heap_Get_information_status; -/* +/** * Information block returned by _Heap_Get_information */ - typedef struct { + /** This field is the number of free blocks in this heap. */ uint32_t free_blocks; + /** This field is the amount of free memory in this heap. */ uint32_t free_size; + /** This field is the number of used blocks in this heap. */ uint32_t used_blocks; + /** This field is the amount of used memory in this heap. */ uint32_t used_size; } Heap_Information_block; -/* - * Constants used in the size/used field of each heap block to - * indicate when a block is free or in use. +/** + * This constant is used in the size/used field of each heap block to + * indicate when a block is in use. */ +#define HEAP_BLOCK_USED 1 -#define HEAP_BLOCK_USED 1 /* indicates block is in use */ -#define HEAP_BLOCK_FREE 0 /* indicates block is free */ +/** + * This constant is used in the size/used field of each heap block to + * indicate when a block is free. + */ +#define HEAP_BLOCK_FREE 0 -/* +/** * The size/used field value for the dummy front and back flags. */ - #define HEAP_DUMMY_FLAG (0 + HEAP_BLOCK_USED) /* * The following constants reflect various requirements of the * heap data structures which impact the management of a heap. * - * NOTE: Because free block overhead is greater than used block + * NOTE: Because free block overhead is greater than used block * overhead AND a portion of the allocated space is from * the extra free block overhead, the absolute lower bound * of the minimum fragment size is equal to the size of * the free block overhead. */ -#define HEAP_OVERHEAD \ - (sizeof( uint32_t ) * 2) /* size dummy first and last blocks */ -#define HEAP_BLOCK_USED_OVERHEAD \ - (sizeof( void * ) * 2) /* num bytes overhead in used block */ -#define HEAP_MINIMUM_SIZE \ - (HEAP_OVERHEAD + sizeof (Heap_Block)) - /* min number of bytes the user may */ - /* specify for the heap size */ +/** size dummy first and last blocks */ +#define HEAP_OVERHEAD (sizeof( uint32_t ) * 2) -/* +/** number of bytes of overhead in used block */ +#define HEAP_BLOCK_USED_OVERHEAD (sizeof( void * ) * 2) + +/** Minimum number of bytes the user may specify for the heap size */ +#define HEAP_MINIMUM_SIZE (HEAP_OVERHEAD + sizeof (Heap_Block)) + +/** + * Forward reference + * + * @ref Heap_Block + */ +typedef struct Heap_Block_struct Heap_Block; + +/** * The following defines the data structure used to manage * individual blocks in a heap. When the block is allocated, the * next and previous fields are not used by the Heap Handler * and thus the address returned for the block starts at * the address of the next field. * - * NOTE: The next and previous pointers are only valid when the + * @note The next and previous pointers are only valid when the * block is free. Caution must be exercised to insure that * allocated blocks are large enough to contain them and * that they are not accidentally overwritten when the * block is actually allocated. */ - -typedef struct Heap_Block_struct Heap_Block; - struct Heap_Block_struct { - uint32_t back_flag; /* size and status of prev block */ - uint32_t front_flag; /* size and status of block */ - Heap_Block *next; /* pointer to next block */ - Heap_Block *previous; /* pointer to previous block */ + /** size and status of prev block */ + uint32_t back_flag; + /** size and status of block */ + uint32_t front_flag; + /** pointer to next block */ + Heap_Block *next; + /** pointer to previous block */ + Heap_Block *previous; }; -/* +/** * The following defines the control block used to manage each heap. * - * NOTE: - * - * This structure is layed out such that it can be used a a dummy + * @note This structure is layed out such that it can be used a a dummy * first and last block on the free block chain. The extra padding * insures the dummy last block is the correct size. * @@ -126,29 +147,37 @@ struct Heap_Block_struct { * final. This is effectively the same trick as is used in the Chain * Handler. */ - typedef struct { - Heap_Block *start; /* first valid block address in heap */ - Heap_Block *final; /* last valid block address in heap */ - - Heap_Block *first; /* pointer to first block in heap */ - Heap_Block *permanent_null; /* always NULL pointer */ - Heap_Block *last; /* pointer to last block in heap */ - uint32_t page_size; /* allocation unit */ + /** first valid block address in heap */ + Heap_Block *start; + /** last valid block address in heap */ + Heap_Block *final; + + /** pointer to first block in heap */ + Heap_Block *first; + /** always NULL pointer */ + Heap_Block *permanent_null; + /** pointer to last block in heap */ + Heap_Block *last; + /** allocation unit */ + uint32_t page_size; + /** reserved field */ uint32_t reserved; } Heap_Control; -/* - * _Heap_Initialize - * - * DESCRIPTION: - * - * This routine initializes the_heap record to manage the - * contiguous heap of size bytes which starts at starting_address. +/** + * This routine initializes @a the_heap record to manage the + * contiguous heap of @a size bytes which starts at @a starting_address. * Blocks of memory are allocated from the heap in multiples of - * page_size byte units. + * @a page_size byte units. + * + * @param the_heap (in) is the heap to operate upon + * @param starting_address (in) 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 */ - uint32_t _Heap_Initialize( Heap_Control *the_heap, void *starting_address, @@ -156,15 +185,18 @@ uint32_t _Heap_Initialize( uint32_t page_size ); -/* - * _Heap_Extend +/** + * This routine grows @a the_heap memory area using the size bytes which + * begin at @a starting_address. * - * DESCRIPTION: - * - * This routine grows the_heap memory area using the size bytes which - * begin at starting_address. + * @param the_heap (in) is the heap to operate upon + * @param starting_address (in) 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 + * @return a status indicating success or the reason for failure + * @return *size filled in with the amount of memory added to the heap */ - Heap_Extend_status _Heap_Extend( Heap_Control *the_heap, void *starting_address, @@ -172,85 +204,75 @@ Heap_Extend_status _Heap_Extend( uint32_t *amount_extended ); -/* - * _Heap_Allocate - * - * DESCRIPTION: - * - * DESCRIPTION: - * +/** * This function attempts to allocate a block of size bytes from - * the_heap. If insufficient memory is free in the_heap to allocate + * @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 + * @return NULL if unsuccessful and a pointer to the block if successful */ - void *_Heap_Allocate( Heap_Control *the_heap, uint32_t size ); -/* - * _Heap_Size_of_user_area - * - * DESCRIPTION: - * +/** * This kernel routine sets size to the size of the given heap block. - * It returns TRUE if the starting_address is in the heap, and FALSE + * It returns TRUE if the @a starting_address is in @a 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 + * to obtain the size of + * @param size (in) 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 */ - boolean _Heap_Size_of_user_area( Heap_Control *the_heap, void *starting_address, uint32_t *size ); -/* - * _Heap_Free - * - * DESCRIPTION: - * +/** * This routine returns the block of memory which begins - * at starting_address to the_heap. Any coalescing which is + * 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 + * to free + * @return TRUE if successfully freed, FALSE otherwise */ - boolean _Heap_Free( Heap_Control *the_heap, void *start_address ); -/* - * _Heap_Walk - * - * DESCRIPTION: - * +/** * 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 */ - void _Heap_Walk( Heap_Control *the_heap, int source, boolean do_dump ); -/*PAGE - * - * _Heap_Get_information - * +/** * This kernel routine walks the heap and tots up the free and allocated * sizes. Derived from _Heap_Walk. * - * Input parameters: - * the_heap - pointer to heap header - * the_info - pointer to information block - * - * Output parameters: - * *the_info - status information - * return 0=success, otherwise heap is corrupt. + * @param the_heap (in) pointer to heap header + * @param the_info (in) pointer to a status information area + * @return *the_info is filled with status information + * @return 0=success, otherwise heap is corrupt. */ - - Heap_Get_information_status _Heap_Get_information( Heap_Control *the_heap, Heap_Information_block *the_info @@ -265,5 +287,7 @@ Heap_Get_information_status _Heap_Get_information( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/interr.h b/cpukit/score/include/rtems/score/interr.h index 536e30bef0..eb5c2b499c 100644 --- a/cpukit/score/include/rtems/score/interr.h +++ b/cpukit/score/include/rtems/score/interr.h @@ -1,10 +1,12 @@ -/* interr.h +/** + * @file interr.h * * This include file contains constants and prototypes related * to the Internal Error Handler. - * - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -17,15 +19,22 @@ #ifndef __RTEMS_INTERNAL_ERROR_h #define __RTEMS_INTERNAL_ERROR_h +/** + * @defgroup ScoreIntErr Internal Error Handler + * + * This group contains functionality which provides the foundation + * Semaphore services used in all of the APIs supported by RTEMS. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif -/* +/** * This type lists the possible sources from which an error * can be reported. */ - typedef enum { INTERNAL_ERROR_CORE, INTERNAL_ERROR_RTEMS_API, @@ -36,7 +45,6 @@ typedef enum { /* * A list of errors which are generated internally by the executive core. */ - typedef enum { INTERNAL_ERROR_NO_CONFIGURATION_TABLE, INTERNAL_ERROR_NO_CPU_TABLE, @@ -60,7 +68,6 @@ typedef enum { /* * This type holds the fatal error information. */ - typedef struct { Internal_errors_Source the_source; boolean is_internal; @@ -70,18 +77,13 @@ typedef struct { /* * When a fatal error occurs, the error information is stored here. */ - SCORE_EXTERN Internal_errors_Information Internal_errors_What_happened; -/* - * _Internal_error_Occurred - * - * DESCRIPTION: +/** @brief Internal error Occurred * * This routine is invoked when the application or the executive itself * determines that a fatal error has occurred. */ - void volatile _Internal_error_Occurred( Internal_errors_Source the_source, boolean is_internal, @@ -92,5 +94,7 @@ void volatile _Internal_error_Occurred( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h index 6064d1ed1e..a932eafcf7 100644 --- a/cpukit/score/include/rtems/score/isr.h +++ b/cpukit/score/include/rtems/score/isr.h @@ -1,11 +1,14 @@ -/* isr.h +/** + * @file isr.h * * This include file contains all the constants and structures associated * with the management of processor interrupt levels. This handler * supports interrupt critical sections, vectoring of user interrupt * handlers, nesting of interrupts, and manipulating interrupt levels. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -18,33 +21,37 @@ #ifndef __ISR_h #define __ISR_h +/** + * @defgroup ScoreISR ISR Handler + * + * This group contains functionality which provides the foundation + * ISR services used in all of the APIs supported by RTEMS. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif -/* +/** * The following type defines the control block used to manage * the interrupt level portion of the status register. */ - typedef uint32_t ISR_Level; -/* +/** * The following type defines the type used to manage the vectors. */ - typedef uint32_t ISR_Vector_number; -/* +/** * Return type for ISR Handler */ - typedef void ISR_Handler; -/* +/** * Pointer to an ISR Handler */ - #if (CPU_ISR_PASSES_FRAME_POINTER == 1) typedef ISR_Handler ( *ISR_Handler_entry )( ISR_Vector_number, @@ -55,82 +62,59 @@ typedef ISR_Handler ( *ISR_Handler_entry )( ISR_Vector_number ); #endif -/* + +/** * This constant promotes out the number of vectors truly supported by * the current CPU being used. This is usually the number of distinct vectors * the cpu can vector. */ - #define ISR_NUMBER_OF_VECTORS CPU_INTERRUPT_NUMBER_OF_VECTORS -/* +/** * This constant promotes out the highest valid interrupt vector number. */ - #define ISR_INTERRUPT_MAXIMUM_VECTOR_NUMBER CPU_INTERRUPT_MAXIMUM_VECTOR_NUMBER -/* +/** * The following is TRUE if signals have been sent to the currently * executing thread by an ISR handler. */ - SCORE_EXTERN boolean _ISR_Signals_to_thread_executing; -/* +/** * The following contains the interrupt service routine nest level. * When this variable is zero, a thread is executing. */ - SCORE_EXTERN volatile uint32_t _ISR_Nest_level; -/* +/** * The following declares the Vector Table. Application * interrupt service routines are vectored by the ISR Handler via this table. */ - SCORE_EXTERN ISR_Handler_entry *_ISR_Vector_table; -/* - * _ISR_Handler_initialization - * - * DESCRIPTION: - * +/** * This routine performs the initialization necessary for this handler. */ - void _ISR_Handler_initialization ( void ); -/* - * _ISR_Disable - * - * DESCRIPTION: - * +/** * This routine disables all interrupts so that a critical section * of code can be executing without being interrupted. Upon return, * the argument _level will contain the previous interrupt mask level. */ - #define _ISR_Disable( _level ) \ _CPU_ISR_Disable( _level ) -/* - * _ISR_Enable - * - * DESCRIPTION: - * +/** * This routine enables interrupts to the previous interrupt mask * LEVEL. It is used at the end of a critical section of code to * enable interrupts so they can be processed again. */ - #define _ISR_Enable( _level ) \ _CPU_ISR_Enable( _level ) -/* - * _ISR_Flash - * - * DESCRIPTION: - * +/** * This routine temporarily enables interrupts to the previous * interrupt mask level and then disables all interrupts so that * the caller can continue into the second part of a critical @@ -142,52 +126,32 @@ void _ISR_Handler_initialization ( void ); * must be selected with care to insure that the critical section * properly protects itself. */ - #define _ISR_Flash( _level ) \ _CPU_ISR_Flash( _level ) -/* - * _ISR_Install_vector - * - * DESCRIPTION: - * +/** * This routine installs new_handler as the interrupt service routine * for the specified vector. The previous interrupt service routine is * returned as old_handler. */ - #define _ISR_Install_vector( _vector, _new_handler, _old_handler ) \ _CPU_ISR_install_vector( _vector, _new_handler, _old_handler ) -/* - * _ISR_Get_level - * - * DESCRIPTION: - * +/** * This routine returns the current interrupt level. */ - #define _ISR_Get_level() \ _CPU_ISR_Get_level() -/* - * _ISR_Set_level - * - * DESCRIPTION: - * +/** * This routine sets the current interrupt level to that specified * by new_level. The new interrupt level is effective when the * routine exits. */ - #define _ISR_Set_level( _new_level ) \ _CPU_ISR_Set_level( _new_level ) -/* - * _ISR_Handler - * - * DESCRIPTION: - * +/** * This routine is the interrupt dispatcher. ALL interrupts * are vectored to this routine so that minimal context can be saved * and setup performed before the application's high-level language @@ -197,40 +161,28 @@ void _ISR_Handler_initialization ( void ); * insure that the necessary thread scheduling operations are * performed when the outermost interrupt service routine exits. * - * NOTE: Implemented in assembly language. + * @note Implemented in assembly language. */ - void _ISR_Handler( void ); -/* - * _ISR_Dispatch - * - * DESCRIPTION: - * +/** * This routine provides a wrapper so that the routine - * _Thread_Dispatch can be invoked when a reschedule is necessary + * @ref _Thread_Dispatch can be invoked when a reschedule is necessary * at the end of the outermost interrupt service routine. This * wrapper is necessary to establish the processor context needed * by _Thread_Dispatch and to save the processor context which is * corrupted by _Thread_Dispatch. This context typically consists * of registers which are not preserved across routine invocations. * - * NOTE: Implemented in assembly language. + * @note Implemented in assembly language. */ - void _ISR_Dispatch( void ); -/*PAGE - * - * _ISR_Is_in_progress - * - * DESCRIPTION: - * +/** * This function returns TRUE if the processor is currently servicing * and interrupt and FALSE otherwise. A return value of TRUE indicates * that the caller is an interrupt service routine, NOT a thread. The */ - #if (CPU_PROVIDES_ISR_IS_IN_PROGRESS == TRUE) boolean _ISR_Is_in_progress( void ); #else @@ -244,5 +196,7 @@ boolean _ISR_Is_in_progress( void ); } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/mpci.h b/cpukit/score/include/rtems/score/mpci.h index 118e31afaa..da5636957d 100644 --- a/cpukit/score/include/rtems/score/mpci.h +++ b/cpukit/score/include/rtems/score/mpci.h @@ -1,9 +1,12 @@ -/* mpci.h +/** + * @file mpci.h * * This include file contains all the constants and structures associated * with the MPCI layer. It provides mechanisms to utilize packets. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,6 +19,13 @@ #ifndef __MPCI_h #define __MPCI_h +/** + * @defgroup ScoreMPCI MPCI Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -32,7 +42,6 @@ extern "C" { * The following constants define the stack size requirements for * the system threads. */ - #define MPCI_RECEIVE_SERVER_STACK_SIZE \ ( STACK_MINIMUM_SIZE + \ CPU_MPCI_RECEIVE_SERVER_EXTRA_STACK + \ @@ -42,7 +51,6 @@ extern "C" { /* * The following defines the node number used when a broadcast is desired. */ - #define MPCI_ALL_NODES 0 /* @@ -51,7 +59,6 @@ extern "C" { * the MPCI driver sets an upper limit on how long a remote request * should take to complete. */ - #define MPCI_DEFAULT_TIMEOUT 0xFFFFFFFF /* @@ -63,268 +70,224 @@ extern "C" { * 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 + */ typedef MPCI_Entry ( *MPCI_initialization_entry )( void ); +/** + * This type is XXX + */ typedef MPCI_Entry ( *MPCI_get_packet_entry )( MP_packet_Prefix ** ); +/** + * This type is XXX + */ typedef MPCI_Entry ( *MPCI_return_packet_entry )( MP_packet_Prefix * ); +/** + * This type is XXX + */ typedef MPCI_Entry ( *MPCI_send_entry )( uint32_t , MP_packet_Prefix * ); +/** + * This type is XXX + */ typedef MPCI_Entry ( *MPCI_receive_entry )( MP_packet_Prefix ** ); +/** + * This type is XXX + */ typedef struct { - uint32_t default_timeout; /* in ticks */ + /** timeout for MPCI operations in ticks */ + uint32_t default_timeout; + /** XXX */ uint32_t maximum_packet_size; + /** XXX */ MPCI_initialization_entry initialization; + /** XXX */ MPCI_get_packet_entry get_packet; + /** XXX */ MPCI_return_packet_entry return_packet; + /** XXX */ MPCI_send_entry send_packet; + /** XXX */ MPCI_receive_entry receive_packet; } MPCI_Control; -/* +/** * The following defines the type for packet processing routines * invoked by the MPCI Receive server. */ - typedef void (*MPCI_Packet_processor)( MP_packet_Prefix * ); -/* +/** * The following enumerated type defines the list of * internal MP operations. */ - typedef enum { MPCI_PACKETS_SYSTEM_VERIFY = 0 } MPCI_Internal_Remote_operations; -/* +/** * The following data structure defines the packet used to perform * remote event operations. */ - typedef struct { + /** XXX */ MP_packet_Prefix Prefix; + /** XXX */ MPCI_Internal_Remote_operations operation; + /** XXX */ uint32_t maximum_nodes; + /** XXX */ uint32_t maximum_global_objects; } MPCI_Internal_packet; -/* +/** * This is the core semaphore which the MPCI Receive Server blocks on. */ - SCORE_EXTERN CORE_semaphore_Control _MPCI_Semaphore; -/* + +/** * The following thread queue is used to maintain a list of tasks * which currently have outstanding remote requests. */ - SCORE_EXTERN Thread_queue_Control _MPCI_Remote_blocked_threads; -/* +/** * The following define the internal pointers to the user's * configuration information. */ - SCORE_EXTERN MPCI_Control *_MPCI_table; -/* +/** * The following points to the MPCI Receive Server. */ - SCORE_EXTERN Thread_Control *_MPCI_Receive_server_tcb; -/* +/** * The following table contains the process packet routines provided * by each object that supports MP operations. */ - SCORE_EXTERN MPCI_Packet_processor _MPCI_Packet_processors[MP_PACKET_CLASSES_LAST+1]; -/* - * _MPCI_Handler_initialization - * - * DESCRIPTION: - * +/** * This routine performs the initialization necessary for this handler. */ - void _MPCI_Handler_initialization( MPCI_Control *users_mpci_table, uint32_t timeout_status ); -/* - * _MPCI_Create_server - * - * DESCRIPTION: - * +/** * This routine creates the packet receive server used in MP systems. */ - void _MPCI_Create_server( void ); -/* - * _MPCI_Initialization - * - * DESCRIPTION: - * +/** * This routine initializes the MPCI driver by * invoking the user provided MPCI initialization callout. */ - void _MPCI_Initialization ( void ); -/* - * _MPCI_Register_packet_processor - * - * DESCRIPTION: - * +/** * This routine registers the MPCI packet processor for the * designated object class. */ - void _MPCI_Register_packet_processor( MP_packet_Classes the_class, MPCI_Packet_processor the_packet_processor ); -/* - * _MPCI_Get_packet - * - * DESCRIPTION: - * +/** * This function obtains a packet by invoking the user provided * MPCI get packet callout. */ - MP_packet_Prefix *_MPCI_Get_packet ( void ); -/* - * _MPCI_Return_packet - * - * DESCRIPTION: - * +/** * This routine returns a packet by invoking the user provided * MPCI return packet callout. */ - void _MPCI_Return_packet ( MP_packet_Prefix *the_packet ); -/* - * _MPCI_Send_process_packet - * - * DESCRIPTION: - * +/** * This routine sends a process packet by invoking the user provided * MPCI send callout. */ - void _MPCI_Send_process_packet ( uint32_t destination, MP_packet_Prefix *the_packet ); -/* - * _MPCI_Send_request_packet - * - * DESCRIPTION: - * +/** * This routine sends a request packet by invoking the user provided * MPCI send callout. */ - uint32_t _MPCI_Send_request_packet ( uint32_t destination, MP_packet_Prefix *the_packet, States_Control extra_state ); -/* - * _MPCI_Send_response_packet - * - * DESCRIPTION: - * +/** * This routine sends a response packet by invoking the user provided * MPCI send callout. */ - void _MPCI_Send_response_packet ( uint32_t destination, MP_packet_Prefix *the_packet ); -/* - * _MPCI_Receive_packet - * - * DESCRIPTION: - * +/** * This routine receives a packet by invoking the user provided * MPCI receive callout. */ - MP_packet_Prefix *_MPCI_Receive_packet ( void ); -/* - * _MPCI_Process_response - * - * DESCRIPTION: - * +/** * This routine obtains a packet by invoking the user provided * MPCI get packet callout. */ - Thread_Control *_MPCI_Process_response ( MP_packet_Prefix *the_packet ); -/*PAGE - * - * _MPCI_Receive_server - * +/** + * This is the server thread which receives and processes all MCPI packets. */ - Thread _MPCI_Receive_server( uint32_t ignored ); -/*PAGE - * - * _MPCI_Announce - * - * DESCRIPTION: - * - * XXX +/** + * This routine informs RTEMS of the availability of an MPCI packet. */ - void _MPCI_Announce ( void ); -/* - * _MPCI_Internal_packets_Send_process_packet - * - * DESCRIPTION: - * +/** * This routine performs a remote procedure call so that a * process operation can be performed on another node. */ - void _MPCI_Internal_packets_Send_process_packet ( MPCI_Internal_Remote_operations operation ); @@ -332,8 +295,6 @@ void _MPCI_Internal_packets_Send_process_packet ( /* * _MPCI_Internal_packets_Send_request_packet * - * DESCRIPTION: - * * This routine performs a remote procedure call so that a * directive operation can be initiated on another node. * @@ -344,8 +305,6 @@ void _MPCI_Internal_packets_Send_process_packet ( /* * _MPCI_Internal_packets_Send_response_packet * - * DESCRIPTION: - * * This routine performs a remote procedure call so that a * directive can be performed on another node. * @@ -353,16 +312,10 @@ void _MPCI_Internal_packets_Send_process_packet ( * packets to be sent by this manager. */ -/* - * - * _MPCI_Internal_packets_Process_packet - * - * DESCRIPTION: - * +/** * This routine performs the actions specific to this package for * the request from another node. */ - void _MPCI_Internal_packets_Process_packet ( MP_packet_Prefix *the_packet_prefix ); @@ -370,8 +323,6 @@ void _MPCI_Internal_packets_Process_packet ( /* * _MPCI_Internal_packets_Send_object_was_deleted * - * DESCRIPTION: - * * This routine is invoked indirectly by the thread queue * when a proxy has been removed from the thread queue and * the remote node must be informed of this. @@ -383,8 +334,6 @@ void _MPCI_Internal_packets_Process_packet ( /* * _MPCI_Internal_packets_Send_extract_proxy * - * DESCRIPTION: - * * This routine is invoked when a task is deleted and it * has a proxy which must be removed from a thread queue and * the remote node must be informed of this. @@ -393,19 +342,16 @@ void _MPCI_Internal_packets_Process_packet ( * deleted by this manager. */ -/* - * _MPCI_Internal_packets_Get_packet - * - * DESCRIPTION: - * +/** * This routine is used to obtain a internal threads mp packet. */ - - MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void ); +MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void ); #ifdef __cplusplus } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/mppkt.h b/cpukit/score/include/rtems/score/mppkt.h index 3c70225cc1..515d67150f 100644 --- a/cpukit/score/include/rtems/score/mppkt.h +++ b/cpukit/score/include/rtems/score/mppkt.h @@ -1,13 +1,15 @@ -/* mppkt.h +/** + * @file mppkt.h * * This package is the specification for the Packet Handler. * This handler defines the basic packet and provides * mechanisms to utilize packets based on this prefix. * Packets are the fundamental basis for messages passed between * nodes in an MP system. - * - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -20,6 +22,13 @@ #ifndef __MP_PACKET_h #define __MP_PACKET_h +/** + * @defgroup ScoreMPPacket MP Packet Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -28,14 +37,13 @@ extern "C" { #include <rtems/score/priority.h> #include <rtems/score/watchdog.h> -/* +/** * The following enumerated type defines the packet classes. * - * NOTE: In general, each class corresponds to a manager + * @note In general, each class corresponds to a manager * which supports global operations. Each manager * defines the set of supported operations. */ - typedef enum { MP_PACKET_MPCI_INTERNAL = 0, MP_PACKET_TASKS = 1, @@ -47,43 +55,55 @@ typedef enum { MP_PACKET_SIGNAL = 7 } MP_packet_Classes; +/** + * XXX + */ #define MP_PACKET_CLASSES_FIRST MP_PACKET_MPCI_INTERNAL + +/** + * XXX + */ #define MP_PACKET_CLASSES_LAST MP_PACKET_SIGNAL -/* +/** * The following record contains the prefix for every packet * passed between nodes in an MP system. * - * NOTE: This structure is padded to ensure that anything following it + * @note This structure is padded to ensure that anything following it * is on a 16 byte boundary. This is the most stringent structure * alignment rule encountered yet. */ - typedef struct { + /** XXX */ MP_packet_Classes the_class; + /** XXX */ Objects_Id id; + /** XXX */ Objects_Id source_tid; + /** XXX */ Priority_Control source_priority; + /** XXX */ uint32_t return_code; + /** XXX */ uint32_t length; + /** XXX */ uint32_t to_convert; + /** XXX */ Watchdog_Interval timeout; } MP_packet_Prefix; -/* +/** * An MPCI must support packets of at least this size. */ - #define MP_PACKET_MINIMUM_PACKET_SIZE 64 -/* +/** * The following constant defines the number of uint32_t 's * in a packet which must be converted to native format in a * heterogeneous system. In packets longer than * MP_PACKET_MINIMUN_HETERO_CONVERSION uint32_t 's, some of the "extra" data * may a user message buffer which is not automatically endian swapped. */ - #define MP_PACKET_MINIMUN_HETERO_CONVERSION \ ( sizeof( MP_packet_Prefix ) / sizeof( uint32_t ) ) @@ -95,5 +115,7 @@ typedef struct { } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/objectmp.h b/cpukit/score/include/rtems/score/objectmp.h index 947b03c59d..cf6a4d68d2 100644 --- a/cpukit/score/include/rtems/score/objectmp.h +++ b/cpukit/score/include/rtems/score/objectmp.h @@ -1,9 +1,12 @@ -/* objectmp.h +/** + * @file objectmp.h * * This include file contains all the constants and structures associated * with the manipulation of Global RTEMS Objects. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,6 +19,13 @@ #ifndef __RTEMS_OBJECTS_MP_h #define __RTEMS_OBJECTS_MP_h +/** + * @defgroup ScoreObjectMP Object Handler Multiprocessing Support + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -24,33 +34,24 @@ extern "C" { * This defines the Global Object Control Block used to manage * objects resident on other nodes. */ - typedef struct { Objects_Control Object; uint32_t name; /* XXX broken but works */ /* XXX If any API is MP with variable length names .. BOOM!!!! */ } Objects_MP_Control; -/* - * _Objects_MP_Handler_initialization - * - * DESCRIPTION: +/** @brief Objects MP Handler initialization * * This routine intializes the inactive global object chain * based on the maximum number of global objects configured. */ - void _Objects_MP_Handler_initialization ( uint32_t node, uint32_t maximum_nodes, uint32_t maximum_global_objects ); -/*PAGE - * - * _Objects_MP_Open - * - * DESCRIPTION: +/** @brief Objects MP Open * * This routine place the specified global object in the * specified information table. @@ -63,17 +64,13 @@ void _Objects_MP_Open ( Objects_Id the_id ); -/* - * _Objects_MP_Allocate_and_open - * - * DESCRIPTION: +/** @brief Objects MP Allocate and open * * This routine allocates a global object control block * and places it in the specified information table. If the * allocation fails, then is_fatal_error determines the * error processing actions taken. */ - boolean _Objects_MP_Allocate_and_open ( Objects_Information *information, uint32_t the_name, /* XXX -- wrong for variable length */ @@ -81,30 +78,22 @@ boolean _Objects_MP_Allocate_and_open ( boolean is_fatal_error ); -/* - * _Objects_MP_Close - * - * DESCRIPTION: +/** @brief Objects MP Close * * This routine removes a global object from the specified * information table and deallocates the global object control block. */ - void _Objects_MP_Close ( Objects_Information *information, Objects_Id the_id ); -/* - * _Objects_MP_Global_name_search - * - * DESCRIPTION: +/** @brief Objects MP Global name search * * 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. */ - Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( Objects_Information *information, Objects_Name the_name, @@ -112,10 +101,7 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( Objects_Id *the_id ); -/* - * _Objects_MP_Is_remote - * - * DESCRIPTION: +/** @brief Objects MP Is remote * * This function searches the Global Object Table managed * by information for the object indicated by ID. If the object @@ -123,7 +109,6 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search ( * location is set to objects_error. In both cases, the_object * is undefined. */ - void _Objects_MP_Is_remote ( Objects_Information *information, Objects_Id the_id, @@ -135,7 +120,6 @@ void _Objects_MP_Is_remote ( * 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; @@ -147,5 +131,7 @@ SCORE_EXTERN Chain_Control _Objects_MP_Inactive_global_objects; } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/priority.h b/cpukit/score/include/rtems/score/priority.h index 3c8454f203..9ab1bc3c8c 100644 --- a/cpukit/score/include/rtems/score/priority.h +++ b/cpukit/score/include/rtems/score/priority.h @@ -1,10 +1,13 @@ -/* priority.h +/** + * @file priority.h * * This include file contains all thread priority manipulation routines. * This Handler provides mechanisms which can be used to * initialize and manipulate thread priorities. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -17,6 +20,13 @@ #ifndef __PRIORITY_h #define __PRIORITY_h +/** + * @defgroup ScorePriority Priority Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -25,7 +35,7 @@ extern "C" { * The following type defines the control block used to manage * thread priorities. * - * NOTE: Priority 0 is reserved for internal threads only. + * @note Priority 0 is reserved for internal threads only. */ typedef uint32_t Priority_Control; @@ -69,7 +79,7 @@ SCORE_EXTERN Priority_Bit_map_control /* * Priority Bitfield Manipulation Routines * - * NOTE: + * @note * * These may simply be pass throughs to CPU dependent routines. */ @@ -92,5 +102,7 @@ SCORE_EXTERN Priority_Bit_map_control } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/stack.h b/cpukit/score/include/rtems/score/stack.h index 16c01f7ea3..39c8f94cc0 100644 --- a/cpukit/score/include/rtems/score/stack.h +++ b/cpukit/score/include/rtems/score/stack.h @@ -1,10 +1,13 @@ -/* stack.h +/** + * @file stack.h * * This include file contains all information about the thread * Stack Handler. This Handler provides mechanisms which can be used to * initialize and utilize stacks. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -17,6 +20,13 @@ #ifndef __STACK_h #define __STACK_h +/** + * @defgroup ScoreStack Stack Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -45,5 +55,7 @@ typedef struct { } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/states.h b/cpukit/score/include/rtems/score/states.h index 59d27c274e..0ed5db73b1 100644 --- a/cpukit/score/include/rtems/score/states.h +++ b/cpukit/score/include/rtems/score/states.h @@ -1,8 +1,11 @@ -/* states.h +/** + * @file states.h * * This include file contains thread execution state information. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -15,6 +18,13 @@ #ifndef __RTEMS_STATES_h #define __RTEMS_STATES_h +/** + * @defgroup ScoreStates Thread States Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -79,5 +89,7 @@ typedef uint32_t States_Control; } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/sysstate.h b/cpukit/score/include/rtems/score/sysstate.h index 2f0636399b..3302be767c 100644 --- a/cpukit/score/include/rtems/score/sysstate.h +++ b/cpukit/score/include/rtems/score/sysstate.h @@ -1,8 +1,11 @@ -/* sysstates.h +/** + * @file sysstate.h * * This include file contains information regarding the system state. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -15,6 +18,13 @@ #ifndef __RTEMS_SYSTEM_STATE_h #define __RTEMS_SYSTEM_STATE_h +/** + * @defgroup ScoreSysState System State Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -62,5 +72,7 @@ SCORE_EXTERN System_state_Codes _System_state_Current; } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index 8090656461..3e9fb9335e 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -1,9 +1,12 @@ -/* thread.h +/** + * @file thread.h * * This include file contains all constants and structures associated * with the thread control block. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,6 +19,13 @@ #ifndef __THREAD_h #define __THREAD_h +/** + * @defgroup ScoreThread Thread Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -33,25 +43,23 @@ extern "C" { #include <rtems/score/tqdata.h> #include <rtems/score/watchdog.h> -/* +/** * The following defines the "return type" of a thread. * - * NOTE: This cannot always be right. Some APIs have void + * @note This cannot always be right. Some APIs have void * tasks/threads, others return pointers, others may * return a numeric value. Hopefully a pointer is * always at least as big as an uint32_t . :) */ - typedef void *Thread; -/* +/** * The following defines the ways in which the entry point for a * thread can be invoked. Basically, it can be passed any * combination/permutation of a pointer and an uint32_t value. * - * NOTE: For now, we are ignoring the return type. + * @note For now, we are ignoring the return type. */ - typedef enum { THREAD_START_NUMERIC, THREAD_START_POINTER, @@ -59,21 +67,31 @@ typedef enum { THREAD_START_BOTH_NUMERIC_FIRST } Thread_Start_types; +/** + */ typedef Thread ( *Thread_Entry )(); /* basic type */ typedef Thread ( *Thread_Entry_numeric )( uint32_t ); + +/** + */ typedef Thread ( *Thread_Entry_pointer )( void * ); + +/** + */ typedef Thread ( *Thread_Entry_both_pointer_first )( void *, uint32_t ); + +/** + */ typedef Thread ( *Thread_Entry_both_numeric_first )( uint32_t , void * ); -/* +/** * The following lists the algorithms used to manage the thread cpu budget. * * Reset Timeslice: At each context switch, reset the time quantum. * Exhaust Timeslice: Only reset the quantum once it is consumed. * Callout: Execute routine when budget is consumed. */ - typedef enum { THREAD_CPU_BUDGET_ALGORITHM_NONE, THREAD_CPU_BUDGET_ALGORITHM_RESET_TIMESLICE, @@ -81,31 +99,47 @@ typedef enum { THREAD_CPU_BUDGET_ALGORITHM_CALLOUT } Thread_CPU_budget_algorithms; +/** + */ typedef struct Thread_Control_struct Thread_Control; +/** + */ typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * ); -/* - * Per task variable structure +/** @brief Per Task Variable Manager Structure Forward Reference + * + * Forward reference to the per task variable structure. */ - struct rtems_task_variable_tt; +/** @brief Per Task Variable Manager Structure + * + * This is the internal structure used to manager per Task Variables. + */ struct rtems_task_variable_tt { + /** 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 + * task variable. + */ void **ptr; + /** This field is to the global value for this per task variable. */ void *gval; + /** This field is to this thread's value for this per task variable. */ 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; -/* +/** * 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 */ @@ -125,38 +159,50 @@ typedef struct { void *stack; /* initial stack area address */ } Thread_Start_information; -/* +/** * The following structure contains the information necessary to manage * a thread which it is waiting for a resource. */ - #define THREAD_STATUS_PROXY_BLOCKING 0x1111111 +/** @brief Thread Blocking Management Information + * + * This contains the information required to manage a thread while it is + * blocked and to return information to it. + */ typedef struct { - Objects_Id id; /* waiting on this object */ - uint32_t count; /* "generic" fields to be used */ - void *return_argument; /* when blocking */ + /** This field is the Id of the object this thread is waiting upon. */ + Objects_Id id; + /** This field is used to return an integer while when blocked. */ + uint32_t count; + /** This field is the first pointer to a user return argument. */ + void *return_argument; + /** This field is the second pointer to a user return argument. */ void *return_argument_1; + /** This field contains any options in effect on this blocking operation. */ uint32_t option; - - /* - * NOTE: The following assumes that all API return codes can be - * treated as an uint32_t . + /** This field will contain the return status from a blocking operation. + * + * @note The following assumes that all API return codes can be + * treated as an uint32_t. */ - uint32_t return_code; /* status for thread awakened */ + uint32_t return_code; - Chain_Control Block2n; /* 2 - n priority blocked chain */ - Thread_queue_Control *queue; /* pointer to thread queue */ + /** This field is the chain header for the second through Nth tasks + * of the same priority blocked waiting on the same object. + */ + Chain_Control Block2n; + /** This field points to the thread queue on which this thread is blocked. */ + Thread_queue_Control *queue; } Thread_Wait_information; -/* +/** * The following defines the control block used to manage * each thread proxy. * - * NOTE: It is critical that proxies and threads have identical + * @note It is critical that proxies and threads have identical * memory images for the shared part. */ - typedef struct { Objects_Control Object; States_Control current_state; @@ -172,24 +218,29 @@ typedef struct { Chain_Node Active; } Thread_Proxy_control; - -/* +/** * The following record defines the control block used * to manage each thread. * - * NOTE: It is critical that proxies and threads have identical + * @note It is critical that proxies and threads have identical * memory images for the shared part. */ - typedef enum { THREAD_API_RTEMS, THREAD_API_POSIX, THREAD_API_ITRON } Thread_APIs; +/** + */ #define THREAD_API_FIRST THREAD_API_RTEMS + +/** + */ #define THREAD_API_LAST THREAD_API_ITRON +/** + */ struct Thread_Control_struct { Objects_Control Object; States_Control current_state; @@ -226,98 +277,86 @@ struct Thread_Control_struct { rtems_task_variable_t *task_variables; }; -/* +/** * Self for the GNU Ada Run-Time */ - SCORE_EXTERN void *rtems_ada_self; -/* +/** * The following defines the information control block used to * manage this class of objects. */ - SCORE_EXTERN Objects_Information _Thread_Internal_information; -/* +/** * The following define the thread control pointers used to access * and manipulate the idle thread. */ - SCORE_EXTERN Thread_Control *_Thread_Idle; -/* +/** * The following context area contains the context of the "thread" * which invoked the start multitasking routine. This context is * restored as the last action of the stop multitasking routine. Thus * control of the processor can be returned to the environment * which initiated the system. */ - 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. */ - SCORE_EXTERN volatile uint32_t _Thread_Dispatch_disable_level; -/* +/** * If this is non-zero, then the post-task switch extension * is run regardless of the state of the per thread flag. */ - SCORE_EXTERN uint32_t _Thread_Do_post_task_switch_extension; -/* +/** * The following holds how many user extensions are in the system. This * is used to determine how many user extension data areas to allocate * per thread. */ - SCORE_EXTERN uint32_t _Thread_Maximum_extensions; -/* +/** * The following is used to manage the length of a timeslice quantum. */ - SCORE_EXTERN uint32_t _Thread_Ticks_per_timeslice; -/* +/** * The following points to the array of FIFOs used to manage the * set of ready threads. */ - SCORE_EXTERN Chain_Control *_Thread_Ready_chain; -/* +/** * The following points to the thread which is currently executing. * This thread is implicitly manipulated by numerous directives. */ - SCORE_EXTERN Thread_Control *_Thread_Executing; -/* +/** * The following points to the highest priority ready thread * in the system. Unless the current thread is not preemptibl, * then this thread will be context switched to when the next * dispatch occurs. */ - SCORE_EXTERN Thread_Control *_Thread_Heir; -/* +/** * The following points to the thread whose floating point * context is currently loaded. */ - #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE ) SCORE_EXTERN Thread_Control *_Thread_Allocated_fp; #endif -/* +/** * The C library re-enter-rant global pointer. Some C library implementations * such as newlib have a single global pointer that changed during a context * switch. The pointer points to that global pointer. The Thread control block @@ -325,49 +364,30 @@ SCORE_EXTERN Thread_Control *_Thread_Allocated_fp; */ SCORE_EXTERN struct _reent **_Thread_libc_reent; -/* - * _Thread_Handler_initialization - * - * DESCRIPTION: - * +/** * This routine performs the initialization necessary for this handler. */ - void _Thread_Handler_initialization ( uint32_t ticks_per_timeslice, uint32_t maximum_extensions, uint32_t maximum_proxies ); -/* - * _Thread_Create_idle - * - * DESCRIPTION: - * +/** * This routine creates the idle thread. * - * WARNING!! No thread should be created before this one. + * @warning No thread should be created before this one. */ - void _Thread_Create_idle( void ); -/* - * _Thread_Start_multitasking - * - * DESCRIPTION: - * +/** * This routine initiates multitasking. It is invoked only as * part of initialization and its invocation is the last act of * the non-multitasking part of the system initialization. */ - void _Thread_Start_multitasking( void ); -/* - * _Thread_Dispatch - * - * DESCRIPTION: - * +/** * This routine is responsible for transferring control of the * processor from the executing thread to the heir thread. As part * of this process, it is responsible for the following actions: @@ -376,21 +396,13 @@ void _Thread_Start_multitasking( void ); * + restoring the context of the heir thread * + dispatching any signals for the resulting executing thread */ - void _Thread_Dispatch( void ); -/* - * _Thread_Stack_Allocate - * - * DESCRIPTION: - * +/** * Allocate the requested stack space for the thread. * return the actual size allocated after any adjustment * or return zero if the allocation failed. * Set the Start.stack field to the address of the stack - * - * NOTES: NONE - * */ uint32_t _Thread_Stack_Allocate( @@ -398,38 +410,24 @@ uint32_t _Thread_Stack_Allocate( uint32_t stack_size ); -/* - * _Thread_Stack_Free - * - * DESCRIPTION: - * +/** * Deallocate the Thread's stack. - * NOTES: NONE - * */ - void _Thread_Stack_Free( Thread_Control *the_thread ); -/* - * _Thread_Initialize - * - * DESCRIPTION: - * +/** * This routine initializes the specified the thread. It allocates * all memory associated with this thread. It completes by adding * the thread to the local object table so operations on this * thread id are allowed. * - * NOTES: + * @note If stack_area is NULL, it is allocated from the workspace. * - * If stack_area is NULL, it is allocated from the workspace. - * - * If the stack is allocated from the workspace, then it is guaranteed to be - * of at least minimum size. + * @note If the stack is allocated from the workspace, then it is + * guaranteed to be of at least minimum size. */ - boolean _Thread_Initialize( Objects_Information *information, Thread_Control *the_thread, @@ -444,16 +442,11 @@ boolean _Thread_Initialize( Objects_Name name ); -/* - * _Thread_Start - * - * DESCRIPTION: - * +/** * This routine initializes the executable information for a thread * and makes it ready to execute. After this routine executes, the * thread competes with all other threads for CPU time. */ - boolean _Thread_Start( Thread_Control *the_thread, Thread_Start_types the_prototype, @@ -462,118 +455,78 @@ boolean _Thread_Start( uint32_t numeric_argument ); -/* - * _Thread_Restart - * - * DESCRIPTION: - * +/** * This support routine restarts the specified task in a way that the * next time this thread executes, it will begin execution at its * original starting point. + * + * TODO: multiple task arg profiles */ - -/* XXX multiple task arg profiles */ - boolean _Thread_Restart( Thread_Control *the_thread, void *pointer_argument, uint32_t numeric_argument ); -/* - * _Thread_Reset - * - * DESCRIPTION: - * +/** * This routine resets a thread to its initial state but does * not restart it. */ - void _Thread_Reset( Thread_Control *the_thread, void *pointer_argument, uint32_t numeric_argument ); -/* - * _Thread_Close - * - * DESCRIPTION: - * +/** * This routine frees all memory associated with the specified * thread and removes it from the local object table so no further * operations on this thread are allowed. */ - void _Thread_Close( Objects_Information *information, Thread_Control *the_thread ); -/* - * _Thread_Ready - * - * DESCRIPTION: - * +/** * This routine removes any set states for the_thread. It performs * any necessary scheduling operations including the selection of * a new heir thread. */ - void _Thread_Ready( Thread_Control *the_thread ); -/* - * _Thread_Clear_state - * - * DESCRIPTION: - * +/** * This routine clears the indicated STATES for the_thread. It performs * any necessary scheduling operations including the selection of * a new heir thread. */ - void _Thread_Clear_state( Thread_Control *the_thread, States_Control state ); -/* - * _Thread_Set_state - * - * DESCRIPTION: - * +/** * This routine sets the indicated states for the_thread. It performs * any necessary scheduling operations including the selection of * a new heir thread. - * */ - void _Thread_Set_state( Thread_Control *the_thread, States_Control state ); -/* - * _Thread_Set_transient - * - * DESCRIPTION: - * +/** * This routine sets the TRANSIENT state for the_thread. It performs * any necessary scheduling operations including the selection of * a new heir thread. */ - void _Thread_Set_transient( Thread_Control *the_thread ); -/* - * _Thread_Reset_timeslice - * - * DESCRIPTION: - * +/** * This routine is invoked upon expiration of the currently * executing thread's timeslice. If no other thread's are ready * at the priority of the currently executing thread, then the @@ -581,198 +534,131 @@ void _Thread_Set_transient( * currently executing thread is placed at the rear of the * FIFO for this priority and a new heir is selected. */ - void _Thread_Reset_timeslice( void ); -/* - * _Thread_Tickle_timeslice - * - * DESCRIPTION: - * +/** * This routine is invoked as part of processing each clock tick. * It is responsible for determining if the current thread allows * timeslicing and, if so, when its timeslice expires. */ - void _Thread_Tickle_timeslice( void ); -/* - * _Thread_Yield_processor - * - * DESCRIPTION: - * +/** * This routine is invoked when a thread wishes to voluntarily * transfer control of the processor to another thread of equal * or greater priority. */ - void _Thread_Yield_processor( void ); -/* - * _Thread_Rotate_Ready_Queue - * - * DESCRIPTION: - * +/** * This routine is invoked to rotate the ready queue for the * given priority. It can be used to yeild the processor * by rotating the executing threads ready queue. */ - void _Thread_Rotate_Ready_Queue( Priority_Control priority ); -/* - * _Thread_Load_environment - * - * DESCRIPTION: - * +/** * This routine initializes the context of the_thread to its * appropriate starting state. */ - void _Thread_Load_environment( Thread_Control *the_thread ); -/* - * _Thread_Handler - * - * DESCRIPTION: - * +/** * This routine is the wrapper function for all threads. It is * the starting point for all threads. The user provided thread * entry point is invoked by this routine. Operations * which must be performed immediately before and after the user's * thread executes are found here. */ - void _Thread_Handler( void ); -/* - * _Thread_Delay_ended - * - * DESCRIPTION: - * +/** * This routine is invoked when a thread must be unblocked at the * end of a time based delay (i.e. wake after or wake when). */ - void _Thread_Delay_ended( Objects_Id id, void *ignored ); -/* - * _Thread_Change_priority - * - * DESCRIPTION: - * +/** * This routine changes the current priority of the_thread to * new_priority. It performs any necessary scheduling operations * including the selection of a new heir thread. */ - void _Thread_Change_priority ( Thread_Control *the_thread, Priority_Control new_priority, boolean prepend_it ); -/* - * _Thread_Set_priority - * - * DESCRIPTION: - * +/** * This routine updates the priority related fields in the_thread * control block to indicate the current priority is now new_priority. */ - void _Thread_Set_priority( Thread_Control *the_thread, Priority_Control new_priority ); -/* - * _Thread_Suspend - * - * DESCRIPTION: - * +/** * This routine updates the related suspend fields in the_thread * control block to indicate the current nested level. */ - void _Thread_Suspend( Thread_Control *the_thread ); -/* - * _Thread_Resume - * - * DESCRIPTION: - * +/** * This routine updates the related suspend fields in the_thread * control block to indicate the current nested level. A force * parameter of TRUE will force a resume and clear the suspend count. */ - void _Thread_Resume( Thread_Control *the_thread, boolean force ); -/* - * _Thread_Evaluate_mode - * - * DESCRIPTION: - * +/** * This routine evaluates the current scheduling information for the * system and determines if a context switch is required. This * is usually called after changing an execution mode such as preemptability * for a thread. */ - boolean _Thread_Evaluate_mode( void ); -/* - * _Thread_Get - * - * NOTE: If we are not using static inlines, this must be a real +#ifndef RTEMS_INLINES +/** + * @note If we are not using static inlines, this must be a real * subroutine call. */ - -#ifndef RTEMS_INLINES Thread_Control *_Thread_Get ( Objects_Id id, Objects_Locations *location ); #endif -/* - * _Thread_Idle_body - * - * DESCRIPTION: - * +#if (CPU_PROVIDES_IDLE_THREAD_BODY == FALSE) +/** * This routine is the body of the system idle thread. */ - -#if (CPU_PROVIDES_IDLE_THREAD_BODY == FALSE) Thread _Thread_Idle_body( uint32_t ignored ); #endif -/* - * rtems_iterate_over_all_tasks - * - * DESCRIPTION: - * - * This routine iterates over all threads regardless of API and - * invokes the specified routine. +/** */ - typedef void (*rtems_per_thread_routine)( Thread_Control * ); +/** + * This routine iterates over all threads regardless of API and + * invokes the specified routine. + */ void rtems_iterate_over_all_threads( rtems_per_thread_routine routine ); @@ -788,5 +674,7 @@ void rtems_iterate_over_all_threads( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/threadmp.h b/cpukit/score/include/rtems/score/threadmp.h index ad5efb7fb0..1a4f3087d4 100644 --- a/cpukit/score/include/rtems/score/threadmp.h +++ b/cpukit/score/include/rtems/score/threadmp.h @@ -1,9 +1,12 @@ -/* threadmp.h +/** + * @file threadmp.h * * This include file contains the specification for all routines * and data specific to the multiprocessing portion of the thread package. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,64 +19,63 @@ #ifndef __RTEMS_THREAD_MP_h #define __RTEMS_THREAD_MP_h +/** + * @defgroup ScoreThreadMP Thread Handler Multiprocessing Support + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif -/* - * _Thread_MP_Handler_initialization - * - * DESCRIPTION: +/** @brief _Thread_MP_Handler_initialization * * This routine initializes the multiprocessing portion of the Thread Handler. */ - void _Thread_MP_Handler_initialization ( uint32_t maximum_proxies ); - -/* - * _Thread_MP_Allocate_proxy - * - * DESCRIPTION: +/** @brief _Thread_MP_Allocate_proxy * * This allocates a proxy control block from * the inactive chain of free proxy control blocks. * - * NOTE: This function returns a thread control pointer + * @note This function returns a thread control pointer * because proxies are substitutes for remote threads. */ - Thread_Control *_Thread_MP_Allocate_proxy ( States_Control the_state ); -/* - * _Thread_MP_Find_proxy - * - * DESCRIPTION: +/** @brief _Thread_MP_Find_proxy * * This function removes the proxy control block for the specified * id from the active chain of proxy control blocks. */ - Thread_Control *_Thread_MP_Find_proxy ( Objects_Id the_id ); -/* +/** @brief Pointer to MP Thread Control Block + * * The following is used to determine when the multiprocessing receive * thread is executing so that a proxy can be allocated instead of * blocking the multiprocessing receive thread. */ - SCORE_EXTERN Thread_Control *_Thread_MP_Receive; -/* - * The following chains are used to manage proxies. +/* @brief Active Proxy Set + * + * The following chain is used to manage the active set proxies. */ - SCORE_EXTERN Chain_Control _Thread_MP_Active_proxies; + +/** @brief Inactive Proxy Set + * + * The following chain is used to manage the inactive set of proxies. + */ SCORE_EXTERN Chain_Control _Thread_MP_Inactive_proxies; #ifndef __RTEMS_APPLICATION__ @@ -84,5 +86,7 @@ SCORE_EXTERN Chain_Control _Thread_MP_Inactive_proxies; } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h index cbbb85e345..83b2563b96 100644 --- a/cpukit/score/include/rtems/score/threadq.h +++ b/cpukit/score/include/rtems/score/threadq.h @@ -1,9 +1,12 @@ -/* threadq.h +/** + * @file threadq.h * * This include file contains all the constants and structures associated * with the manipulation of objects. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,6 +19,13 @@ #ifndef __THREAD_QUEUE_h #define __THREAD_QUEUE_h +/** + * @defgroup ScoreThreadQ Thread Queue Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -26,132 +36,87 @@ extern "C" { #include <rtems/score/thread.h> #include <rtems/score/watchdog.h> -/* +/** * Constant for indefinite wait. */ - #define THREAD_QUEUE_WAIT_FOREVER WATCHDOG_NO_TIMEOUT -/* +/** * The following type defines the callout used when a remote task * is extracted from a local thread queue. */ - typedef void ( *Thread_queue_Flush_callout )( Thread_Control * ); -/* - * 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). - */ - -#if 0 -typedef void ( *Thread_queue_Extract_callout )( - Thread_Control * - ); - -SCORE_EXTERN Thread_queue_Extract_callout - _Thread_queue_Extract_table[ OBJECTS_CLASSES_LAST + 1 ]; -#endif - -/* - * _Thread_queue_Dequeue - * - * DESCRIPTION: +/** @brief Thread queue Dequeue * * This function returns a pointer to a thread waiting on * the_thread_queue. The selection of this thread is based on * the discipline of the_thread_queue. If no threads are waiting * on the_thread_queue, then NULL is returned. */ - Thread_Control *_Thread_queue_Dequeue( Thread_queue_Control *the_thread_queue ); -/* - * _Thread_queue_Enqueue - * - * DESCRIPTION: +/** @brief Thread queue Enqueue * * This routine enqueues the currently executing thread on * the_thread_queue with an optional timeout. */ - void _Thread_queue_Enqueue( Thread_queue_Control *the_thread_queue, Watchdog_Interval timeout ); -/* - * _Thread_queue_Extract - * - * DESCRIPTION: +/** @brief Thread queue Extract * * This routine removes the_thread from the_thread_queue * and cancels any timeouts associated with this blocking. */ - void _Thread_queue_Extract( Thread_queue_Control *the_thread_queue, Thread_Control *the_thread ); -/* - * _Thread_queue_Extract_with_proxy - * - * DESCRIPTION: +/** @brief Thread queue Extract with proxy * * This routine extracts the_thread from the_thread_queue * and ensures that if there is a proxy for this task on * another node, it is also dealt with. */ - boolean _Thread_queue_Extract_with_proxy( Thread_Control *the_thread ); -/* - * _Thread_queue_First - * - * DESCRIPTION: +/** @brief Thread queue First * * This function returns a pointer to the "first" thread * on the_thread_queue. The "first" thread is selected * based on the discipline of the_thread_queue. */ - Thread_Control *_Thread_queue_First( Thread_queue_Control *the_thread_queue ); -/* - * _Thread_queue_Flush - * - * DESCRIPTION: +/** @brief Thread queue Flush * * This routine unblocks all threads blocked on the_thread_queue * and cancels any associated timeouts. */ - void _Thread_queue_Flush( Thread_queue_Control *the_thread_queue, Thread_queue_Flush_callout remote_extract_callout, uint32_t status ); -/* - * _Thread_queue_Initialize - * - * DESCRIPTION: +/** @brief Thread queue Initialize * * This routine initializes the_thread_queue based on the * discipline indicated in attribute_set. The state set on * threads which block on the_thread_queue is state. */ - void _Thread_queue_Initialize( Thread_queue_Control *the_thread_queue, Thread_queue_Disciplines the_discipline, @@ -159,126 +124,91 @@ void _Thread_queue_Initialize( uint32_t timeout_status ); -/* - * _Thread_queue_Dequeue_priority - * - * DESCRIPTION: +/** @brief Thread queue Dequeue priority * * This function returns a pointer to the highest priority * thread waiting on the_thread_queue. If no threads are waiting * on the_thread_queue, then NULL is returned. */ - Thread_Control *_Thread_queue_Dequeue_priority( Thread_queue_Control *the_thread_queue ); -/* - * _Thread_queue_Enqueue_priority - * - * DESCRIPTION: +/** @brief Thread queue Enqueue priority * * This routine enqueues the currently executing thread on * the_thread_queue with an optional timeout using the * priority discipline. */ - void _Thread_queue_Enqueue_priority( Thread_queue_Control *the_thread_queue, Thread_Control *the_thread, Watchdog_Interval timeout ); -/* - * _Thread_queue_Extract_priority - * - * DESCRIPTION: +/** @brief Thread queue Extract priority * * This routine removes the_thread from the_thread_queue * and cancels any timeouts associated with this blocking. */ - void _Thread_queue_Extract_priority( Thread_queue_Control *the_thread_queue, Thread_Control *the_thread ); -/* - * _Thread_queue_First_priority - * - * DESCRIPTION: +/** @brief Thread queue First priority * * This function returns a pointer to the "first" thread * on the_thread_queue. The "first" thread is the highest * priority thread waiting on the_thread_queue. */ - Thread_Control *_Thread_queue_First_priority( Thread_queue_Control *the_thread_queue ); -/* - * _Thread_queue_Dequeue_FIFO - * - * DESCRIPTION: +/** @brief Thread queue Dequeue FIFO * * This function returns a pointer to the thread which has * been waiting the longest on the_thread_queue. If no * threads are waiting on the_thread_queue, then NULL is returned. */ - Thread_Control *_Thread_queue_Dequeue_fifo( Thread_queue_Control *the_thread_queue ); -/* - * _Thread_queue_Enqueue_FIFO - * - * DESCRIPTION: +/** @brief Thread queue Enqueue FIFO * * This routine enqueues the currently executing thread on * the_thread_queue with an optional timeout using the * FIFO discipline. */ - void _Thread_queue_Enqueue_fifo( Thread_queue_Control *the_thread_queue, Thread_Control *the_thread, Watchdog_Interval timeout ); -/* - * _Thread_queue_Extract_FIFO - * - * DESCRIPTION: +/** @brief Thread queue Extract FIFO * * This routine removes the_thread from the_thread_queue * and cancels any timeouts associated with this blocking. */ - void _Thread_queue_Extract_fifo( Thread_queue_Control *the_thread_queue, Thread_Control *the_thread ); -/* - * _Thread_queue_First_FIFO - * - * DESCRIPTION: +/** @brief Thread queue First FIFO * * This function returns a pointer to the "first" thread * on the_thread_queue. The first thread is the thread * which has been waiting longest on the_thread_queue. */ - Thread_Control *_Thread_queue_First_fifo( Thread_queue_Control *the_thread_queue ); -/* - * _Thread_queue_timeout - * - * DESCRIPTION: +/** @brief Thread queue timeout * * This routine is invoked when a task's request has not * been satisfied after the timeout interval specified to @@ -286,7 +216,6 @@ Thread_Control *_Thread_queue_First_fifo( * its status code will be set in it's control block to indicate * that a timeout has occurred. */ - void _Thread_queue_Timeout ( Objects_Id id, void *ignored @@ -296,5 +225,7 @@ void _Thread_queue_Timeout ( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h index 8966c8b06c..b938899293 100644 --- a/cpukit/score/include/rtems/score/tod.h +++ b/cpukit/score/include/rtems/score/tod.h @@ -1,9 +1,12 @@ -/* tod.h +/** + * @file tod.h * * This include file contains all the constants and structures associated * with the Time of Day Handler. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,6 +19,13 @@ #ifndef __TIME_OF_DAY_h #define __TIME_OF_DAY_h +/** + * @defgroup ScoreTOD Time Of Day (TOD) Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -23,93 +33,142 @@ extern "C" { #include <rtems/score/object.h> #include <rtems/score/watchdog.h> -/* +/** @defgroup ScoreTODConstants TOD Constants * The following constants are related to the time of day. */ +/**@{*/ +/** + * XXX + */ #define TOD_SECONDS_PER_MINUTE (uint32_t )60 + +/** + * XXX + */ #define TOD_MINUTES_PER_HOUR (uint32_t )60 + +/** + * XXX + */ #define TOD_MONTHS_PER_YEAR (uint32_t )12 + +/** + * XXX + */ #define TOD_DAYS_PER_YEAR (uint32_t )365 + +/** + * XXX + */ #define TOD_HOURS_PER_DAY (uint32_t )24 + +/** + * XXX + */ #define TOD_SECONDS_PER_DAY (uint32_t ) (TOD_SECONDS_PER_MINUTE * \ TOD_MINUTES_PER_HOUR * \ TOD_HOURS_PER_DAY) + +/** + * XXX + */ #define TOD_SECONDS_PER_NON_LEAP_YEAR (365 * TOD_SECONDS_PER_DAY) +/** + * XXX + */ #define TOD_MILLISECONDS_PER_SECOND (uint32_t )1000 + +/** + * XXX + */ #define TOD_MICROSECONDS_PER_SECOND (uint32_t )1000000 + +/** + * XXX + */ #define TOD_NANOSECONDS_PER_SECOND (uint32_t )1000000000 + +/** + * XXX + */ #define TOD_NANOSECONDS_PER_MICROSECOND (uint32_t )1000 -/* +/**@}*/ + +/** @brief RTEMS Epoch Year + * * The following constant define the earliest year to which an * time of day can be initialized. This is considered the * epoch. */ - #define TOD_BASE_YEAR 1988 -/* +/** * The following record defines the time of control block. This * control block is used to maintain the current time of day. + * + * @note This is an RTEID style time/date. */ - -typedef struct { /* RTEID style time/date */ - uint32_t year; /* year, A.D. */ - uint32_t month; /* month, 1 -> 12 */ - uint32_t day; /* day, 1 -> 31 */ - uint32_t hour; /* hour, 0 -> 23 */ - uint32_t minute; /* minute, 0 -> 59 */ - uint32_t second; /* second, 0 -> 59 */ - uint32_t ticks; /* elapsed ticks between secs */ +typedef struct { + /** This field is the year, A.D. */ + uint32_t year; + /** This field is the month, 1 -> 12 */ + uint32_t month; + /** This field is the day, 1 -> 31 */ + uint32_t day; + /** This field is the hour, 0 -> 23 */ + uint32_t hour; + /** This field is the minute, 0 -> 59 */ + uint32_t minute; + /** This field is the second, 0 -> 59 */ + uint32_t second; + /** This field is the elapsed ticks between secs */ + uint32_t ticks; } TOD_Control; -/* - * The following is TRUE if the application has set the current +/** @brief Is the Time Of Day Set + * + * This is TRUE if the application has set the current * time of day, and FALSE otherwise. */ - SCORE_EXTERN boolean _TOD_Is_set; -/* +/** @brief Current Time of Day * The following contains the current time of day. */ - SCORE_EXTERN TOD_Control _TOD_Current; -/* +/** @brief Seconds Since RTEMS Epoch * The following contains the number of seconds from 00:00:00 * January 1, TOD_BASE_YEAR until the current time of day. */ - SCORE_EXTERN Watchdog_Interval _TOD_Seconds_since_epoch; -/* +/** @brief Microseconds per Clock Tick + * * The following contains the number of microseconds per tick. */ - SCORE_EXTERN uint32_t _TOD_Microseconds_per_tick; -/* - * The following contains the number of clock ticks per second. +/** @brief Clock Ticks per Second * - * NOTE: + * The following contains the number of clock ticks per second. * - * If one second is NOT evenly divisible by the number of microseconds + * @note If one second is NOT evenly divisible by the number of microseconds * per clock tick, this value will contain only the integer portion * of the division. This means that the interval between clock ticks * can be a source of error in the current time of day. */ - SCORE_EXTERN uint32_t _TOD_Ticks_per_second; -/* +/** @brief Watchdog Set Managed by Seconds + * * This is the control structure for the watchdog timer which * fires to service the seconds chain. */ - SCORE_EXTERN Watchdog_Control _TOD_Seconds_watchdog; #ifdef SCORE_INIT @@ -120,7 +179,6 @@ SCORE_EXTERN Watchdog_Control _TOD_Seconds_watchdog; * The second dimension should range from 1 to 12 for January to * February, respectively. */ - const uint32_t _TOD_Days_per_month[ 2 ][ 13 ] = { { 0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }, { 0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 } @@ -131,7 +189,6 @@ const uint32_t _TOD_Days_per_month[ 2 ][ 13 ] = { * up to the month indicated by the index of the second dimension. * The first dimension should be 1 for leap years, and 0 otherwise. */ - const uint16_t _TOD_Days_to_date[2][13] = { { 0, 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334 }, { 0, 0, 31, 60, 91, 121, 152, 182, 213, 244, 274, 305, 335 } @@ -143,122 +200,95 @@ const uint16_t _TOD_Days_to_date[2][13] = { * years, and the number of years since the beginning of a leap * year otherwise. */ - const uint16_t _TOD_Days_since_last_leap_year[4] = { 0, 366, 731, 1096 }; #else +/** @brief + * + */ extern const uint16_t _TOD_Days_to_date[2][13]; /* Julian days */ + +/** @brief + * + */ extern const uint16_t _TOD_Days_since_last_leap_year[4]; + +/** @brief + * + */ extern const uint32_t _TOD_Days_per_month[2][13]; #endif -/* - * _TOD_Handler_initialization - * - * DESCRIPTION: +/** @brief _TOD_Handler_initialization * * This routine performs the initialization necessary for this handler. */ - void _TOD_Handler_initialization( uint32_t microseconds_per_tick ); -/* - * _TOD_Set - * - * DESCRIPTION: +/** @brief _TOD_Set * * This routine sets the current time of day to THE_TOD and * the equivalent SECONDS_SINCE_EPOCH. */ - void _TOD_Set( TOD_Control *the_tod, Watchdog_Interval seconds_since_epoch ); -/* - * _TOD_Validate - * - * DESCRIPTION: +/** @brief _TOD_Validate * * This function returns TRUE if THE_TOD contains * a valid time of day, and FALSE otherwise. */ - boolean _TOD_Validate( TOD_Control *the_tod ); -/* - * _TOD_To_seconds - * - * DESCRIPTION: +/** @brief _TOD_To_seconds * * This function returns the number seconds between the epoch and THE_TOD. */ - Watchdog_Interval _TOD_To_seconds( TOD_Control *the_tod ); -/* - * _TOD_Tickle - * - * DESCRIPTION: +/** @brief _TOD_Tickle * * This routine is scheduled as a watchdog function and is invoked at * each second boundary. It updates the current time of day to indicate * that a second has passed and processes the seconds watchdog chain. */ - void _TOD_Tickle( Objects_Id id, void *ignored ); -/* - * TOD_MILLISECONDS_TO_MICROSECONDS - * - * DESCRIPTION: +/** @brief TOD_MILLISECONDS_TO_MICROSECONDS * * This routine converts an interval expressed in milliseconds to microseconds. * - * NOTE: - * - * This must be a macro so it can be used in "static" tables. + * @note This must be a macro so it can be used in "static" tables. */ - #define TOD_MILLISECONDS_TO_MICROSECONDS(_ms) ((_ms) * 1000) -/* - * TOD_MICROSECONDS_TO_TICKS - * - * DESCRIPTION: +/** @brief TOD_MICROSECONDS_TO_TICKS * * This routine converts an interval expressed in microseconds to ticks. * - * NOTE: - * - * This must be a macro so it can be used in "static" tables. + * @note This must be a macro so it can be used in "static" tables. */ - #define TOD_MICROSECONDS_TO_TICKS(_us) \ ((_us) / _TOD_Microseconds_per_tick) -/* - * TOD_MILLISECONDS_TO_TICKS - * - * DESCRIPTION: +/** @brief TOD_MILLISECONDS_TO_TICKS * * This routine converts an interval expressed in milliseconds to ticks. * - * NOTE: - * - * This must be a macro so it can be used in "static" tables. + * @note This must be a macro so it can be used in "static" tables. */ #define TOD_MILLISECONDS_TO_TICKS(_ms) \ @@ -272,5 +302,7 @@ void _TOD_Tickle( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/tqdata.h b/cpukit/score/include/rtems/score/tqdata.h index 4945c74e3f..f7ba664e17 100644 --- a/cpukit/score/include/rtems/score/tqdata.h +++ b/cpukit/score/include/rtems/score/tqdata.h @@ -1,9 +1,12 @@ -/* tqdata.h +/** + * @file tqdata.h * * This include file contains all the constants and structures * needed to declare a thread queue. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -16,6 +19,13 @@ #ifndef __THREAD_QUEUE_DATA_h #define __THREAD_QUEUE_DATA_h +/** + * @defgroup ScoreThreadQData Thread Queue Handler Data Definition + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -85,5 +95,7 @@ typedef struct { } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/userext.h b/cpukit/score/include/rtems/score/userext.h index c0f5a4b0a8..8215eb5f45 100644 --- a/cpukit/score/include/rtems/score/userext.h +++ b/cpukit/score/include/rtems/score/userext.h @@ -1,10 +1,13 @@ -/* userext.h +/** + * @file userext.h * * This include file contains all information about user extensions. This * Handler provides mechanisms which can be used to initialize and manipulate * all user extensions. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -17,6 +20,13 @@ #ifndef __USER_EXTENSIONS_h #define __USER_EXTENSIONS_h +/** + * @defgroup ScoreUserExt User Extension Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -25,193 +35,210 @@ 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. * This table defines the application dependent routines which * are invoked at critical points in the life of each thread and * the system as a whole. */ +/*@{*/ +/** + * XXX + */ typedef void User_extensions_routine; +/** + * XXX + */ typedef boolean ( *User_extensions_thread_create_extension )( Thread_Control *, Thread_Control * ); +/** + * XXX + */ typedef User_extensions_routine ( *User_extensions_thread_delete_extension )( Thread_Control *, Thread_Control * ); +/** + * XXX + */ typedef User_extensions_routine ( *User_extensions_thread_start_extension )( Thread_Control *, Thread_Control * ); +/** + * XXX + */ typedef User_extensions_routine ( *User_extensions_thread_restart_extension )( Thread_Control *, Thread_Control * ); +/** + * XXX + */ typedef User_extensions_routine ( *User_extensions_thread_switch_extension )( Thread_Control *, Thread_Control * ); +/** + * XXX + */ typedef User_extensions_routine ( *User_extensions_thread_post_switch_extension )( Thread_Control * ); +/** + * XXX + */ typedef User_extensions_routine ( *User_extensions_thread_begin_extension )( Thread_Control * ); +/** + * XXX + */ typedef User_extensions_routine ( *User_extensions_thread_exitted_extension )( Thread_Control * ); +/** + * XXX + */ typedef User_extensions_routine ( *User_extensions_fatal_extension )( Internal_errors_Source /* the_source */, boolean /* is_internal */, uint32_t /* the_error */ ); - +/** + * XXX + */ typedef struct { + /** This field is XXX */ User_extensions_thread_create_extension thread_create; + /** This field is XXX */ User_extensions_thread_start_extension thread_start; + /** This field is XXX */ User_extensions_thread_restart_extension thread_restart; + /** This field is XXX */ User_extensions_thread_delete_extension thread_delete; + /** This field is XXX */ User_extensions_thread_switch_extension thread_switch; + /** This field is XXX */ User_extensions_thread_begin_extension thread_begin; + /** This field is XXX */ User_extensions_thread_exitted_extension thread_exitted; + /** This field is XXX */ User_extensions_fatal_extension fatal; } User_extensions_Table; -/* - * The following is used to manage the list of switch handlers. - */ +/*@}*/ +/** + * This is used to manage the list of switch handlers. + */ typedef struct { + /** This field is XXX */ Chain_Node Node; + /** This field is XXX */ User_extensions_thread_switch_extension thread_switch; } User_extensions_Switch_control; -/* - * The following is used to manage each user extension set. +/** + * This is used to manage each user extension set. * The switch control is part of the extensions control even * if not used due to the extension not having a switch * handler. */ - typedef struct { + /** This field is XXX */ Chain_Node Node; + /** This field is XXX */ User_extensions_Switch_control Switch; + /** This field is XXX */ User_extensions_Table Callouts; } User_extensions_Control; -/* - * The following is used to manage the list of active extensions. +/** + * This is used to manage the list of active extensions. */ - SCORE_EXTERN Chain_Control _User_extensions_List; -/* - * The following is used to manage a chain of user extension task +/** + * This is used to manage a chain of user extension task * switch nodes. */ - SCORE_EXTERN Chain_Control _User_extensions_Switches_list; -/* - * _User_extensions_Thread_create - * - * DESCRIPTION: +/** @brief User extensions Thread create * * This routine is used to invoke the user extension for * the thread creation operate. */ - boolean _User_extensions_Thread_create ( Thread_Control *the_thread ); -/* - * _User_extensions_Thread_delete - * - * DESCRIPTION: +/** @brief User extensions Thread delete * * This routine is used to invoke the user extension for * the thread deletion operation. */ - void _User_extensions_Thread_delete ( Thread_Control *the_thread ); -/* - * _User_extensions_Thread_start - * - * DESCRIPTION: +/** @brief User extensions Thread start * * This routine is used to invoke the user extension for * the thread start operation. */ - void _User_extensions_Thread_start ( Thread_Control *the_thread ); -/* - * _User_extensions_Thread_restart - * - * DESCRIPTION: +/** @brief User extensions Thread restart * * This routine is used to invoke the user extension for * the thread restart operation. */ - void _User_extensions_Thread_restart ( Thread_Control *the_thread ); -/* - * _User_extensions_Thread_begin - * - * DESCRIPTION: +/** @brief User extensions Thread begin * * This routine is used to invoke the user extension which * is invoked when a thread begins. */ - void _User_extensions_Thread_begin ( Thread_Control *executing ); -/* - * _User_extensions_Thread_exitted - * - * DESCRIPTION: +/** @brief User extensions Thread exitted * * This routine is used to invoke the user extension which * is invoked when a thread exits. */ - void _User_extensions_Thread_exitted ( Thread_Control *executing ); -/* - * _User_extensions_Fatal - * - * DESCRIPTION: +/** @brief User extensions Fatal * * This routine is used to invoke the user extension invoked * when a fatal error occurs. */ - void _User_extensions_Fatal ( Internal_errors_Source the_source, boolean is_internal, @@ -226,5 +253,7 @@ void _User_extensions_Fatal ( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h index cb70d13120..91d2a166c0 100644 --- a/cpukit/score/include/rtems/score/watchdog.h +++ b/cpukit/score/include/rtems/score/watchdog.h @@ -1,10 +1,13 @@ -/* watchdog.h +/** + * @file watchdog.h * * This include file contains all the constants and structures associated * with watchdog timers. This Handler provides mechanisms which can be - * used to initialize and manipulate watchdog timers. - * - * COPYRIGHT (c) 1989-1999. + * used to initialize and manipulate watchdog timers. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -17,67 +20,94 @@ #ifndef __WATCHDOG_h #define __WATCHDOG_h +/** + * @defgroup ScoreWatchdog Watchdog Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif #include <rtems/score/object.h> -/* +/** @brief Maximum Interval Length + * * The following type defines the control block used to manage * intervals. */ - #define WATCHDOG_MAXIMUM_INTERVAL ((Watchdog_Interval) 0xffffffff) +/** @brief Watchdog Interval Type + * + * This type is used to specify the length of intervals. + */ typedef uint32_t Watchdog_Interval; -/* - * The following types define a pointer to a watchdog service routine. +/** @brief Watchdog Service Routine Return Type + * + * This type defines the return type from a Watchdog Service Routine. */ - typedef void Watchdog_Service_routine; +/** @brief Watchdog Service Routine Pointer Type + * + * This type define a pointer to a watchdog service routine. + */ typedef Watchdog_Service_routine ( *Watchdog_Service_routine_entry )( Objects_Id, void * ); -/* - * Constant for indefinite wait. (actually an illegal interval) +/** @brief No timeout constant + * + * This is the constant for indefinite wait. It is actually an + * illegal interval. */ - #define WATCHDOG_NO_TIMEOUT 0 -/* - * The following enumerated type lists the states in which a +/** @brief Watchdog States Type + * + * This enumerated type is the set of the states in which a * watchdog timer may be at any given time. */ typedef enum { - WATCHDOG_INACTIVE, /* off all chains */ - WATCHDOG_BEING_INSERTED, /* off all chains, searching for insertion point */ - WATCHDOG_ACTIVE, /* on chain, allowed to fire */ - WATCHDOG_REMOVE_IT /* on chain, remove without firing if expires */ + /** This is the state when the watchdog is off all chains */ + WATCHDOG_INACTIVE, + /** This is the state when the watchdog is off all chains, but we are + * currently searching for the insertion point. + */ + WATCHDOG_BEING_INSERTED, + /** This is the state when the watchdog is on a chain, and allowed to fire. */ + WATCHDOG_ACTIVE, + /** This is the state when the watchdog is on a chain, but we should + * remove without firing if it expires. + */ + WATCHDOG_REMOVE_IT } Watchdog_States; -/* +/** @brief Watchdog Adjustment Directions Type + * * The following enumerated type details the manner in which - * a watchdog chain may be adjusted by the Watchdog_Adjust + * a watchdog chain may be adjusted by the @ref _Watchdog_Adjust * routine. The direction indicates a movement FORWARD * or BACKWARD in time. */ - typedef enum { - WATCHDOG_FORWARD, /* adjust delta value forward */ - WATCHDOG_BACKWARD /* adjust delta value backward */ + /** adjust delta value forward */ + WATCHDOG_FORWARD, + /** adjust delta value backward */ + WATCHDOG_BACKWARD } Watchdog_Adjust_directions; -/* +/** @brief Watchdog Control Structure + * * The following record defines the control block used * to manage each watchdog timer. */ - typedef struct { Chain_Node Node; Watchdog_States state; @@ -90,93 +120,93 @@ typedef struct { void *user_data; } Watchdog_Control; -/* - * The following are used for synchronization purposes +/** @brief Watchdog Synchronization Level + * + * This used for synchronization purposes * during an insert on a watchdog delta chain. */ - SCORE_EXTERN volatile uint32_t _Watchdog_Sync_level; + +/** @brief Watchdog Synchronization Count + * + * This used for synchronization purposes + * during an insert on a watchdog delta chain. + */ SCORE_EXTERN volatile uint32_t _Watchdog_Sync_count; -/* - * The following contains the number of ticks since the - * system was booted. +/** @brief Ticks Since System Boot + * + * This contains the number of ticks since the system was booted. */ SCORE_EXTERN volatile Watchdog_Interval _Watchdog_Ticks_since_boot; -/* - * The following defines the watchdog chains which are managed - * on ticks and second boundaries. +/** @brief Per Ticks Watchdog List + * + * This is the watchdog chain which is managed at ticks. */ - SCORE_EXTERN Chain_Control _Watchdog_Ticks_chain; -SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain; -/* - * _Watchdog_Handler_initialization +/** @brief Per Seconds Watchdog List * - * DESCRIPTION: + * This is the watchdog chain which is managed at second boundaries. + */ +SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain; + +/** @brief Watchdog Handler Initialization * * This routine initializes the watchdog handler. The watchdog * synchronization flag is initialized and the watchdog chains are * initialized and emptied. */ - void _Watchdog_Handler_initialization( void ); -/* - * _Watchdog_Remove - * - * DESCRIPTION: +/** @brief Remove Watchdog from List * - * This routine removes THE_WATCHDOG from the watchdog chain on which - * it resides and returns the state THE_WATCHDOG timer was in. + * 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 + * @return the state in which @a the_watchdog was in when removed */ - Watchdog_States _Watchdog_Remove ( Watchdog_Control *the_watchdog ); -/* - * _Watchdog_Adjust +/** @brief Watchdog Adjust * - * DESCRIPTION: + * This routine adjusts the @a header watchdog chain in the forward + * or backward @a direction for @a units ticks. * - * This routine adjusts the HEADER watchdog chain in the forward - * or backward DIRECTION for 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 */ - void _Watchdog_Adjust ( Chain_Control *header, Watchdog_Adjust_directions direction, Watchdog_Interval units ); -/* - * _Watchdog_Insert - * - * DESCRIPTION: +/** @brief Watchdog Insert * - * This routine inserts THE_WATCHDOG into the HEADER watchdog chain - * for a time of UNITS. The INSERT_MODE indicates whether - * THE_WATCHDOG is to be activated automatically or later, explicitly - * by the caller. + * 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 */ - void _Watchdog_Insert ( Chain_Control *header, Watchdog_Control *the_watchdog ); -/* - * _Watchdog_Tickle - * - * DESCRIPTION: +/** @brief Watchdog Tickle * * This routine is invoked at appropriate intervals to update - * the HEADER watchdog chain. + * the @a header watchdog chain. + * + * @param header (in) is the watchdog chain to tickle */ void _Watchdog_Tickle ( @@ -191,5 +221,7 @@ void _Watchdog_Tickle ( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/score/wkspace.h b/cpukit/score/include/rtems/score/wkspace.h index aff79c78d5..dd3869df05 100644 --- a/cpukit/score/include/rtems/score/wkspace.h +++ b/cpukit/score/include/rtems/score/wkspace.h @@ -1,10 +1,13 @@ -/* wkspace.h +/** + * @file wkspace.h * * This include file contains information related to the * RAM Workspace. This Handler provides mechanisms which can be used to * define, initialize and manipulate the workspace. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -17,6 +20,13 @@ #ifndef __WORKSPACE_h #define __WORKSPACE_h +/** + * @defgroup ScoreWorkspace Workspace Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -24,36 +34,35 @@ extern "C" { #include <rtems/score/heap.h> #include <rtems/score/interr.h> -/* - * The following is used to manage the Workspace. +/** @brief Executive Workspace Control * + * The is the heap control structure that used to manage the + * RTEMS Executive Workspace. */ - SCORE_EXTERN Heap_Control _Workspace_Area; /* executive heap header */ -/* - * _Workspace_Handler_initialization - * - * DESCRIPTION: +/** @brief Workspace Handler Initialization * * This routine performs the initialization necessary for this handler. + * + * @param starting_address (in) is the base address of the RTEMS Executive + * Workspace + * @param size (in) is the number of bytes in the RTEMS Executive Workspace */ - void _Workspace_Handler_initialization( void *starting_address, uint32_t size ); -/* - * _Workspace_Allocate_or_fatal_error +/** @brief Workspace Allocate or Fail with Fatal Error * - * DESCRIPTION: - * - * This routine returns the address of a block of memory of size + * This routine returns the address of a block of memory of @a size * bytes. If a block of the appropriate size cannot be allocated * from the workspace, then the internal error handler is invoked. + * + * @param size (in) is the desired number of bytes to allocate + * @return If successful, the starting address of the allocated memory */ - void *_Workspace_Allocate_or_fatal_error( uint32_t size ); @@ -66,5 +75,7 @@ void *_Workspace_Allocate_or_fatal_error( } #endif +/**@}*/ + #endif /* end of include file */ diff --git a/cpukit/score/include/rtems/seterr.h b/cpukit/score/include/rtems/seterr.h index d45345ba6d..621ee5932e 100644 --- a/cpukit/score/include/rtems/seterr.h +++ b/cpukit/score/include/rtems/seterr.h @@ -1,5 +1,12 @@ +/** + * @file seterr.h + * + * This file contains macros and definitions which ease the burden + * of consistently setting errno and returning -1. + */ + /* - * COPYRIGHT (c) 1989-1999. + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be diff --git a/cpukit/score/include/rtems/system.h b/cpukit/score/include/rtems/system.h index 90501dd3d3..e441f8890d 100644 --- a/cpukit/score/include/rtems/system.h +++ b/cpukit/score/include/rtems/system.h @@ -1,10 +1,13 @@ -/* system.h +/** + * @file system.h * * This include file contains information that is included in every * function in the executive. This must be the first include file * included in all internal RTEMS files. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -168,7 +171,7 @@ SCORE_EXTERN rtems_cpu_table _CPU_Table; /* CPU dependent info */ /* * Macros to access CPU Table fields required by ALL ports. * - * NOTE: Similar macros to access port specific fields in in the + * @note Similar macros to access port specific fields in in the * appropriate cpu.h file. */ |