Changeset 4c99921 in rtems


Ignore:
Timestamp:
Apr 9, 2019, 6:50:24 AM (6 months ago)
Author:
Andreas Dachsberger <andreas.dachsberger@…>
Branches:
master
Children:
0cdcb27
Parents:
cf6ce4a
git-author:
Andreas Dachsberger <andreas.dachsberger@…> (04/09/19 06:50:24)
git-committer:
Sebastian Huber <sebastian.huber@…> (05/13/19 05:42:03)
Message:

doxygen: score: adjust doc in heapimpl.h to doxygen guidelines

Update #3706.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/include/rtems/score/heapimpl.h

    rcf6ce4a r4c99921  
    2727/**
    2828 * @addtogroup RTEMSScoreHeap
    29  */
    30 /**@{**/
     29 *
     30 * @{
     31 */
    3132
    3233/**
     
    5152
    5253/**
    53  * @brief Gets the first and last block for the heap area with begin
    54  * @a heap_area_begin and size @a heap_area_size.
    55  *
    56  * A page size of @a page_size and minimal block size of @a min_block_size will
    57  * be used for calculation.
     54 * @brief Gets the first and last block for the heap area.
    5855 *
    5956 * Nothing will be written to this area.
    6057 *
    61  * In case of success the pointers to the first and last block will be returned
    62  * via @a first_block_ptr and @a last_block_ptr.
    63  *
    64  * Returns @c true if the area is big enough, and @c false otherwise.
     58 * @param heap_area_begin The starting address of the heap area.
     59 * @param heap_area_size The size of the heap area.
     60 * @param page_size The page size for the calculation.
     61 * @param min_block_size The minimal block size for the calculation.
     62 * @param[out] first_block_ptr The pointer to the first block in the case of success
     63 * @param[out] last_block_ptr The pointer to the last block in the case of success
     64 *
     65 * @retval true The area is big enough.
     66 * @retval false The area is not big enough.
    6567 */
    6668bool _Heap_Get_first_and_last_block(
     
    7476
    7577/**
    76  * @brief Initializes the heap control block @a heap to manage the area
    77  * starting at @a area_begin of size @a area_size bytes.
     78 * @brief Initializes the heap control block.
    7879 *
    7980 * Blocks of memory are allocated from the heap in multiples of @a page_size
     
    8182 * @c CPU_ALIGNMENT, it is aligned up to the nearest @c CPU_ALIGNMENT boundary.
    8283 *
    83  * Returns the maximum memory available, or zero in case of failure.
     84 * @param[out] heap The heap control block to manage the area.
     85 * @param area_begin The starting address of the area.
     86 * @param area_size The size of the area in bytes.
     87 * @param page_size The page size for the calculation
     88 *
     89 * @retval some_value The maximum memory available.
     90 * @retval 0 The initialization failed.
    8491 *
    8592 * @see Heap_Initialization_or_extend_handler.
     
    93100
    94101/**
    95  * @brief Allocates a memory area of size @a size bytes from the heap @a heap.
    96  *
    97  * If the alignment parameter @a alignment is not equal to zero, the allocated
    98  * memory area will begin at an address aligned by this value.
    99  *
    100  * If the boundary parameter @a boundary is not equal to zero, the allocated
    101  * memory area will fulfill a boundary constraint.  The boundary value
    102  * specifies the set of addresses which are aligned by the boundary value.  The
    103  * interior of the allocated memory area will not contain an element of this
    104  * set.  The begin or end address of the area may be a member of the set.
     102 * @brief Allocates an aligned memory area with boundary constraint.
    105103 *
    106104 * A size value of zero will return a unique address which may be freed with
    107105 * _Heap_Free().
    108106 *
    109  * Returns a pointer to the begin of the allocated memory area, or @c NULL if
    110  * no memory is available or the parameters are inconsistent.
     107 * @param[in, out] heap The heap to allocate a memory are from.
     108 * @param size The size of the desired memory are in bytes.
     109 * @param alignment The allocated memory area will begin at an address aligned by this value.
     110 * @param boundary The allocated memory area will fulfill a boundary constraint,
     111 *      if this value is not equal to zero.  The boundary value specifies
     112 *      the set of addresses which are aligned by the boundary value.  The
     113 *      interior of the allocated memory area will not contain an element of this
     114 *      set.  The begin or end address of the area may be a member of the set.
     115 *
     116 * @retval pointer The starting address of the allocated memory area.
     117 * @retval NULL No memory is available of the parameters are inconsistent.
    111118 */
    112119void *_Heap_Allocate_aligned_with_boundary(
     
    118125
    119126/**
    120  * @brief See _Heap_Allocate_aligned_with_boundary() with boundary equals zero.
     127 * @brief Allocates an aligned memory area.
     128 *
     129 * A size value of zero will return a unique address which may be freed with
     130 * _Heap_Free().
     131 *
     132 * @param[in, out] heap The heap to allocate a memory are from.
     133 * @param size The size of the desired memory are in bytes.
     134 * @param alignment The allocated memory area will begin at an address aligned by this value.
     135 *
     136 * @retval pointer The starting address of the allocated memory area.
     137 * @retval NULL No memory is available of the parameters are inconsistent.
    121138 */
    122139RTEMS_INLINE_ROUTINE void *_Heap_Allocate_aligned(
     
    130147
    131148/**
    132  * @brief See _Heap_Allocate_aligned_with_boundary() with alignment and
    133  * boundary equals zero.
     149 * @brief Allocates a memory area.
     150 *
     151 * A size value of zero will return a unique address which may be freed with
     152 * _Heap_Free().
     153 *
     154 * @param[in, out] heap The heap to allocate a memory are from.
     155 * @param size The size of the desired memory are in bytes.
     156 *
     157 * @retval pointer The starting address of the allocated memory area.
     158 * @retval NULL No memory is available of the parameters are inconsistent.
    134159 */
    135160RTEMS_INLINE_ROUTINE void *_Heap_Allocate( Heap_Control *heap, uintptr_t size )
     
    139164
    140165/**
    141  * @brief Frees the allocated memory area starting at @a addr in the heap
    142  * @a heap.
     166 * @brief Frees the allocated memory area.
    143167 *
    144168 * Inappropriate values for @a addr may corrupt the heap.
    145169 *
    146  * Returns @c true in case of success, and @c false otherwise.
     170 * @param[in, out] heap The heap of the allocated memory area.
     171 * @param addr The starting address of the memory area to be freed.
     172 *
     173 * @retval true The allocated memory area was successfully freed.
     174 * @retval false The method failed.
    147175 */
    148176bool _Heap_Free( Heap_Control *heap, void *addr );
    149177
    150178/**
    151  * @brief Walks the heap @a heap to verify its integrity.
    152  *
    153  * If @a dump is @c true, then diagnostic messages will be printed to standard
    154  * output.  In this case @a source is used to mark the output lines.
    155  *
    156  * Returns @c true if no errors occurred, and @c false if the heap is corrupt.
     179 * @brief Verifies the integrity of the heap.
     180 *
     181 * Walks the heap to verify its integrity.
     182 *
     183 * @param heap The heap whose integrity is to be verified.
     184 * @param source If @a dump is @c true, this is used to mark the output lines.
     185 * @param dump Indicates whether diagnostic messages will be printed to standard output.
     186 *
     187 * @retval true No errors occured, the heapÂŽs integrity is not violated.
     188 * @retval false The heap is corrupt.
    157189 */
    158190bool _Heap_Walk(
     
    180212 * @brief Iterates over all blocks of the heap.
    181213 *
    182  * For each block the @a visitor with the argument @a visitor_arg will be
    183  * called.
     214 * @param[in, out] heap The heap to iterate over.
     215 * @param visitor This will be called for each heap block with
     216 *      the argument @a visitor_arg.
     217 * @param[in, out] visitor_arg The argument for all calls of @a visitor.
    184218 */
    185219void _Heap_Iterate(
     
    190224
    191225/**
    192  * @brief Greedy allocate that empties the heap.
    193  *
    194  * Afterwards the heap has at most @a block_count allocatable blocks of sizes
    195  * specified by @a block_sizes.  The @a block_sizes must point to an array with
    196  * @a block_count members.  All other blocks are used.
     226 * @brief Greedily allocates and empties the heap.
     227 *
     228 * Afterwards, the heap has at most @a block_count allocatable blocks of sizes
     229 * specified by @a block_sizes.  All other blocks are used.
     230 *
     231 * @param[in, out] heap The heap to operate upon
     232 * @param block_sizes The sizes of the allocatable blocks.  Must point to an
     233 *      array with @a block_count members.
     234 * @param block_count The maximum number of allocatable blocks of sizes
     235 *      specified by @block_sizes.
     236 *
     237 * @return Pointer to the first allocated block.
    197238 *
    198239 * @see _Heap_Greedy_free().
     
    205246
    206247/**
    207  * @brief Greedy allocate all blocks except the largest free block.
     248 * @brief Greedily allocates all blocks except the largest free block.
    208249 *
    209250 * Afterwards the heap has at most one allocatable block.  This block is the
    210  * largest free block if it exists.  The allocatable size of this block is
    211  * stored in @a allocatable_size.  All other blocks are used.
     251 * largest free block if it exists.  All other blocks are used.
     252 *
     253 * @param[in, out] heap The heap to operate upon.
     254 * @param[out] allocatable_size Stores the size of the largest free block of
     255 *      the heap after the method call.
     256 *
     257 * @return Pointer to the first allocated block.
    212258 *
    213259 * @see _Heap_Greedy_free().
     
    221267 * @brief Frees blocks of a greedy allocation.
    222268 *
    223  * The @a blocks must be the return value of _Heap_Greedy_allocate().
     269 * @param[in, out] heap The heap to operate upon.
     270 * @param blocks Must be the return value of _Heap_Greedy_allocate().
    224271 */
    225272void _Heap_Greedy_free(
     
    229276
    230277/**
    231  * @brief Returns information about used and free blocks for the heap @a heap
    232  * in @a info.
     278 * @brief Returns information about used and free blocks for the heap.
     279 *
     280 * @param heap The heap to get the information from.
     281 * @param[out] info Stores the information of the @a heap after the method call.
    233282 */
    234283void _Heap_Get_information(
     
    238287
    239288/**
    240  * @brief Returns information about free blocks for the heap @a heap in
    241  * @a info.
     289 * @brief Returns information about free blocks for the heap.
     290 *
     291 * @param heap The heap to get the information from.
     292 * @param[out] info Stores the information about free blocks of @a heap after the
     293 *      method call.
    242294 */
    243295void _Heap_Get_free_information(
     
    247299
    248300/**
    249  * @brief Returns the size of the allocatable memory area starting at @a addr
    250  * in @a size.
     301 * @brief Returns the size of the allocatable memory area.
    251302 *
    252303 * The size value may be greater than the initially requested size in
     
    256307 * invalid size values.
    257308 *
    258  * Returns @a true if successful, and @c false otherwise.
     309 * @param heap The heap to operate upon.
     310 * @param addr The starting address of the allocatable memory area.
     311 * @param[out] size Stores the size of the allocatable memory area after the method call.
     312 *
     313 * @retval true The operation was successful.
     314 * @retval false The operation was not successful.
    259315 */
    260316bool _Heap_Size_of_alloc_area(
     
    265321
    266322/**
    267  * @brief Resizes the block of the allocated memory area starting at @a addr.
    268  *
    269  * The new memory area will have a size of at least @a size bytes.  A resize
    270  * may be impossible and depends on the current heap usage.
    271  *
    272  * The size available for allocation in the current block before the resize
    273  * will be returned in @a old_size.  The size available for allocation in
    274  * the resized block will be returned in @a new_size.  If the resize was not
    275  * successful, then a value of zero will be returned in @a new_size.
     323 * @brief Resizes the block of the allocated memory area.
    276324 *
    277325 * Inappropriate values for @a addr may corrupt the heap.
     326 *
     327 * @param[in, out] heap The heap to operate upon.
     328 * @param addr The starting address of the allocated memory area to be resized.
     329 * @param size The least possible size for the new memory area.  Resize may be
     330 *      impossible and depends on the current heap usage.
     331 * @param[out] old_size Stores the size available for allocation in the current
     332 *      block before the resize after the method call.
     333 * @param[out] new_size Stores the size available for allocation in the resized
     334 *      block after the method call.  In the case of an unsuccessful resize,
     335 *      zero is returned in this parameter
     336 *
     337 * @retval HEAP_RESIZE_SUCCESSFUL The resize was successful.
     338 * @retval HEAP_RESIZE_UNSATISFIED The least possible size @a size was too big.
     339 *      Resize not possible.
     340 * @retval HEAP_RESIZE_FATAL_ERROR The block starting at @a addr is not part of
     341 *      the heap.
    278342 */
    279343Heap_Resize_status _Heap_Resize_block(
     
    286350
    287351/**
    288  * @brief Allocates the memory area starting at @a alloc_begin of size
     352 * @brief Allocates the memory area.
     353 * starting at @a alloc_begin of size
    289354 * @a alloc_size bytes in the block @a block.
    290355 *
     
    298363 * heap.
    299364 *
    300  * Returns the block containing the allocated memory area.
     365 * @param[in, out] heap The heap to operate upon.
     366 * @param block The block in which the memory area should be allocated
     367 * @param alloc_begin The starting address of the memory area that shall be allocated.
     368 * @param alloc_size The size of the desired allocated area in bytes.
     369 *
     370 * @return The block containing the allocated memory area.
    301371 */
    302372Heap_Block *_Heap_Block_allocate(
     
    355425 * fraction value of two.
    356426 *
    357  * @param[in] heap The heap control.
    358  * @param[in] fraction The fraction is one divided by this fraction value.
     427 * @param[in, out] heap The heap control.
     428 * @param fraction The fraction is one divided by this fraction value.
    359429 */
    360430RTEMS_INLINE_ROUTINE void _Heap_Protection_set_delayed_free_fraction(
     
    371441}
    372442
     443/**
     444 * @brief Returns the head of the free list of the heap.
     445 *
     446 * @param heap The heap to operate upon.
     447 *
     448 * @return The head of the free list.
     449 */
    373450RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Free_list_head( Heap_Control *heap )
    374451{
     
    376453}
    377454
     455/**
     456 * @brief Returns the tail of the free list of the heap.
     457 *
     458 * @param heap The heap to operate upon.
     459 *
     460 * @return The tail of the free list.
     461 */
    378462RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Free_list_tail( Heap_Control *heap )
    379463{
     
    381465}
    382466
     467/**
     468 * @brief Returns the first block of the free list of the heap.
     469 *
     470 * @param heap The heap to operate upon.
     471 *
     472 * @return The first block of the free list.
     473 */
    383474RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Free_list_first( Heap_Control *heap )
    384475{
     
    386477}
    387478
     479/**
     480 * @brief Returns the last block of the free list of the heap.
     481 *
     482 * @param heap The heap to operate upon.
     483 *
     484 * @return The last block of the free list.
     485 */
    388486RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Free_list_last( Heap_Control *heap )
    389487{
     
    391489}
    392490
     491/**
     492 * @brief Removes the block from the free list.
     493 *
     494 * @param block The block to be removed.
     495 */
    393496RTEMS_INLINE_ROUTINE void _Heap_Free_list_remove( Heap_Block *block )
    394497{
     
    400503}
    401504
     505/**
     506 * @brief Replaces one block in the free list by another.
     507 *
     508 * @param old_block The block in the free list to replace.
     509 * @param new_block The block that should replace @a old_block.
     510 */
    402511RTEMS_INLINE_ROUTINE void _Heap_Free_list_replace(
    403512  Heap_Block *old_block,
     
    415524}
    416525
     526/**
     527 * @brief Inserts a block after an existing block in the free list.
     528 *
     529 * @param block_before The block that is already in the free list.
     530 * @param new_block The block to be inserted after @a block_before.
     531 */
    417532RTEMS_INLINE_ROUTINE void _Heap_Free_list_insert_after(
    418533  Heap_Block *block_before,
     
    428543}
    429544
     545/**
     546 * @brief Inserts a block before an existing block in the free list.
     547 *
     548 * @param block_before The block that is already in the free list.
     549 * @param new_block The block to be inserted before @a block_before.
     550 */
    430551RTEMS_INLINE_ROUTINE void _Heap_Free_list_insert_before(
    431552  Heap_Block *block_next,
     
    441562}
    442563
     564/**
     565 * @brief Checks if the value is aligned to the given alignment.
     566 *
     567 * @param value The value to check the alignment of.
     568 * @param alignment The alignment for the operation.
     569 *
     570 * @retval true The value is aligned to the given alignment.
     571 * @retval false The value is not aligned to the given alignment.
     572 */
    443573RTEMS_INLINE_ROUTINE bool _Heap_Is_aligned(
    444574  uintptr_t value,
     
    449579}
    450580
     581/**
     582 * @brief Returns the aligned value, truncating.
     583 *
     584 * @param value The value to be aligned
     585 * @param alignment The alignment for the operation.
     586 *
     587 * @return The aligned value, truncated.
     588 */
    451589RTEMS_INLINE_ROUTINE uintptr_t _Heap_Align_down(
    452590  uintptr_t value,
     
    459597/**
    460598 * @brief Returns the block which is @a offset away from @a block.
     599 *
     600 * @param block The block for the relative calculation.
     601 * @param offset The offset for the calculation.
     602 *
     603 * @return The address of the block which is @a offset away from @a block.
    461604 */
    462605RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_at(
     
    468611}
    469612
     613/**
     614 * @brief Returns the address of the previous block.
     615 *
     616 * @param block The block of which the address of the previous block is requested.
     617 *
     618 * @return The address of the previous block.
     619 */
    470620RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Prev_block(
    471621  const Heap_Block *block
     
    475625}
    476626
     627/**
     628 * @brief Returns the first address in the block without the heap header.
     629 *
     630 * @param block The block for the operation.
     631 *
     632 * @return The first address after the heap header.
     633 */
    477634RTEMS_INLINE_ROUTINE uintptr_t _Heap_Alloc_area_of_block(
    478635  const Heap_Block *block
     
    482639}
    483640
     641/**
     642 * @brief Returns the starting address of the block corresponding to the allocatable area.
     643 *
     644 * @param alloc_begin The starting address of the allocatable area.
     645 * @param page_size The page size for the calculation.
     646 *
     647 * @return The Starting address of the corresponding block of the allocatable area.
     648 */
    484649RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_of_alloc_area(
    485650  uintptr_t alloc_begin,
     
    491656}
    492657
     658/**
     659 * @brief Returns the block size.
     660 *
     661 * @param block The block of which the size is requested.
     662 *
     663 * @return The block size.
     664 */
    493665RTEMS_INLINE_ROUTINE uintptr_t _Heap_Block_size( const Heap_Block *block )
    494666{
     
    496668}
    497669
     670/**
     671 * @brief Sets the block size.
     672 *
     673 * @param[in, out] block The block of which the size shall be set.
     674 * @param size The new size of the block.
     675 */
    498676RTEMS_INLINE_ROUTINE void _Heap_Block_set_size(
    499677  Heap_Block *block,
     
    506684}
    507685
     686/**
     687 * @brief Returns if the previous heap block is used.
     688 *
     689 * @param block The block of which the information about the previous
     690 *      block is requested.
     691 *
     692 * @retval true The previous block is used.
     693 * @retval false The previous block is not used.
     694 */
    508695RTEMS_INLINE_ROUTINE bool _Heap_Is_prev_used( const Heap_Block *block )
    509696{
     
    511698}
    512699
     700/**
     701 * @brief Returns if the heap block is used.
     702 *
     703 * @param block The block of which the information is requested.
     704 *
     705 * @retval true The block is used.
     706 * @retval false The block is not used.
     707 */
    513708RTEMS_INLINE_ROUTINE bool _Heap_Is_used(
    514709  const Heap_Block *block
     
    521716}
    522717
     718/**
     719 * @brief Returns if the heap block is free.
     720 *
     721 * @param block The block of which the information is requested.
     722 *
     723 * @retval true The block is free.
     724 * @retval false The block is not free.
     725 */
    523726RTEMS_INLINE_ROUTINE bool _Heap_Is_free(
    524727  const Heap_Block *block
     
    528731}
    529732
     733/**
     734 * @brief Returns if the block is part of the heap.
     735 *
     736 * @param heap The heap to test if the @a block is part of it.
     737 * @param block The block of which the information is requested.
     738 *
     739 * @retval true The block is part of the heap.
     740 * @retval false The block is not part of the heap.
     741 */
    530742RTEMS_INLINE_ROUTINE bool _Heap_Is_block_in_heap(
    531743  const Heap_Control *heap,
     
    538750
    539751/**
    540  * @brief Sets the size of the last block for heap @a heap.
     752 * @brief Sets the size of the last block for the heap.
    541753 *
    542754 * The next block of the last block will be the first block.  Since the first
     
    547759 * This feature will be used to terminate the scattered heap area list.  See
    548760 * also _Heap_Extend().
     761 *
     762 * @param[in, out] heap The heap to set the last block size of.
    549763 */
    550764RTEMS_INLINE_ROUTINE void _Heap_Set_last_block_size( Heap_Control *heap )
     
    560774 *
    561775 * This value is an integral multiple of the page size.
     776 *
     777 * @param heap The heap to get the allocatable area from.
     778 *
     779 * @return The size of the allocatable area in @a heap in bytes.
    562780 */
    563781RTEMS_INLINE_ROUTINE uintptr_t _Heap_Get_size( const Heap_Control *heap )
     
    566784}
    567785
     786/**
     787 * @brief Returns the bigger one of the two arguments.
     788 *
     789 * @param a The parameter on the left hand side of the comparison.
     790 * @param b The parameter on the right hand side of the comparison.
     791 *
     792 * @retval a If a > b.
     793 * @retval b If b >= a
     794 */
    568795RTEMS_INLINE_ROUTINE uintptr_t _Heap_Max( uintptr_t a, uintptr_t b )
    569796{
     
    571798}
    572799
     800/**
     801 * @brief Returns the smaller one of the two arguments.
     802 *
     803 * @param a The parameter on the left hand side of the comparison.
     804 * @param b The parameter on the right hand side of the comparison.
     805 *
     806 * @retval a If a < b.
     807 * @retval b If b <= a
     808 */
    573809RTEMS_INLINE_ROUTINE uintptr_t _Heap_Min( uintptr_t a, uintptr_t b )
    574810{
Note: See TracChangeset for help on using the changeset viewer.