From 6a074363a2657a86b5f1ea0fc1185f68ad9f3c08 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 16 Jan 2006 15:13:58 +0000 Subject: 2006-01-16 Joel Sherrill Large patch to improve Doxygen output. As a side-effect, grammar and spelling errors were corrected, spacing errors were address, and some variable names were improved. * libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS. * score/Doxyfile: Set output directory. Predefine some macro values. Turn on graphical output. * score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/object.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/macros/README, score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, score/src/threadstartmultitasking.c: Improve generated Doxygen output. Fix spelling and grammar errors in comments. Correct names of some variables and propagate changes. --- cpukit/score/inline/rtems/score/address.inl | 58 +++++-- cpukit/score/inline/rtems/score/chain.inl | 218 +++++++++++++++++++------- cpukit/score/inline/rtems/score/coremutex.inl | 52 ++++-- cpukit/score/inline/rtems/score/coresem.inl | 16 +- cpukit/score/inline/rtems/score/heap.inl | 135 ++++++++++++---- cpukit/score/inline/rtems/score/object.inl | 185 ++++++++++------------ cpukit/score/inline/rtems/score/stack.inl | 4 +- cpukit/score/inline/rtems/score/thread.inl | 8 +- cpukit/score/inline/rtems/score/tqdata.inl | 6 +- 9 files changed, 448 insertions(+), 234 deletions(-) (limited to 'cpukit/score/inline') diff --git a/cpukit/score/inline/rtems/score/address.inl b/cpukit/score/inline/rtems/score/address.inl index e8e260910f..19cf03699c 100644 --- a/cpukit/score/inline/rtems/score/address.inl +++ b/cpukit/score/inline/rtems/score/address.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -24,12 +24,17 @@ * @{ */ -/** - * This function is used to add an offset to a base address. +/** @brief Add Offset to Address + * + * This function is used to add an @a offset to a @a base address. * It returns the resulting address. This address is typically * converted to an access type before being used further. + * + * @param[in] base is the base address. + * @param[in] offset is the offset to add to @a base. + * + * @return This method returns the resulting address. */ - RTEMS_INLINE_ROUTINE void *_Addresses_Add_offset ( void *base, uint32_t offset @@ -38,10 +43,16 @@ RTEMS_INLINE_ROUTINE void *_Addresses_Add_offset ( return (void *)((char *)base + offset); } -/** - * This function is used to subtract an offset from a base +/** @brief Subtract Offset from Offset + * + * This function is used to subtract an @a offset from a @a base * address. It returns the resulting address. This address is * typically converted to an access type before being used further. + * + * @param[in] base is the base address. + * @param[in] offset is the offset to subtract to @a base. + * + * @return This method returns the resulting address. */ RTEMS_INLINE_ROUTINE void *_Addresses_Subtract_offset ( @@ -52,14 +63,19 @@ RTEMS_INLINE_ROUTINE void *_Addresses_Subtract_offset ( return (void *)((char *)base - offset); } -/** +/** @brief Subtract Two Offsets + * * This function is used to subtract two addresses. It returns the * resulting offset. * - * @note The cast of an address to an uint32_t makes this code + * @param[in] left is the address on the left hand side of the subtraction. + * @param[in] right is the address on the right hand side of the subtraction. + * + * @return This method returns the resulting address. + * + * @note The cast of an address to an uint32_t makes this code * dependent on an addresses being thirty two bits. */ - RTEMS_INLINE_ROUTINE uint32_t _Addresses_Subtract ( void *left, void *right @@ -68,12 +84,17 @@ RTEMS_INLINE_ROUTINE uint32_t _Addresses_Subtract ( return ((char *) left - (char *) right); } -/** +/** @brief Is Address Aligned + * * This function returns TRUE if the given address is correctly * aligned for this processor and FALSE otherwise. Proper alignment * is based on correctness and efficiency. + * + * @param[in] address is the address being checked for alignment. + * + * @return This method returns TRUE if the address is aligned and + * FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Addresses_Is_aligned ( void *address ) @@ -81,25 +102,32 @@ RTEMS_INLINE_ROUTINE boolean _Addresses_Is_aligned ( #if (CPU_ALIGNMENT == 0) return TRUE; #else - return ( ( (uintptr_t)address % CPU_ALIGNMENT ) == 0 ); + return (((uintptr_t)address % CPU_ALIGNMENT) == 0); #endif } -/** +/** @brief Is Address In Range + * * This function returns TRUE if the given address is within the * memory range specified and FALSE otherwise. base is the address * of the first byte in the memory range and limit is the address * of the last byte in the memory range. The base address is * assumed to be lower than the limit address. + * + * @param[in] address is the address to check. + * @param[in] base is the lowest address of the range to check against. + * @param[in] limit is the highest address of the range to check against. + * + * @return This method returns TRUE if the given @a address is within the + * memory range specified and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Addresses_Is_in_range ( void *address, void *base, void *limit ) { - return ( address >= base && address <= limit ); + return (address >= base && address <= limit); } /**@}*/ diff --git a/cpukit/score/inline/rtems/score/chain.inl b/cpukit/score/inline/rtems/score/chain.inl index 3a6f10e2e6..d394ec93e1 100644 --- a/cpukit/score/inline/rtems/score/chain.inl +++ b/cpukit/score/inline/rtems/score/chain.inl @@ -10,7 +10,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -28,9 +28,16 @@ * @{ */ -/** - * This function returns TRUE if \a left and \a right are equal, +/** @brief Are Two Nodes Equal + * + * This function returns TRUE if @a left and @a right are equal, * and FALSE otherwise. + * + * @param[in] left is the node on the left hand side of the comparison. + * @param[in] right is the node on the left hand side of the comparison. + * + * @return This function returns TRUE if @a left and @a right are equal, + * and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal( Chain_Node *left, @@ -40,28 +47,43 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal( return left == right; } -/** +/** @brief Is this Chain Control Pointer Null + * * This function returns TRUE if the_chain is NULL and FALSE otherwise. + * + * @param[in] the_chain is the chain to be checked for empty status. + * + * @return This method returns TRUE if the_chain is NULL and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_null( Chain_Control *the_chain ) { - return ( the_chain == NULL ); + return (the_chain == NULL); } -/** + +/** @brief Is the Chain Node Pointer NULL + * * This function returns TRUE if the_node is NULL and FALSE otherwise. + * + * @param[in] the_node is the node pointer to check. + * + * @return This method returns TRUE if the_node is NULL and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Chain_Is_null_node( Chain_Node *the_node ) { - return ( the_node == NULL ); + return (the_node == NULL); } -/** +/** @brief Return pointer to Chain Head + * * This function returns a pointer to the first node on the chain. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This method returns the permanent head node of the chain. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head( Chain_Control *the_chain @@ -70,8 +92,13 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head( return (Chain_Node *) the_chain; } -/** +/** @brief Return pointer to Chain Tail + * * This function returns a pointer to the last node on the chain. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This method returns the permanent tail node of the chain. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail( Chain_Control *the_chain @@ -80,92 +107,132 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail( return (Chain_Node *) &the_chain->permanent_null; } -/** - * This function returns TRUE if there a no nodes on the_chain and +/** @brief Is the Chain Empty + * + * This function returns TRUE if there a no nodes on @a the_chain and + * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This function returns TRUE if there a no nodes on @a the_chain and * FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_empty( Chain_Control *the_chain ) { - return ( the_chain->first == _Chain_Tail( the_chain ) ); + return (the_chain->first == _Chain_Tail(the_chain)); } -/** +/** @brief Is this the First Node on the Chain + * * This function returns TRUE if the_node is the first node on a chain and * FALSE otherwise. + * + * @param[in] the_node is the node the caller wants to know if it is + * the first node on a chain. + * + * @return This function returns TRUE if @a the_node is the first node on + * a chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_first( Chain_Node *the_node ) { - return ( the_node->previous == NULL ); + return (the_node->previous == NULL); } -/** - * This function returns TRUE if \a the_node is the last node on a chain and +/** @brief Is this the Last Node on the Chain + * + * This function returns TRUE if @a the_node is the last node on a chain and * FALSE otherwise. + * + * @param[in] the_node is the node to check as the last node. + * + * @return This function returns TRUE if @a the_node is the last node on + * a chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_last( Chain_Node *the_node ) { - return ( the_node->next == NULL ); + return (the_node->next == NULL); } -/** - * This function returns TRUE if there is only one node on \a the_chain and +/** @brief Does this Chain have only One Node + * + * This function returns TRUE if there is only one node on @a the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * + * @return This function returns TRUE if there is only one node on + * @a the_chain and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Chain_Has_only_one_node( Chain_Control *the_chain ) { - return ( the_chain->first == the_chain->last ); + return (the_chain->first == the_chain->last); } -/** - * This function returns TRUE if the_node is the head of the_chain and +/** @brief Is this Node the Chain Head + * + * This function returns TRUE if @a the_node is the head of the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to check for being the Chain Head. + * + * @return This function returns TRUE if @a the_node is the head of + * @a the_chain and FALSE otherwise. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_head( Chain_Control *the_chain, Chain_Node *the_node ) { - return ( the_node == _Chain_Head( the_chain ) ); + return (the_node == _Chain_Head(the_chain)); } -/** +/** @brief Is this Node the Chail Tail + * * This function returns TRUE if the_node is the tail of the_chain and * FALSE otherwise. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to check for being the Chain Tail. */ RTEMS_INLINE_ROUTINE boolean _Chain_Is_tail( Chain_Control *the_chain, Chain_Node *the_node ) { - return ( the_node == _Chain_Tail( the_chain ) ); + return (the_node == _Chain_Tail(the_chain)); } -/** +/** @brief Initialize this Chain as Empty + * * This routine initializes the specified chain to contain zero nodes. + * + * @param[in] the_chain is the chain to be initialized. */ - RTEMS_INLINE_ROUTINE void _Chain_Initialize_empty( Chain_Control *the_chain ) { - the_chain->first = _Chain_Tail( the_chain ); + the_chain->first = _Chain_Tail(the_chain); the_chain->permanent_null = NULL; - the_chain->last = _Chain_Head( the_chain ); + the_chain->last = _Chain_Head(the_chain); } -/** +/** @brief Extract this Node (unprotected) + * * This routine extracts the_node from the chain on which it resides. - * It does NOT disable interrupts to insure the atomicity of the + * It does NOT disable interrupts to ensure the atomicity of the * extract operation. + * + * @param[in] the_node is the node to be extracted. */ RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected( Chain_Node *the_node @@ -180,10 +247,19 @@ RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected( previous->next = next; } -/** +/** @brief Get the First Node (unprotected) + * * This function removes the first node from the_chain and returns - * a pointer to that node. It does NOT disable interrupts to insure + * a pointer to that node. It does NOT disable interrupts to ensure * the atomicity of the get operation. + * + * @param[in] the_chain is the chain to attempt to get the first node from. + * + * @return This method returns the first node on the chain even if it is + * the Chain Tail. + * + * @note This routine assumes that there is at least one node on the chain + * and always returns a node even if it is the Chain Tail. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected( Chain_Control *the_chain @@ -195,33 +271,46 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected( return_node = the_chain->first; new_first = return_node->next; the_chain->first = new_first; - new_first->previous = _Chain_Head( the_chain ); + new_first->previous = _Chain_Head(the_chain); return return_node; } -/** +/** @brief Get the First Node (unprotected) + * * 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 does NOT disable interrupts to insure the atomicity of the - * get operation. + * + * @param[in] the_chain is the chain to attempt to get the first node from. + * + * @return This method returns the first node on the chain or NULL if the + * chain is empty. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * get operation. */ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_unprotected( Chain_Control *the_chain ) { - if ( !_Chain_Is_empty( the_chain ) ) - return _Chain_Get_first_unprotected( the_chain ); + if ( !_Chain_Is_empty(the_chain)) + return _Chain_Get_first_unprotected(the_chain); else return NULL; } -/** +/** @brief Insert a Node (unprotected) + * * This routine inserts the_node on a chain immediately following - * after_node. It does NOT disable interrupts to insure the atomicity - * of the extract operation. + * after_node. + * + * @param[in] after_node is the node which will precede @a the_node on the + * chain. + * @param[in] the_node is the node to be inserted. + * + * @note It does NOT disable interrupts to ensure the atomicity + * of the extract operation. */ - RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected( Chain_Node *after_node, Chain_Node *the_node @@ -236,10 +325,15 @@ RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected( before_node->previous = the_node; } -/** +/** @brief Append a Node (unprotected) + * * This routine appends the_node onto the end of the_chain. - * It does NOT disable interrupts to insure the atomicity of the - * append operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be appended. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * append operation. */ RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected( Chain_Control *the_chain, @@ -248,37 +342,47 @@ RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected( { Chain_Node *old_last_node; - the_node->next = _Chain_Tail( the_chain ); + the_node->next = _Chain_Tail(the_chain); old_last_node = the_chain->last; the_chain->last = the_node; old_last_node->next = the_node; the_node->previous = old_last_node; } -/** +/** @brief Prepend a Node (unprotected) + * * This routine prepends the_node onto the front of the_chain. - * It does NOT disable interrupts to insure the atomicity of the - * prepend operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be prepended. + * + * @note It does NOT disable interrupts to ensure the atomicity of the + * prepend operation. */ RTEMS_INLINE_ROUTINE void _Chain_Prepend_unprotected( Chain_Control *the_chain, Chain_Node *the_node ) { - _Chain_Insert_unprotected( _Chain_Head( the_chain ), the_node ); + _Chain_Insert_unprotected(_Chain_Head(the_chain), the_node); } -/** +/** @brief Prepend a Node (protected) + * * This routine prepends the_node onto the front of the_chain. - * It disables interrupts to insure the atomicity of the - * prepend operation. + * + * @param[in] the_chain is the chain to be operated upon. + * @param[in] the_node is the node to be prepended. + * + * @note It disables interrupts to ensure the atomicity of the + * prepend operation. */ RTEMS_INLINE_ROUTINE void _Chain_Prepend( Chain_Control *the_chain, Chain_Node *the_node ) { - _Chain_Insert( _Chain_Head( the_chain ), the_node ); + _Chain_Insert(_Chain_Head(the_chain), the_node); } /**@}*/ diff --git a/cpukit/score/inline/rtems/score/coremutex.inl b/cpukit/score/inline/rtems/score/coremutex.inl index e186b197cd..2bde4a888f 100644 --- a/cpukit/score/inline/rtems/score/coremutex.inl +++ b/cpukit/score/inline/rtems/score/coremutex.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -25,10 +25,15 @@ */ /** + * @brief Is Mutex Locked + * * This routine returns TRUE if the mutex specified is locked and FALSE * otherwise. + * + * @param[in] the_mutex is the mutex to check + * + * @return This method returns TRUE if the mutex is locked. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_locked( CORE_mutex_Control *the_mutex ) @@ -37,10 +42,15 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_locked( } /** + * @brief Does Core Mutex Use FIFO Blocking + * * This routine returns TRUE if the mutex's wait discipline is FIFO and FALSE * otherwise. + * + * @param[in] the_attribute is the attribute set of the mutex + * + * @return This method returns TRUE if the mutex is using FIFO blocking order. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_fifo( CORE_mutex_Attributes *the_attribute ) @@ -49,10 +59,16 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_fifo( } /** + * @brief Doex Core Mutex Use Priority Blocking + * * This routine returns TRUE if the mutex's wait discipline is PRIORITY and * FALSE otherwise. + * + * @param[in] the_attribute is the attribute set of the mutex + * + * @return This method returns TRUE if the mutex is using + * priority blocking order. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority( CORE_mutex_Attributes *the_attribute ) @@ -61,10 +77,16 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority( } /** + * @brief Does Mutex Use Priority Inheritance + * * This routine returns TRUE if the mutex's wait discipline is * INHERIT_PRIORITY and FALSE otherwise. + * + * @param[in] the_attribute is the attribute set of the mutex + * + * @return This method returns TRUE if the mutex is using priority + * inheritance. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_inherit_priority( CORE_mutex_Attributes *the_attribute ) @@ -73,10 +95,16 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_inherit_priority( } /** + * @brief Does Mutex Use Priority Ceiling + * * This routine returns TRUE if the mutex's wait discipline is * PRIORITY_CEILING and FALSE otherwise. + * + * @param[in] the_attribute is the attribute set of the mutex + * + * @return This method returns TRUE if the mutex is using priority + * ceiling. */ - RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority_ceiling( CORE_mutex_Attributes *the_attribute ) @@ -85,14 +113,10 @@ RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_priority_ceiling( } /* - * This routine returns 0 if "trylock" can resolve whether or not the - * mutex is immediately obtained or there was an error attempting to - * get it. It returns 1 to indicate that the caller cannot obtain - * the mutex and will have to block to do so. - * - * NOTE: There is no MACRO version of this routine. - * A body is in coremutexseize.c that is duplicated - * from the .inl by hand. + * Seize Mutex with Quick Success Path + * + * NOTE: There is no MACRO version of this routine. A body is in + * coremutexseize.c that is duplicated from the .inl by hand. * * NOTE: The Doxygen for this routine is in the .h file. */ diff --git a/cpukit/score/inline/rtems/score/coresem.inl b/cpukit/score/inline/rtems/score/coresem.inl index 944c73190b..c7e6b69605 100644 --- a/cpukit/score/inline/rtems/score/coresem.inl +++ b/cpukit/score/inline/rtems/score/coresem.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -31,7 +31,7 @@ * This function returns TRUE if the priority attribute is * enabled in the attribute_set and FALSE otherwise. * - * @param the_attribute (in) is the attribute set to test + * @param[in] the_attribute is the attribute set to test * @return TRUE if the priority attribute is enabled */ RTEMS_INLINE_ROUTINE boolean _CORE_semaphore_Is_priority( @@ -44,7 +44,7 @@ RTEMS_INLINE_ROUTINE boolean _CORE_semaphore_Is_priority( /** * This routine returns the current count associated with the semaphore. * - * @param the_semaphore (in) is the semaphore to obtain the count of + * @param[in] the_semaphore is the semaphore to obtain the count of * @return the current count of this semaphore */ RTEMS_INLINE_ROUTINE uint32_t _CORE_semaphore_Get_count( @@ -60,11 +60,11 @@ RTEMS_INLINE_ROUTINE uint32_t _CORE_semaphore_Get_count( * returns. Otherwise, the calling task is blocked until a unit becomes * available. * - * @param the_semaphore (in) is the semaphore to obtain - * @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_p (in) is a temporary variable used to contain the ISR + * @param[in] the_semaphore is the semaphore to obtain + * @param[in] id is the Id of the owning API level Semaphore object + * @param[in] wait is TRUE if the thread is willing to wait + * @param[in] timeout is the maximum number of ticks to block + * @param[in] level_p is a temporary variable used to contain the ISR * disable level cookie * * @note There is currently no MACRO version of this routine. diff --git a/cpukit/score/inline/rtems/score/heap.inl b/cpukit/score/inline/rtems/score/heap.inl index 645551e153..d34ce759ee 100644 --- a/cpukit/score/inline/rtems/score/heap.inl +++ b/cpukit/score/inline/rtems/score/heap.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -28,8 +28,12 @@ /** * This function returns the head of the specified heap. + * + * @param[in] the_heap points to the heap being operated upon + * + * @return This method returns a pointer to the dummy head of the free + * block list. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Head ( Heap_Control *the_heap ) @@ -39,8 +43,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Head ( /** * This function returns the tail of the specified heap. + * + * @param[in] the_heap points to the heap being operated upon + * + * @return This method returns a pointer to the dummy tail of the heap + * free list. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Tail ( Heap_Control *the_heap ) @@ -50,8 +58,11 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Tail ( /** * Return the first free block of the specified heap. + * + * @param[in] the_heap points to the heap being operated upon + * + * @return This method returns a pointer to the first free block. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_First ( Heap_Control *the_heap ) @@ -59,15 +70,13 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_First ( return _Heap_Head(the_heap)->next; } -/*PAGE - * - * _Heap_Last +/** + * Return the last free block of the specified heap. * - * DESCRIPTION: + * @param[in] the_heap points to the heap being operated upon * - * Return the last free block of the specified heap. + * @return This method returns a pointer to the last block on the free list. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Last ( Heap_Control *the_heap ) @@ -75,15 +84,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Last ( return _Heap_Tail(the_heap)->prev; } -/*PAGE - * - * _Heap_Block_remove - * - * DESCRIPTION: - * +/** * This function removes 'the_block' from doubly-linked list. + * + * @param[in] the_block is the block to remove from the heap used block + * list. */ - RTEMS_INLINE_ROUTINE void _Heap_Block_remove ( Heap_Block *the_block ) @@ -98,6 +104,14 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_remove ( /** * This function replaces @a old_block by @a new_block in doubly-linked list. + * When a block is allocated, the memory is allocated from the low memory + * address range of the block. This means that the upper address range of + * the memory block must be added to the free block list in place of the + * lower address portion being allocated. This method is also used as part + * of resizing a block. + * + * @param[in] old_block is the block which is currently on the list. + * @param[in] new_block is the new block which will replace it on the list. */ RTEMS_INLINE_ROUTINE void _Heap_Block_replace ( @@ -117,7 +131,10 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_replace ( /** * This function inserts @a the_block after @a prev_block - * in doubly-linked list. + * in the doubly-linked free block list. + * + * @param[in] prev_block is the previous block in the free list. + * @param[in] the_block is the block being freed. */ RTEMS_INLINE_ROUTINE void _Heap_Block_insert_after ( Heap_Block *prev_block, @@ -135,8 +152,13 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_insert_after ( /** * Return TRUE if @a value is a multiple of @a alignment, FALSE otherwise + * + * @param[in] value is the address to verify alignment of. + * @param[in] alignment is the alignment factor to verify. + * + * @return This method returns TRUE if the address is aligned and false + * otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned ( uint32_t value, uint32_t alignment @@ -147,8 +169,12 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned ( /** * Align @a *value up to the nearest multiple of @a alignment. + * + * @param[in] value is a pointer to be aligned. + * @param[in] alignment is the alignment value. + * + * @return Upon return, @a value will contain the aligned result. */ - RTEMS_INLINE_ROUTINE void _Heap_Align_up ( uint32_t *value, uint32_t alignment @@ -162,8 +188,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_up ( /** * Align @a *value down to the nearest multiple of @a alignment. + * + * @param[in] value is a pointer to be aligned. + * @param[in] alignment is the alignment value. + * + * @return Upon return, @a value will contain the aligned result. */ - RTEMS_INLINE_ROUTINE void _Heap_Align_down ( uint32_t *value, uint32_t alignment @@ -175,11 +205,16 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_down ( /** * Return TRUE if @a ptr is aligned at @a alignment boundary, - * FALSE otherwise + * FALSE otherwise. + * + * @param[in] ptr is the pointer to verify alignment of. + * @param[in] alignment is the alignment factor. + * + * @return This method returns TRUE if @a ptr is aligned at @a alignment + * boundary, and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned_ptr ( - void *ptr, + void *ptr, uint32_t alignment ) { @@ -188,8 +223,12 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned_ptr ( /** * Align @a *value up to the nearest multiple of @a alignment. + * + * @param[in] value is a pointer to be aligned. + * @param[in] alignment is the alignment value. + * + * @return Upon return, @a value will contain the aligned result. */ - RTEMS_INLINE_ROUTINE void _Heap_Align_up_uptr ( _H_uptr_t *value, uint32_t alignment @@ -203,8 +242,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_up_uptr ( /** * Align @a *value down to the nearest multiple of @a alignment. + * + * @param[in] value is a pointer to be aligned. + * @param[in] alignment is the alignment value. + * + * @return Upon return, @a value will contain the aligned result. */ - RTEMS_INLINE_ROUTINE void _Heap_Align_down_uptr ( _H_uptr_t *value, uint32_t alignment @@ -217,10 +260,14 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_down_uptr ( /** * This function calculates and returns a block's location (address) * in the heap based upon a base address @a base and an @a offset. + * + * @param[in] base is the base address of the memory area. + * @param[in] offset is the byte offset into @a base. + * + * @return This method returns a pointer to the block's address. */ - RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_at( - void *base, + void *base, uint32_t offset ) { @@ -230,8 +277,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_at( /** * This function returns the starting address of the portion of @a the_block * which the user may access. + * + * @param[in] the_block is the heap block to find the user area of. + * + * @return This method returns a pointer to the start of the user area in + * the block. */ - RTEMS_INLINE_ROUTINE void *_Heap_User_area ( Heap_Block *the_block ) @@ -242,8 +293,14 @@ RTEMS_INLINE_ROUTINE void *_Heap_User_area ( /** * Fill @a *the_block with the address of the beginning of the block given * pointer to the user accessible area @a base. + * + * @param[in] the_heap points to the heap being operated upon + * @param[in] base points to the user area in the block. + * @param[in] the_block will be the address of the heap block. + * + * @return This method returns a pointer to the heap block based upon the + * given heap and user pointer. */ - RTEMS_INLINE_ROUTINE void _Heap_Start_of_block ( Heap_Control *the_heap, void *base, @@ -262,8 +319,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Start_of_block ( /** * This function returns TRUE if the previous block of @a the_block * is in use, and FALSE otherwise. + * + * @param[in] the_block is the block to operate upon. + * + * @return This method returns TRUE if the previous block is used and FALSE + * if the previous block is free. */ - RTEMS_INLINE_ROUTINE boolean _Heap_Is_prev_used ( Heap_Block *the_block ) @@ -273,8 +334,11 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_prev_used ( /** * This function returns the size of @a the_block in bytes. + * + * @param[in] the_block is the block to operate upon. + * + * @return This method returns the size of the specified heap block in bytes. */ - RTEMS_INLINE_ROUTINE uint32_t _Heap_Block_size ( Heap_Block *the_block ) @@ -285,8 +349,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Heap_Block_size ( /** * This function returns TRUE if @a the_block is within the memory area * managed by @a the_heap, and FALSE otherwise. + * + * @param[in] the_heap points to the heap being operated upon + * @param[in] the_block is the block address to check. + * + * @return This method returns TRUE if @a the_block appears to have been + * allocated from @a the_heap, and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Heap_Is_block_in ( Heap_Control *the_heap, Heap_Block *the_block diff --git a/cpukit/score/inline/rtems/score/object.inl b/cpukit/score/inline/rtems/score/object.inl index ac6d873fc8..e3e17bdb69 100644 --- a/cpukit/score/inline/rtems/score/object.inl +++ b/cpukit/score/inline/rtems/score/object.inl @@ -7,7 +7,7 @@ * This include file contains the static inline implementation of all * of the inlined routines in the Object Handler. * - * COPYRIGHT (c) 1989-2002. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -20,16 +20,18 @@ #ifndef _RTEMS_SCORE_OBJECT_INL #define _RTEMS_SCORE_OBJECT_INL -/*PAGE - * - * _Objects_Build_id - * - * DESCRIPTION: - * +/** * This function builds an object's id from the processor node and index * values specified. + * + * @param[in] the_api indicates the API associated with this Id. + * @param[in] the_class indicates the class of object. + * It is specific to @a the_api. + * @param[in] node is the node where this object resides. + * @param[in] index is the instance number of this object. + * + * @return This method returns an object Id constructed from the arguments. */ - RTEMS_INLINE_ROUTINE Objects_Id _Objects_Build_id( Objects_APIs the_api, uint32_t the_class, @@ -43,15 +45,13 @@ RTEMS_INLINE_ROUTINE Objects_Id _Objects_Build_id( (( (Objects_Id) index ) << OBJECTS_INDEX_START_BIT); } -/*PAGE - * - * _Objects_Get_API +/** + * This function returns the API portion of the ID. * - * DESCRIPTION: + * @param[in] id is the object Id to be processed. * - * This function returns the API portion of the ID. + * @return This method returns an object Id constructed from the arguments. */ - RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API( Objects_Id id ) @@ -59,15 +59,11 @@ RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API( return (Objects_APIs) ((id >> OBJECTS_API_START_BIT) & OBJECTS_API_VALID_BITS); } -/*PAGE - * - * _Objects_Get_class - * - * DESCRIPTION: - * +/** * This function returns the class portion of the ID. + * + * @param[in] id is the object Id to be processed */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_class( Objects_Id id ) @@ -76,15 +72,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_class( ((id >> OBJECTS_CLASS_START_BIT) & OBJECTS_CLASS_VALID_BITS); } -/*PAGE - * - * _Objects_Get_node +/** + * This function returns the node portion of the ID. * - * DESCRIPTION: + * @param[in] id is the object Id to be processed * - * This function returns the node portion of the ID. + * @return This method returns the node portion of an object ID. */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_node( Objects_Id id ) @@ -92,15 +86,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_node( return (id >> OBJECTS_NODE_START_BIT) & OBJECTS_NODE_VALID_BITS; } -/*PAGE - * - * _Objects_Get_index +/** + * This function returns the index portion of the ID. * - * DESCRIPTION: + * @param[in] id is the Id to be processed * - * This function returns the index portion of the ID. + * @return This method returns the class portion of the specified object ID. */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_index( Objects_Id id ) @@ -108,15 +100,14 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_index( return (id >> OBJECTS_INDEX_START_BIT) & OBJECTS_INDEX_VALID_BITS; } -/*PAGE - * - * _Objects_Is_class_valid +/** + * This function returns TRUE if the class is valid. * - * DESCRIPTION: + * @param[in] the_class is the class portion of an object ID. * - * This function returns TRUE if the class is valid. + * @return This method returns TRUE if the specified class value is valid + * and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Is_class_valid( uint32_t the_class ) @@ -125,17 +116,17 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_class_valid( return TRUE; /* the_class && the_class <= OBJECTS_CLASSES_LAST; */ } -/*PAGE - * - * _Objects_Is_local_node - * - * DESCRIPTION: - * +#if defined(RTEMS_MULTIPROCESSING) +/** * This function returns TRUE if the node is of the local object, and * FALSE otherwise. + * + * @param[in] node is the node number and corresponds to the node number + * portion of an object ID. + * + * @return This method returns TRUE if the specified node is the local node + * and FALSE otherwise. */ - -#if defined(RTEMS_MULTIPROCESSING) RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_node( uint32_t node ) @@ -144,16 +135,17 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_node( } #endif -/*PAGE +/** + * This function returns TRUE if the id is of a local object, and + * FALSE otherwise. * - * _Objects_Is_local_id + * @param[in] id is an object ID * - * DESCRIPTION: + * @return This method returns TRUE if the specified object Id is local + * and FALSE otherwise. * - * This function returns TRUE if the id is of a local object, and - * FALSE otherwise. + * @note On a single processor configuration, this always returns TRUE. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_id( Objects_Id id ) @@ -165,17 +157,16 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_id( #endif } - -/*PAGE - * - * _Objects_Are_ids_equal - * - * DESCRIPTION: - * +/** * This function returns TRUE if left and right are equal, * and FALSE otherwise. + * + * @param[in] left is the Id on the left hand side of the comparison + * @param[in] right is the Id on the right hand side of the comparison + * + * @return This method returns TRUE if the specified object IDs are equal + * and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Are_ids_equal( Objects_Id left, Objects_Id right @@ -184,16 +175,16 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Are_ids_equal( return ( left == right ); } -/*PAGE - * - * _Objects_Get_local_object - * - * DESCRIPTION: - * +/** * This function returns a pointer to the local_table object * referenced by the index. + * + * @param[in] information points to an Object Information Table + * @param[in] index is the index of the object the caller wants to access + * + * @return This method returns a pointer to a local object or NULL if the + * index is invalid. */ - RTEMS_INLINE_ROUTINE Objects_Control *_Objects_Get_local_object( Objects_Information *information, uint16_t index @@ -204,14 +195,13 @@ RTEMS_INLINE_ROUTINE Objects_Control *_Objects_Get_local_object( return information->local_table[ index ]; } -/*PAGE - * - * _Objects_Set_local_object - * - * DESCRIPTION: - * +/** * This function sets the pointer to the local_table object * referenced by the index. + * + * @param[in] information points to an Object Information Table + * @param[in] index is the index of the object the caller wants to access + * @param[in] the_object is the local object pointer */ RTEMS_INLINE_ROUTINE void _Objects_Set_local_object( @@ -224,17 +214,16 @@ RTEMS_INLINE_ROUTINE void _Objects_Set_local_object( information->local_table[ index ] = the_object; } - -/*PAGE +/** + * This function return the information structure given + * an id of an object. * - * _Objects_Get_information + * @param[in] id is an object ID * - * DESCRIPTION: * - * This function return the information structure given - * an id of an object. + * @return This method returns a pointer to the Object Information Table + * for the class of objects which corresponds to this object ID. */ - RTEMS_INLINE_ROUTINE Objects_Information *_Objects_Get_information( Objects_Id id ) @@ -252,16 +241,14 @@ RTEMS_INLINE_ROUTINE Objects_Information *_Objects_Get_information( return _Objects_Information_table[ the_api ][ the_class ]; } -/*PAGE - * - * _Objects_Open - * - * DESCRIPTION: - * +/** * This function places the_object control pointer and object name * in the Local Pointer and Local Name Tables, respectively. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object + * @param[in] name is the name of the object to make accessible */ - RTEMS_INLINE_ROUTINE void _Objects_Open( Objects_Information *information, Objects_Control *the_object, @@ -281,16 +268,13 @@ RTEMS_INLINE_ROUTINE void _Objects_Open( the_object->name = name; } -/*PAGE - * - * _Objects_Close - * - * DESCRIPTION: - * +/** * This function removes the_object control pointer and object name * in the Local Pointer and Local Name Tables. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object */ - RTEMS_INLINE_ROUTINE void _Objects_Close( Objects_Information *information, Objects_Control *the_object @@ -304,15 +288,12 @@ RTEMS_INLINE_ROUTINE void _Objects_Close( the_object->name = 0; } -/*PAGE - * - * _Objects_Namespace_remove - * - * DESCRIPTION: - * +/** * This function removes the_object from the namespace. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object */ - RTEMS_INLINE_ROUTINE void _Objects_Namespace_remove( Objects_Information *information, Objects_Control *the_object diff --git a/cpukit/score/inline/rtems/score/stack.inl b/cpukit/score/inline/rtems/score/stack.inl index 83df22fd2a..863d703aa3 100644 --- a/cpukit/score/inline/rtems/score/stack.inl +++ b/cpukit/score/inline/rtems/score/stack.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -53,7 +53,7 @@ RTEMS_INLINE_ROUTINE boolean _Stack_Is_enough ( } /** - * This function increases the stack size to insure that the thread + * This function increases the stack size to ensure that the thread * has the desired amount of stack space after the initial stack * pointer is determined based on alignment restrictions. * diff --git a/cpukit/score/inline/rtems/score/thread.inl b/cpukit/score/inline/rtems/score/thread.inl index 0ac5887588..1599883d70 100644 --- a/cpukit/score/inline/rtems/score/thread.inl +++ b/cpukit/score/inline/rtems/score/thread.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -224,7 +224,11 @@ RTEMS_INLINE_ROUTINE boolean _Thread_Is_null ( * Otherwise, location is set to OBJECTS_ERROR and * the_thread is undefined. * - * @note XXX... This routine may be able to be optimized. + * @note The performance of many RTEMS services depends upon + * the quick execution of the "good object" path in this + * routine. If there is a possibility of saving a few + * cycles off the execution time, this routine is worth + * further optimization attention. */ RTEMS_INLINE_ROUTINE Thread_Control *_Thread_Get ( diff --git a/cpukit/score/inline/rtems/score/tqdata.inl b/cpukit/score/inline/rtems/score/tqdata.inl index c7f878baea..d1248f4b74 100644 --- a/cpukit/score/inline/rtems/score/tqdata.inl +++ b/cpukit/score/inline/rtems/score/tqdata.inl @@ -6,7 +6,7 @@ */ /* - * COPYRIGHT (c) 1989-2004. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -61,5 +61,9 @@ RTEMS_INLINE_ROUTINE void _Thread_queue_Enter_critical_section ( the_thread_queue->sync_state = THREAD_QUEUE_NOTHING_HAPPENED; } +/** + * @} + */ + #endif /* end of include file */ -- cgit v1.2.3