Heap

Features Supported

  • Ability to create multiple user defined heaps

  • Alloc and free APIs

  • Detailed heap statistics

  • Thread safe APIs with RTOS

  • Minimum alignment of HeapP_BYTE_ALIGNMENT for all allocations

Features NOT Supported

  • Memory allocation with alignment as a input. Users should allocate extra and align after allocation.

Important Usage Guidelines

NA

Example Usage

Include the below file to access the APIs,

Example usage to define a heap memory and heap handle:

Example usage to create a heap:

Example usage to allocate and free memory:

API Reference

Defines

HeapP_BYTE_ALIGNMENT

Minimum alignment for heap allocations, in units of bytes.

HeapP_OBJECT_SIZE_MAX

Max size of heap object across no-RTOS and all OS’s.

Functions

void HeapP_construct(HeapP_Object *heap, void *heapAddr, size_t heapSize)

Create a user defined heap.

The actual heap start address and size will be adjusted to satisfy HeapP_BYTE_ALIGNMENT.

Parameters:

  • heap – [out] Intialized heap handle to be used for subsequent API calls

  • heapAddr – [in] Base address of memory to be used as heap

  • heapSize – [in] Size of memory block that is to be used as heap

void HeapP_destruct(HeapP_Object *heap)

Delete the user defined heap.

Parameters:

heap – [in] Heap handle

void *HeapP_alloc(HeapP_Object *heap, size_t allocSize)

Alloc memory from user defined heap.

Parameters:

  • heap – [in] Heap handle

  • allocSize – [in] Size of memory to allocate

Returns:

pointer to allcoated memory

Returns:

NULL memory could not be allocated since a free block of required size could not be found

void HeapP_free(HeapP_Object *heap, void *ptr)

Free memory from user defined heap.

Parameters:

  • heap – [in] Heap handle

  • ptr – [in] Pointer to memory allocated using HeapP_alloc

size_t HeapP_getFreeHeapSize(HeapP_Object *heap)

Get free heap size, in bytes.

Parameters:

heap – [in] Heap handle

Returns:

Free memory size in this heap, in bytes

size_t HeapP_getMinimumEverFreeHeapSize(HeapP_Object *heap)

Get lowest ever free heap size, in bytes.

Parameters:

heap – [in] Heap handle

Returns:

Lowest ever free heap size, in bytes

void HeapP_getHeapStats(HeapP_Object *heap, HeapP_MemStats *pHeapStats)

Get detailed heap statistics.

Parameters:

  • heap – [in] Heap handle

  • pHeapStats – [out] Returned heap statistics

struct HeapP_MemStats
#include <HeapP.h>

Structure used to pass information about the heap out of HeapP_getHeapStats().

Public Members

size_t availableHeapSpaceInBytes

The total heap size, in bytes, currently available - this is the sum of all the free blocks, not the largest block that can be allocated.

size_t sizeOfLargestFreeBlockInBytes

The maximum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called.

size_t sizeOfSmallestFreeBlockInBytes

The minimum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called.

size_t numberOfFreeBlocks

The number of free memory blocks within the heap at the time vPortGetHeapStats() is called.

size_t minimumEverFreeBytesRemaining

The minimum amount of total free memory, in bytes, (sum of all free blocks) there has been in the heap since the system booted.

size_t numberOfSuccessfulAllocations

The number of calls to HeapP_alloc() that have returned a valid memory block.

size_t numberOfSuccessfulFrees

The number of calls to HeapP_free() that has successfully freed a block of memory.

struct HeapP_Object
#include <HeapP.h>

Opaque heap object used with the heap APIs.

Public Members

uint32_t rsv[HeapP_OBJECT_SIZE_MAX / sizeof(uint32_t)]

reserved, should NOT be modified by end users