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/heap.inl | 135 +++++++++++++++++++++++-------- 1 file changed, 102 insertions(+), 33 deletions(-) (limited to 'cpukit/score/inline/rtems/score/heap.inl') 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 -- cgit v1.2.3