begriffs open source - freertos/blob - portable/MemMang/heap_5.c

   1 /*
   2  * FreeRTOS Kernel <DEVELOPMENT BRANCH>
   3  * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
   4  *
   5  * SPDX-License-Identifier: MIT
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
   8  * this software and associated documentation files (the "Software"), to deal in
   9  * the Software without restriction, including without limitation the rights to
  10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  11  * the Software, and to permit persons to whom the Software is furnished to do so,
  12  * subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in all
  15  * copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  20  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  21  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  *
  24  * https://www.FreeRTOS.org
  25  * https://github.com/FreeRTOS
  26  *
  27  */
  28
  29 /*
  30  * A sample implementation of pvPortMalloc() that allows the heap to be defined
  31  * across multiple non-contigous blocks and combines (coalescences) adjacent
  32  * memory blocks as they are freed.
  33  *
  34  * See heap_1.c, heap_2.c, heap_3.c and heap_4.c for alternative
  35  * implementations, and the memory management pages of https://www.FreeRTOS.org
  36  * for more information.
  37  *
  38  * Usage notes:
  39  *
  40  * vPortDefineHeapRegions() ***must*** be called before pvPortMalloc().
  41  * pvPortMalloc() will be called if any task objects (tasks, queues, event
  42  * groups, etc.) are created, therefore vPortDefineHeapRegions() ***must*** be
  43  * called before any other objects are defined.
  44  *
  45  * vPortDefineHeapRegions() takes a single parameter.  The parameter is an array
  46  * of HeapRegion_t structures.  HeapRegion_t is defined in portable.h as
  47  *
  48  * typedef struct HeapRegion
  49  * {
  50  *  uint8_t *pucStartAddress; << Start address of a block of memory that will be part of the heap.
  51  *  size_t xSizeInBytes;      << Size of the block of memory.
  52  * } HeapRegion_t;
  53  *
  54  * The array is terminated using a NULL zero sized region definition, and the
  55  * memory regions defined in the array ***must*** appear in address order from
  56  * low address to high address.  So the following is a valid example of how
  57  * to use the function.
  58  *
  59  * HeapRegion_t xHeapRegions[] =
  60  * {
  61  *  { ( uint8_t * ) 0x80000000UL, 0x10000 }, << Defines a block of 0x10000 bytes starting at address 0x80000000
  62  *  { ( uint8_t * ) 0x90000000UL, 0xa0000 }, << Defines a block of 0xa0000 bytes starting at address of 0x90000000
  63  *  { NULL, 0 }                << Terminates the array.
  64  * };
  65  *
  66  * vPortDefineHeapRegions( xHeapRegions ); << Pass the array into vPortDefineHeapRegions().
  67  *
  68  * Note 0x80000000 is the lower address so appears in the array first.
  69  *
  70  */
  71 #include <stdlib.h>
  72 #include <string.h>
  73
  74 /* Defining MPU_WRAPPERS_INCLUDED_FROM_API_FILE prevents task.h from redefining
  75  * all the API functions to use the MPU wrappers.  That should only be done when
  76  * task.h is included from an application file. */
  77 #define MPU_WRAPPERS_INCLUDED_FROM_API_FILE
  78
  79 #include "FreeRTOS.h"
  80 #include "task.h"
  81
  82 #undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE
  83
  84 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 0 )
  85     #error This file must not be used if configSUPPORT_DYNAMIC_ALLOCATION is 0
  86 #endif
  87
  88 #ifndef configHEAP_CLEAR_MEMORY_ON_FREE
  89     #define configHEAP_CLEAR_MEMORY_ON_FREE    0
  90 #endif
  91
  92 /* Block sizes must not get too small. */
  93 #define heapMINIMUM_BLOCK_SIZE    ( ( size_t ) ( xHeapStructSize << 1 ) )
  94
  95 /* Assumes 8bit bytes! */
  96 #define heapBITS_PER_BYTE         ( ( size_t ) 8 )
  97
  98 /* Max value that fits in a size_t type. */
  99 #define heapSIZE_MAX              ( ~( ( size_t ) 0 ) )
 100
 101 /* Check if multiplying a and b will result in overflow. */
 102 #define heapMULTIPLY_WILL_OVERFLOW( a, b )    ( ( ( a ) > 0 ) && ( ( b ) > ( heapSIZE_MAX / ( a ) ) ) )
 103
 104 /* Check if adding a and b will result in overflow. */
 105 #define heapADD_WILL_OVERFLOW( a, b )         ( ( a ) > ( heapSIZE_MAX - ( b ) ) )
 106
 107 /* MSB of the xBlockSize member of an BlockLink_t structure is used to track
 108  * the allocation status of a block.  When MSB of the xBlockSize member of
 109  * an BlockLink_t structure is set then the block belongs to the application.
 110  * When the bit is free the block is still part of the free heap space. */
 111 #define heapBLOCK_ALLOCATED_BITMASK    ( ( ( size_t ) 1 ) << ( ( sizeof( size_t ) * heapBITS_PER_BYTE ) - 1 ) )
 112 #define heapBLOCK_SIZE_IS_VALID( xBlockSize )    ( ( ( xBlockSize ) & heapBLOCK_ALLOCATED_BITMASK ) == 0 )
 113 #define heapBLOCK_IS_ALLOCATED( pxBlock )        ( ( ( pxBlock->xBlockSize ) & heapBLOCK_ALLOCATED_BITMASK ) != 0 )
 114 #define heapALLOCATE_BLOCK( pxBlock )            ( ( pxBlock->xBlockSize ) |= heapBLOCK_ALLOCATED_BITMASK )
 115 #define heapFREE_BLOCK( pxBlock )                ( ( pxBlock->xBlockSize ) &= ~heapBLOCK_ALLOCATED_BITMASK )
 116
 117 /*-----------------------------------------------------------*/
 118
 119 /* Define the linked list structure.  This is used to link free blocks in order
 120  * of their memory address. */
 121 typedef struct A_BLOCK_LINK
 122 {
 123     struct A_BLOCK_LINK * pxNextFreeBlock; /**< The next free block in the list. */
 124     size_t xBlockSize;                     /**< The size of the free block. */
 125 } BlockLink_t;
 126
 127 /*-----------------------------------------------------------*/
 128
 129 /*
 130  * Inserts a block of memory that is being freed into the correct position in
 131  * the list of free memory blocks.  The block being freed will be merged with
 132  * the block in front it and/or the block behind it if the memory blocks are
 133  * adjacent to each other.
 134  */
 135 static void prvInsertBlockIntoFreeList( BlockLink_t * pxBlockToInsert );
 136
 137 /*-----------------------------------------------------------*/
 138
 139 /* The size of the structure placed at the beginning of each allocated memory
 140  * block must by correctly byte aligned. */
 141 static const size_t xHeapStructSize = ( sizeof( BlockLink_t ) + ( ( size_t ) ( portBYTE_ALIGNMENT - 1 ) ) ) & ~( ( size_t ) portBYTE_ALIGNMENT_MASK );
 142
 143 /* Create a couple of list links to mark the start and end of the list. */
 144 static BlockLink_t xStart;
 145 static BlockLink_t * pxEnd = NULL;
 146
 147 /* Keeps track of the number of calls to allocate and free memory as well as the
 148  * number of free bytes remaining, but says nothing about fragmentation. */
 149 static size_t xFreeBytesRemaining = 0U;
 150 static size_t xMinimumEverFreeBytesRemaining = 0U;
 151 static size_t xNumberOfSuccessfulAllocations = 0;
 152 static size_t xNumberOfSuccessfulFrees = 0;
 153
 154 /*-----------------------------------------------------------*/
 155
 156 void * pvPortMalloc( size_t xWantedSize )
 157 {
 158     BlockLink_t * pxBlock;
 159     BlockLink_t * pxPreviousBlock;
 160     BlockLink_t * pxNewBlockLink;
 161     void * pvReturn = NULL;
 162     size_t xAdditionalRequiredSize;
 163
 164     /* The heap must be initialised before the first call to
 165      * prvPortMalloc(). */
 166     configASSERT( pxEnd );
 167
 168     vTaskSuspendAll();
 169     {
 170         if( xWantedSize > 0 )
 171         {
 172             /* The wanted size must be increased so it can contain a BlockLink_t
 173              * structure in addition to the requested amount of bytes. */
 174             if( heapADD_WILL_OVERFLOW( xWantedSize, xHeapStructSize ) == 0 )
 175             {
 176                 xWantedSize += xHeapStructSize;
 177
 178                 /* Ensure that blocks are always aligned to the required number
 179                  * of bytes. */
 180                 if( ( xWantedSize & portBYTE_ALIGNMENT_MASK ) != 0x00 )
 181                 {
 182                     /* Byte alignment required. */
 183                     xAdditionalRequiredSize = portBYTE_ALIGNMENT - ( xWantedSize & portBYTE_ALIGNMENT_MASK );
 184
 185                     if( heapADD_WILL_OVERFLOW( xWantedSize, xAdditionalRequiredSize ) == 0 )
 186                     {
 187                         xWantedSize += xAdditionalRequiredSize;
 188                     }
 189                     else
 190                     {
 191                         xWantedSize = 0;
 192                     }
 193                 }
 194                 else
 195                 {
 196                     mtCOVERAGE_TEST_MARKER();
 197                 }
 198             }
 199             else
 200             {
 201                 xWantedSize = 0;
 202             }
 203         }
 204         else
 205         {
 206             mtCOVERAGE_TEST_MARKER();
 207         }
 208
 209         /* Check the block size we are trying to allocate is not so large that the
 210          * top bit is set.  The top bit of the block size member of the BlockLink_t
 211          * structure is used to determine who owns the block - the application or
 212          * the kernel, so it must be free. */
 213         if( heapBLOCK_SIZE_IS_VALID( xWantedSize ) != 0 )
 214         {
 215             if( ( xWantedSize > 0 ) && ( xWantedSize <= xFreeBytesRemaining ) )
 216             {
 217                 /* Traverse the list from the start (lowest address) block until
 218                  * one of adequate size is found. */
 219                 pxPreviousBlock = &xStart;
 220                 pxBlock = xStart.pxNextFreeBlock;
 221
 222                 while( ( pxBlock->xBlockSize < xWantedSize ) && ( pxBlock->pxNextFreeBlock != NULL ) )
 223                 {
 224                     pxPreviousBlock = pxBlock;
 225                     pxBlock = pxBlock->pxNextFreeBlock;
 226                 }
 227
 228                 /* If the end marker was reached then a block of adequate size
 229                  * was not found. */
 230                 if( pxBlock != pxEnd )
 231                 {
 232                     /* Return the memory space pointed to - jumping over the
 233                      * BlockLink_t structure at its start. */
 234                     pvReturn = ( void * ) ( ( ( uint8_t * ) pxPreviousBlock->pxNextFreeBlock ) + xHeapStructSize );
 235
 236                     /* This block is being returned for use so must be taken out
 237                      * of the list of free blocks. */
 238                     pxPreviousBlock->pxNextFreeBlock = pxBlock->pxNextFreeBlock;
 239
 240                     /* If the block is larger than required it can be split into
 241                      * two. */
 242                     if( ( pxBlock->xBlockSize - xWantedSize ) > heapMINIMUM_BLOCK_SIZE )
 243                     {
 244                         /* This block is to be split into two.  Create a new
 245                          * block following the number of bytes requested. The void
 246                          * cast is used to prevent byte alignment warnings from the
 247                          * compiler. */
 248                         pxNewBlockLink = ( void * ) ( ( ( uint8_t * ) pxBlock ) + xWantedSize );
 249
 250                         /* Calculate the sizes of two blocks split from the
 251                          * single block. */
 252                         pxNewBlockLink->xBlockSize = pxBlock->xBlockSize - xWantedSize;
 253                         pxBlock->xBlockSize = xWantedSize;
 254
 255                         /* Insert the new block into the list of free blocks. */
 256                         pxNewBlockLink->pxNextFreeBlock = pxPreviousBlock->pxNextFreeBlock;
 257                         pxPreviousBlock->pxNextFreeBlock = pxNewBlockLink;
 258                     }
 259                     else
 260                     {
 261                         mtCOVERAGE_TEST_MARKER();
 262                     }
 263
 264                     xFreeBytesRemaining -= pxBlock->xBlockSize;
 265
 266                     if( xFreeBytesRemaining < xMinimumEverFreeBytesRemaining )
 267                     {
 268                         xMinimumEverFreeBytesRemaining = xFreeBytesRemaining;
 269                     }
 270                     else
 271                     {
 272                         mtCOVERAGE_TEST_MARKER();
 273                     }
 274
 275                     /* The block is being returned - it is allocated and owned
 276                      * by the application and has no "next" block. */
 277                     heapALLOCATE_BLOCK( pxBlock );
 278                     pxBlock->pxNextFreeBlock = NULL;
 279                     xNumberOfSuccessfulAllocations++;
 280                 }
 281                 else
 282                 {
 283                     mtCOVERAGE_TEST_MARKER();
 284                 }
 285             }
 286             else
 287             {
 288                 mtCOVERAGE_TEST_MARKER();
 289             }
 290         }
 291         else
 292         {
 293             mtCOVERAGE_TEST_MARKER();
 294         }
 295
 296         traceMALLOC( pvReturn, xWantedSize );
 297     }
 298     ( void ) xTaskResumeAll();
 299
 300     #if ( configUSE_MALLOC_FAILED_HOOK == 1 )
 301     {
 302         if( pvReturn == NULL )
 303         {
 304             vApplicationMallocFailedHook();
 305         }
 306         else
 307         {
 308             mtCOVERAGE_TEST_MARKER();
 309         }
 310     }
 311     #endif /* if ( configUSE_MALLOC_FAILED_HOOK == 1 ) */
 312
 313     return pvReturn;
 314 }
 315 /*-----------------------------------------------------------*/
 316
 317 void vPortFree( void * pv )
 318 {
 319     uint8_t * puc = ( uint8_t * ) pv;
 320     BlockLink_t * pxLink;
 321
 322     if( pv != NULL )
 323     {
 324         /* The memory being freed will have an BlockLink_t structure immediately
 325          * before it. */
 326         puc -= xHeapStructSize;
 327
 328         /* This casting is to keep the compiler from issuing warnings. */
 329         pxLink = ( void * ) puc;
 330
 331         configASSERT( heapBLOCK_IS_ALLOCATED( pxLink ) != 0 );
 332         configASSERT( pxLink->pxNextFreeBlock == NULL );
 333
 334         if( heapBLOCK_IS_ALLOCATED( pxLink ) != 0 )
 335         {
 336             if( pxLink->pxNextFreeBlock == NULL )
 337             {
 338                 /* The block is being returned to the heap - it is no longer
 339                  * allocated. */
 340                 heapFREE_BLOCK( pxLink );
 341                 #if ( configHEAP_CLEAR_MEMORY_ON_FREE == 1 )
 342                 {
 343                     ( void ) memset( puc + xHeapStructSize, 0, pxLink->xBlockSize - xHeapStructSize );
 344                 }
 345                 #endif
 346
 347                 vTaskSuspendAll();
 348                 {
 349                     /* Add this block to the list of free blocks. */
 350                     xFreeBytesRemaining += pxLink->xBlockSize;
 351                     traceFREE( pv, pxLink->xBlockSize );
 352                     prvInsertBlockIntoFreeList( ( ( BlockLink_t * ) pxLink ) );
 353                     xNumberOfSuccessfulFrees++;
 354                 }
 355                 ( void ) xTaskResumeAll();
 356             }
 357             else
 358             {
 359                 mtCOVERAGE_TEST_MARKER();
 360             }
 361         }
 362         else
 363         {
 364             mtCOVERAGE_TEST_MARKER();
 365         }
 366     }
 367 }
 368 /*-----------------------------------------------------------*/
 369
 370 size_t xPortGetFreeHeapSize( void )
 371 {
 372     return xFreeBytesRemaining;
 373 }
 374 /*-----------------------------------------------------------*/
 375
 376 size_t xPortGetMinimumEverFreeHeapSize( void )
 377 {
 378     return xMinimumEverFreeBytesRemaining;
 379 }
 380 /*-----------------------------------------------------------*/
 381
 382 void * pvPortCalloc( size_t xNum,
 383                      size_t xSize )
 384 {
 385     void * pv = NULL;
 386
 387     if( heapMULTIPLY_WILL_OVERFLOW( xNum, xSize ) == 0 )
 388     {
 389         pv = pvPortMalloc( xNum * xSize );
 390
 391         if( pv != NULL )
 392         {
 393             ( void ) memset( pv, 0, xNum * xSize );
 394         }
 395     }
 396
 397     return pv;
 398 }
 399 /*-----------------------------------------------------------*/
 400
 401 static void prvInsertBlockIntoFreeList( BlockLink_t * pxBlockToInsert )
 402 {
 403     BlockLink_t * pxIterator;
 404     uint8_t * puc;
 405
 406     /* Iterate through the list until a block is found that has a higher address
 407      * than the block being inserted. */
 408     for( pxIterator = &xStart; pxIterator->pxNextFreeBlock < pxBlockToInsert; pxIterator = pxIterator->pxNextFreeBlock )
 409     {
 410         /* Nothing to do here, just iterate to the right position. */
 411     }
 412
 413     /* Do the block being inserted, and the block it is being inserted after
 414      * make a contiguous block of memory? */
 415     puc = ( uint8_t * ) pxIterator;
 416
 417     if( ( puc + pxIterator->xBlockSize ) == ( uint8_t * ) pxBlockToInsert )
 418     {
 419         pxIterator->xBlockSize += pxBlockToInsert->xBlockSize;
 420         pxBlockToInsert = pxIterator;
 421     }
 422     else
 423     {
 424         mtCOVERAGE_TEST_MARKER();
 425     }
 426
 427     /* Do the block being inserted, and the block it is being inserted before
 428      * make a contiguous block of memory? */
 429     puc = ( uint8_t * ) pxBlockToInsert;
 430
 431     if( ( puc + pxBlockToInsert->xBlockSize ) == ( uint8_t * ) pxIterator->pxNextFreeBlock )
 432     {
 433         if( pxIterator->pxNextFreeBlock != pxEnd )
 434         {
 435             /* Form one big block from the two blocks. */
 436             pxBlockToInsert->xBlockSize += pxIterator->pxNextFreeBlock->xBlockSize;
 437             pxBlockToInsert->pxNextFreeBlock = pxIterator->pxNextFreeBlock->pxNextFreeBlock;
 438         }
 439         else
 440         {
 441             pxBlockToInsert->pxNextFreeBlock = pxEnd;
 442         }
 443     }
 444     else
 445     {
 446         pxBlockToInsert->pxNextFreeBlock = pxIterator->pxNextFreeBlock;
 447     }
 448
 449     /* If the block being inserted plugged a gab, so was merged with the block
 450      * before and the block after, then it's pxNextFreeBlock pointer will have
 451      * already been set, and should not be set here as that would make it point
 452      * to itself. */
 453     if( pxIterator != pxBlockToInsert )
 454     {
 455         pxIterator->pxNextFreeBlock = pxBlockToInsert;
 456     }
 457     else
 458     {
 459         mtCOVERAGE_TEST_MARKER();
 460     }
 461 }
 462 /*-----------------------------------------------------------*/
 463
 464 void vPortDefineHeapRegions( const HeapRegion_t * const pxHeapRegions )
 465 {
 466     BlockLink_t * pxFirstFreeBlockInRegion = NULL;
 467     BlockLink_t * pxPreviousFreeBlock;
 468     portPOINTER_SIZE_TYPE xAlignedHeap;
 469     size_t xTotalRegionSize, xTotalHeapSize = 0;
 470     BaseType_t xDefinedRegions = 0;
 471     portPOINTER_SIZE_TYPE xAddress;
 472     const HeapRegion_t * pxHeapRegion;
 473
 474     /* Can only call once! */
 475     configASSERT( pxEnd == NULL );
 476
 477     pxHeapRegion = &( pxHeapRegions[ xDefinedRegions ] );
 478
 479     while( pxHeapRegion->xSizeInBytes > 0 )
 480     {
 481         xTotalRegionSize = pxHeapRegion->xSizeInBytes;
 482
 483         /* Ensure the heap region starts on a correctly aligned boundary. */
 484         xAddress = ( portPOINTER_SIZE_TYPE ) pxHeapRegion->pucStartAddress;
 485
 486         if( ( xAddress & portBYTE_ALIGNMENT_MASK ) != 0 )
 487         {
 488             xAddress += ( portBYTE_ALIGNMENT - 1 );
 489             xAddress &= ~portBYTE_ALIGNMENT_MASK;
 490
 491             /* Adjust the size for the bytes lost to alignment. */
 492             xTotalRegionSize -= ( size_t ) ( xAddress - ( portPOINTER_SIZE_TYPE ) pxHeapRegion->pucStartAddress );
 493         }
 494
 495         xAlignedHeap = xAddress;
 496
 497         /* Set xStart if it has not already been set. */
 498         if( xDefinedRegions == 0 )
 499         {
 500             /* xStart is used to hold a pointer to the first item in the list of
 501              *  free blocks.  The void cast is used to prevent compiler warnings. */
 502             xStart.pxNextFreeBlock = ( BlockLink_t * ) xAlignedHeap;
 503             xStart.xBlockSize = ( size_t ) 0;
 504         }
 505         else
 506         {
 507             /* Should only get here if one region has already been added to the
 508              * heap. */
 509             configASSERT( pxEnd != NULL );
 510
 511             /* Check blocks are passed in with increasing start addresses. */
 512             configASSERT( ( size_t ) xAddress > ( size_t ) pxEnd );
 513         }
 514
 515         /* Remember the location of the end marker in the previous region, if
 516          * any. */
 517         pxPreviousFreeBlock = pxEnd;
 518
 519         /* pxEnd is used to mark the end of the list of free blocks and is
 520          * inserted at the end of the region space. */
 521         xAddress = xAlignedHeap + ( portPOINTER_SIZE_TYPE ) xTotalRegionSize;
 522         xAddress -= ( portPOINTER_SIZE_TYPE ) xHeapStructSize;
 523         xAddress &= ~( ( portPOINTER_SIZE_TYPE ) portBYTE_ALIGNMENT_MASK );
 524         pxEnd = ( BlockLink_t * ) xAddress;
 525         pxEnd->xBlockSize = 0;
 526         pxEnd->pxNextFreeBlock = NULL;
 527
 528         /* To start with there is a single free block in this region that is
 529          * sized to take up the entire heap region minus the space taken by the
 530          * free block structure. */
 531         pxFirstFreeBlockInRegion = ( BlockLink_t * ) xAlignedHeap;
 532         pxFirstFreeBlockInRegion->xBlockSize = ( size_t ) ( xAddress - ( portPOINTER_SIZE_TYPE ) pxFirstFreeBlockInRegion );
 533         pxFirstFreeBlockInRegion->pxNextFreeBlock = pxEnd;
 534
 535         /* If this is not the first region that makes up the entire heap space
 536          * then link the previous region to this region. */
 537         if( pxPreviousFreeBlock != NULL )
 538         {
 539             pxPreviousFreeBlock->pxNextFreeBlock = pxFirstFreeBlockInRegion;
 540         }
 541
 542         xTotalHeapSize += pxFirstFreeBlockInRegion->xBlockSize;
 543
 544         /* Move onto the next HeapRegion_t structure. */
 545         xDefinedRegions++;
 546         pxHeapRegion = &( pxHeapRegions[ xDefinedRegions ] );
 547     }
 548
 549     xMinimumEverFreeBytesRemaining = xTotalHeapSize;
 550     xFreeBytesRemaining = xTotalHeapSize;
 551
 552     /* Check something was actually defined before it is accessed. */
 553     configASSERT( xTotalHeapSize );
 554 }
 555 /*-----------------------------------------------------------*/
 556
 557 void vPortGetHeapStats( HeapStats_t * pxHeapStats )
 558 {
 559     BlockLink_t * pxBlock;
 560     size_t xBlocks = 0, xMaxSize = 0, xMinSize = portMAX_DELAY; /* portMAX_DELAY used as a portable way of getting the maximum value. */
 561
 562     vTaskSuspendAll();
 563     {
 564         pxBlock = xStart.pxNextFreeBlock;
 565
 566         /* pxBlock will be NULL if the heap has not been initialised.  The heap
 567          * is initialised automatically when the first allocation is made. */
 568         if( pxBlock != NULL )
 569         {
 570             while( pxBlock != pxEnd )
 571             {
 572                 /* Increment the number of blocks and record the largest block seen
 573                  * so far. */
 574                 xBlocks++;
 575
 576                 if( pxBlock->xBlockSize > xMaxSize )
 577                 {
 578                     xMaxSize = pxBlock->xBlockSize;
 579                 }
 580
 581                 /* Heap five will have a zero sized block at the end of each
 582                  * each region - the block is only used to link to the next
 583                  * heap region so it not a real block. */
 584                 if( pxBlock->xBlockSize != 0 )
 585                 {
 586                     if( pxBlock->xBlockSize < xMinSize )
 587                     {
 588                         xMinSize = pxBlock->xBlockSize;
 589                     }
 590                 }
 591
 592                 /* Move to the next block in the chain until the last block is
 593                  * reached. */
 594                 pxBlock = pxBlock->pxNextFreeBlock;
 595             }
 596         }
 597     }
 598     ( void ) xTaskResumeAll();
 599
 600     pxHeapStats->xSizeOfLargestFreeBlockInBytes = xMaxSize;
 601     pxHeapStats->xSizeOfSmallestFreeBlockInBytes = xMinSize;
 602     pxHeapStats->xNumberOfFreeBlocks = xBlocks;
 603
 604     taskENTER_CRITICAL();
 605     {
 606         pxHeapStats->xAvailableHeapSpaceInBytes = xFreeBytesRemaining;
 607         pxHeapStats->xNumberOfSuccessfulAllocations = xNumberOfSuccessfulAllocations;
 608         pxHeapStats->xNumberOfSuccessfulFrees = xNumberOfSuccessfulFrees;
 609         pxHeapStats->xMinimumEverFreeBytesRemaining = xMinimumEverFreeBytesRemaining;
 610     }
 611     taskEXIT_CRITICAL();
 612 }
 613 /*-----------------------------------------------------------*/