Memory Heaps

The memory heap component is part of the real-time kernel and provides dynamic allocation of variable-sized memory from a larger contiguous block of memory. A heap has the benefit of being able to allocate any size of memory, but the trade-off is that it can suffer from fragmentation and the time it takes to allocate the memory is not deterministic. Therefore, allocations from a heap cannot be performed from an ISR, a memory pool must be used for those scenarios.

The memory heap maintains a list of free blocks and upon a request for allocation, the heap will take the first free block that can accommodate the request. If the free block is larger than the amount of memory requested, the heap will split the free block and return only the portion that was requested.

When memory is returned, the heap will merge (defrag) the returned memory with any adjacent memory free memory blocks.

Basic Usage

When creating a heap, a contiguous region of memory must be provided that will be managed by the heap. An example snippet below provides a 2KB block of memory to be managed by a memory heap.

#include "Kernel/kernel_heap.h"
#include <assert.h>

static HEAP heap;                                   /* Allocate a memory heap */

void APP_Example(void)
{
    static BYTE heap_mem[2048];                     /* Allocate the source memory managed by the heap */
    STATUS status;


    status = HEAP_Create(&heap,                     /* Create a memory heap */
                         "Heap1",                   /* A name for the heap (for debugging purposes) */
                         heap_mem,                  /* A pointer to the memory used by the heap */
                         sizeof(heap_mem));         /* The size in bytes of the heap */

    assert(status == SUCCESS);
}

Any size of memory can be allocated from a heap. An example snippet below allocates a block of memory and accesses the block and then later releases the memory back to the heap.

#include "Kernel/kernel_heap.h"

/* An application-defined object */
typedef struct MYOBJECT {
    UINT32 value1;
    UINT32 value2;
} MYOBJECT;

void APP_Example(void)
{
    MYOBJECT* obj;


    obj = HEAP_Alloc(&heap, sizeof(MYOBJECT));  /* Allocate memory for an object */
    if (obj) {                                  /* Successfully allocated? */
	
        obj->value1 = 0;                        /* Use the memory... */
        obj->value2 = 1;


        HEAP_Free(&heap, obj);                  /* Return the memory to the heap */
    }
}