Heap Memory Pool

The heap memory pool is a predefined memory pool object that allows threads to dynamically allocate memory from a common memory region in a malloc()-like manner.

Concepts

Only a single heap memory pool can be defined. Unlike other memory pools, the heap memory pool cannot be directly referenced using its memory address.

The size of the heap memory pool is configurable. The following sizes are supported: 256 bytes, 1024 bytes, 4096 bytes, and 16384 bytes.

A thread can dynamically allocate a chunk of heap memory by calling k_malloc(). The address of the allocated chunk is guaranteed to be aligned on a multiple of 4 bytes. If a suitable chunk of heap memory cannot be found NULL is returned.

When the thread is finished with a chunk of heap memory it can release the chunk back to the heap memory pool by calling k_free().

Internal Operation

The heap memory pool defines a single maximum size block that contains the entire heap; that is, a single block of 256, 1024, 4096, or 16384 bytes. The heap memory pool also defines a minimum block size of 64 bytes. Consequently, the maximum number of blocks of each size that the heap memory pool can support is shown in the following table.

heap size 64 byte blocks 256 byte blocks 1024 byte blocks 4096 byte blocks 16384 byte blocks
256 4 1 0 0 0
1024 16 4 1 0 0
4096 64 16 4 1 0
16384 256 64 16 4 1

Note

The number of blocks of a given size that can be allocated simultaneously is typically smaller than the value shown in the table. For example, each allocation of a 256 byte block from a 1024 byte heap reduces the number of 64 byte blocks available for allocation by 4. Fragmentation of the memory pool’s buffer can also further reduce the availability of blocks.

The kernel uses the first 16 bytes of any memory block allocated from the heap memory pool to save the block descriptor information it needs to later free the block. Consequently, an application’s request for an N byte chunk of heap memory requires a block that is at least (N+16) bytes long.

Implementation

Defining the Heap Memory Pool

The size of the heap memory pool is specified using the CONFIG_HEAP_MEM_POOL_SIZE configuration option.

By default, the heap memory pool size is zero bytes. This value instructs the kernel not to define the heap memory pool object.

Allocating Memory

A chunk of heap memory is allocated by calling k_malloc().

The following code allocates a 200 byte chunk of heap memory, then fills it with zeros. A warning is issued if a suitable chunk is not obtained.

Note that the application will actually allocate a 256 byte memory block, since that is the closest matching size supported by the heap memory pool.

char *mem_ptr;

mem_ptr = k_malloc(200);
if (mem_ptr != NULL)) {
    memset(mem_ptr, 0, 200);
    ...
} else {
    printf("Memory not allocated");
}

Releasing Memory

A chunk of heap memory is released by calling k_free().

The following code allocates a 75 byte chunk of memory, then releases it once it is no longer needed. (A 256 byte memory block from the heap memory pool is actually used to satisfy the request.)

char *mem_ptr;

mem_ptr = k_malloc(75);
... /* use memory block */
k_free(mem_ptr);

Suggested Uses

Use the heap memory pool to dynamically allocate memory in a malloc()-like manner.

Configuration Options

Related configuration options:

API Reference

group heap_apis

Functions

void *k_malloc(size_t size)

Allocate memory from heap.

This routine provides traditional malloc() semantics. Memory is allocated from the heap memory pool.

Return
Address of the allocated memory if successful; otherwise NULL.
Parameters
  • size: Amount of memory requested (in bytes).

void k_free(void *ptr)

Free memory allocated from heap.

This routine provides traditional free() semantics. The memory being returned must have been allocated from the heap memory pool or k_mem_pool_malloc().

If ptr is NULL, no operation is performed.

Return
N/A
Parameters
  • ptr: Pointer to previously allocated memory.

void *k_calloc(size_t nmemb, size_t size)

Allocate memory from heap, array style.

This routine provides traditional calloc() semantics. Memory is allocated from the heap memory pool and zeroed.

Return
Address of the allocated memory if successful; otherwise NULL.
Parameters
  • nmemb: Number of elements in the requested array
  • size: Size of each array element (in bytes).