Memory Heaps

Zephyr provides a collection of utilities that allow threads to dynamically allocate memory.

Synchronized Heap Allocator

Creating a Heap

The simplest way to define a heap is statically, with the K_HEAP_DEFINE macro. This creates a static k_heap variable with a given name that manages a memory region of the specified size.

Heaps can also be created to manage arbitrary regions of application-controlled memory using k_heap_init().

Allocating Memory

Memory can be allocated from a heap using k_heap_alloc(), passing it the address of the heap object and the number of bytes desired. This functions similarly to standard C malloc(), returning a NULL pointer on an allocation failure.

The heap supports blocking operation, allowing threads to go to sleep until memory is available. The final argument is a k_timeout_t timeout value indicating how long the thread may sleep before returning, or else one of the constant timeout values K_NO_WAIT or K_FOREVER.

Releasing Memory

Memory allocated with k_heap_alloc() must be released using k_heap_free(). Similar to standard C free(), the pointer provided must be either a NULL value or a pointer previously returned by k_heap_alloc() for the same heap. Freeing a NULL value is defined to have no effect.

Low Level Heap Allocator

The underlying implementation of the k_heap abstraction is provided a data structure named sys_heap. This implements exactly the same allocation semantics, but provides no kernel synchronization tools. It is available for applications that want to manage their own blocks of memory in contexts (for example, userspace) where synchronization is unavailable or more complicated. Unlike k_heap, all calls to any sys_heap functions on a single heap must be serialized by the caller. Simultaneous use from separate threads is disallowed.

Implementation

Internally, the sys_heap memory block is partitioned into “chunks” of 8 bytes. All allocations are made out of a contiguous region of chunks. The first chunk of every allocation or unused block is prefixed by a chunk header that stores the length of the chunk, the length of the next lower (“left”) chunk in physical memory, a bit indicating whether the chunk is in use, and chunk-indexed link pointers to the previous and next chunk in a “free list” to which unused chunks are added.

The heap code takes reasonable care to avoid fragmentation. Free block lists are stored in “buckets” by their size, each bucket storing blocks within one power of two (i.e. a bucket for blocks of 3-4 chunks, another for 5-8, 9-16, etc…) this allows new allocations to be made from the smallest/most-fragmented blocks available. Also, as allocations are freed and added to the heap, they are automatically combined with adjacent free blocks to prevent fragmentation.

All metadata is stored at the beginning of the contiguous block of heap memory, including the variable-length list of bucket list heads (which depend on heap size). The only external memory required is the sys_heap structure itself.

The sys_heap functions are unsynchronized. Care must be taken by any users to prevent concurrent access. Only one context may be inside one of the API functions at a time.

The heap code takes care to present high performance and reliable latency. All sys_heap API functions are guaranteed to complete within constant time. On typical architectures, they will all complete within 1-200 cycles. One complexity is that the search of the minimum bucket size for an allocation (the set of free blocks that “might fit”) has a compile-time upper bound of iterations to prevent unbounded list searches, at the expense of some fragmentation resistance. This CONFIG_SYS_HEAP_ALLOC_LOOPS value may be chosen by the user at build time, and defaults to a value of 3.

Multi-Heap Wrapper Utility

The sys_heap utility requires that all managed memory be in a single contiguous block. It is common for complicated microcontroller applications to have more complicated memory setups that they still want to manage dynamically as a “heap”. For example, the memory might exist as separate discontiguous regions, different areas may have different cache, performance or power behavior, peripheral devices may only be able to perform DMA to certain regions, etc…

For those situations, Zephyr provides a sys_multi_heap utility. Effectively this is a simple wrapper around a set of one or more sys_heap objects. It should be initialized after its child heaps via sys_multi_heap_init(), after which each heap can be added to the managed set via sys_multi_heap_add_heap(). No destruction utility is provided; just as for sys_heap, applications that want to destroy a multi heap should simply ensure all allocated blocks are freed (or at least will never be used again) and repurpose the underlying memory for another usage.

It has a single pair of allocation entry points, sys_multi_heap_alloc() and sys_multi_heap_aligned_alloc(). These behave identically to the sys_heap functions with similar names, except that they also accept an opaque “configuration” parameter. This pointer is uninspected by the multi heap code itself; instead it is passed to a callback function provided at initialization time. This application-provided callback is responsible for doing the underlying allocation from one of the managed heaps, and may use the configuration parameter in any way it likes to make that decision.

When unused, a multi heap may be freed via sys_multi_heap_free(). The application does not need to pass a configuration parameter. Memory allocated from any of the managed sys_heap objects may be freed with in the same way.

System Heap

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

Only a single system heap is defined. Unlike other heaps or memory pools, the system heap cannot be directly referenced using its memory address.

The size of the system heap is configurable to arbitrary sizes, subject to space availability.

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 pointer sizes. 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 system heap by calling k_free().

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. The maximum size is limited by the amount of available memory in the system. The project build will fail in the link stage if the size specified can not be supported.

In addition, each subsystem (board, driver, library, etc) can set a custom requirement by defining a Kconfig option with the prefix HEAP_MEM_POOL_ADD_SIZE_ (this value is in bytes). If multiple subsystems specify custom values, the sum of these will be used as the minimum requirement. If the application tries to set a value that’s less than the minimum value, this will be ignored and the minimum value will be used instead.

To force a smaller than minimum value to be used, the application may enable the CONFIG_HEAP_MEM_POOL_IGNORE_MIN option. This can be useful when optimizing the heap size and the minimum requirement can be more accurately determined for a specific application.

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.

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.

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

Defines

K_HEAP_DEFINE(name, bytes)

Define a static k_heap.

This macro defines and initializes a static memory region and k_heap of the requested size. After kernel start, &name can be used as if k_heap_init() had been called.

Note that this macro enforces a minimum size on the memory region to accommodate metadata requirements. Very small heaps will be padded to fit.

Parameters:

  • name – Symbol name for the struct k_heap object

  • bytes – Size of memory region, in bytes

K_HEAP_DEFINE_NOCACHE(name, bytes)

Define a static k_heap in uncached memory.

This macro defines and initializes a static memory region and k_heap of the requested size in uncached memory. After kernel start, &name can be used as if k_heap_init() had been called.

Note that this macro enforces a minimum size on the memory region to accommodate metadata requirements. Very small heaps will be padded to fit.

Parameters:

  • name – Symbol name for the struct k_heap object

  • bytes – Size of memory region, in bytes

Functions

void k_heap_init(struct k_heap *h, void *mem, size_t bytes)

Initialize a k_heap.

This constructs a synchronized k_heap object over a memory region specified by the user. Note that while any alignment and size can be passed as valid parameters, internal alignment restrictions inside the inner sys_heap mean that not all bytes may be usable as allocated memory.

Parameters:

  • h – Heap struct to initialize

  • mem – Pointer to memory.

  • bytes – Size of memory region, in bytes

void *k_heap_aligned_alloc(struct k_heap *h, size_t align, size_t bytes, k_timeout_t timeout)

Allocate aligned memory from a k_heap.

Behaves in all ways like k_heap_alloc(), except that the returned memory (if available) will have a starting address in memory which is a multiple of the specified power-of-two alignment value in bytes. The resulting memory can be returned to the heap using k_heap_free().

Function properties (list may not be complete)

isr-ok

Note

timeout must be set to K_NO_WAIT if called from ISR.

Note

When CONFIG_MULTITHREADING=n any timeout is treated as K_NO_WAIT.

Parameters:

  • h – Heap from which to allocate

  • align – Alignment in bytes, must be a power of two

  • bytes – Number of bytes requested

  • timeout – How long to wait, or K_NO_WAIT

Returns:

Pointer to memory the caller can now use

void *k_heap_alloc(struct k_heap *h, size_t bytes, k_timeout_t timeout)

Allocate memory from a k_heap.

Allocates and returns a memory buffer from the memory region owned by the heap. If no memory is available immediately, the call will block for the specified timeout (constructed via the standard timeout API, or K_NO_WAIT or K_FOREVER) waiting for memory to be freed. If the allocation cannot be performed by the expiration of the timeout, NULL will be returned. Allocated memory is aligned on a multiple of pointer sizes.

Function properties (list may not be complete)

isr-ok

Note

timeout must be set to K_NO_WAIT if called from ISR.

Note

When CONFIG_MULTITHREADING=n any timeout is treated as K_NO_WAIT.

Parameters:

  • h – Heap from which to allocate

  • bytes – Desired size of block to allocate

  • timeout – How long to wait, or K_NO_WAIT

Returns:

A pointer to valid heap memory, or NULL

void *k_heap_realloc(struct k_heap *h, void *ptr, size_t bytes, k_timeout_t timeout)

Reallocate memory from a k_heap.

Reallocates and returns a memory buffer from the memory region owned by the heap. If no memory is available immediately, the call will block for the specified timeout (constructed via the standard timeout API, or K_NO_WAIT or K_FOREVER) waiting for memory to be freed. If the allocation cannot be performed by the expiration of the timeout, NULL will be returned. Reallocated memory is aligned on a multiple of pointer sizes.

Function properties (list may not be complete)

isr-ok

Note

timeout must be set to K_NO_WAIT if called from ISR.

Note

When CONFIG_MULTITHREADING=n any timeout is treated as K_NO_WAIT.

Parameters:

  • h – Heap from which to allocate

  • ptr – Original pointer returned from a previous allocation

  • bytes – Desired size of block to allocate

  • timeout – How long to wait, or K_NO_WAIT

Returns:

Pointer to memory the caller can now use, or NULL

void k_heap_free(struct k_heap *h, void *mem)

Free memory allocated by k_heap_alloc()

Returns the specified memory block, which must have been returned from k_heap_alloc(), to the heap for use by other callers. Passing a NULL block is legal, and has no effect.

Parameters:

  • h – Heap to which to return the memory

  • mem – A valid memory block, or NULL

void *k_aligned_alloc(size_t align, size_t size)

Allocate memory from the heap with a specified alignment.

This routine provides semantics similar to aligned_alloc(); memory is allocated from the heap with a specified alignment. However, one minor difference is that k_aligned_alloc() accepts any non-zero size, whereas aligned_alloc() only accepts a size that is an integral multiple of align.

Above, aligned_alloc() refers to: C11 standard (ISO/IEC 9899:2011): 7.22.3.1 The aligned_alloc function (p: 347-348)

Parameters:

  • align – Alignment of memory requested (in bytes).

  • size – Amount of memory requested (in bytes).

Returns:

Address of the allocated memory if successful; otherwise NULL.

void *k_malloc(size_t size)

Allocate memory from the heap.

This routine provides traditional malloc() semantics. Memory is allocated from the heap memory pool. Allocated memory is aligned on a multiple of pointer sizes.

Parameters:

  • size – Amount of memory requested (in bytes).

Returns:

Address of the allocated memory if successful; otherwise NULL.

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.

If ptr is NULL, no operation is performed.

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.

Parameters:

  • nmemb – Number of elements in the requested array

  • size – Size of each array element (in bytes).

Returns:

Address of the allocated memory if successful; otherwise NULL.

void *k_realloc(void *ptr, size_t size)

Expand the size of an existing allocation.

Returns a pointer to a new memory region with the same contents, but a different allocated size. If the new allocation can be expanded in place, the pointer returned will be identical. Otherwise the data will be copies to a new block and the old one will be freed as per sys_heap_free(). If the specified size is smaller than the original, the block will be truncated in place and the remaining memory returned to the heap. If the allocation of a new block fails, then NULL will be returned and the old block will not be freed or modified.

Parameters:

  • ptr – Original pointer returned from a previous allocation

  • size – Amount of memory requested (in bytes).

Returns:

Pointer to memory the caller can now use, or NULL.

struct k_heap
#include <kernel.h>
group low_level_heap_allocator

Defines

sys_heap_realloc(heap, ptr, bytes)

Functions

void sys_heap_init(struct sys_heap *heap, void *mem, size_t bytes)

Initialize sys_heap.

Initializes a sys_heap struct to manage the specified memory.

Parameters:

  • heap – Heap to initialize

  • mem – Untyped pointer to unused memory

  • bytes – Size of region pointed to by mem

void *sys_heap_alloc(struct sys_heap *heap, size_t bytes)

Allocate memory from a sys_heap.

Returns a pointer to a block of unused memory in the heap. This memory will not otherwise be used until it is freed with sys_heap_free(). If no memory can be allocated, NULL will be returned. The allocated memory is guaranteed to have a starting address which is a multiple of sizeof(void *). If a bigger alignment is necessary then sys_heap_aligned_alloc() should be used instead.

Note

The sys_heap implementation is not internally synchronized. No two sys_heap functions should operate on the same heap at the same time. All locking must be provided by the user.

Parameters:

  • heap – Heap from which to allocate

  • bytes – Number of bytes requested

Returns:

Pointer to memory the caller can now use

void *sys_heap_aligned_alloc(struct sys_heap *heap, size_t align, size_t bytes)

Allocate aligned memory from a sys_heap.

Behaves in all ways like sys_heap_alloc(), except that the returned memory (if available) will have a starting address in memory which is a multiple of the specified power-of-two alignment value in bytes. With align=0 this behaves exactly like sys_heap_alloc(). The resulting memory can be returned to the heap using sys_heap_free().

Parameters:

  • heap – Heap from which to allocate

  • align – Alignment in bytes, must be a power of two

  • bytes – Number of bytes requested

Returns:

Pointer to memory the caller can now use

void sys_heap_free(struct sys_heap *heap, void *mem)

Free memory into a sys_heap.

De-allocates a pointer to memory previously returned from sys_heap_alloc such that it can be used for other purposes. The caller must not use the memory region after entry to this function.

Note

The sys_heap implementation is not internally synchronized. No two sys_heap functions should operate on the same heap at the same time. All locking must be provided by the user.

Parameters:

  • heap – Heap to which to return the memory

  • mem – A pointer previously returned from sys_heap_alloc()

void *sys_heap_aligned_realloc(struct sys_heap *heap, void *ptr, size_t align, size_t bytes)

Expand the size of an existing allocation.

Returns a pointer to a new memory region with the same contents, but a different allocated size. If the new allocation can be expanded in place, the pointer returned will be identical. Otherwise the data will be copies to a new block and the old one will be freed as per sys_heap_free(). If the specified size is smaller than the original, the block will be truncated in place and the remaining memory returned to the heap. If the allocation of a new block fails, then NULL will be returned and the old block will not be freed or modified.

Parameters:

  • heap – Heap from which to allocate

  • ptr – Original pointer returned from a previous allocation

  • align – Alignment in bytes, must be a power of two

  • bytes – Number of bytes requested for the new block

Returns:

Pointer to memory the caller can now use, or NULL

size_t sys_heap_usable_size(struct sys_heap *heap, void *mem)

Return allocated memory size.

Returns the size, in bytes, of a block returned from a successful sys_heap_alloc() or sys_heap_alloc_aligned() call. The value returned is the size of the heap-managed memory, which may be larger than the number of bytes requested due to allocation granularity. The heap code is guaranteed to make no access to this region of memory until a subsequent sys_heap_free() on the same pointer.

Parameters:

  • heap – Heap containing the block

  • mem – Pointer to memory allocated from this heap

Returns:

Size in bytes of the memory region

bool sys_heap_validate(struct sys_heap *heap)

Validate heap integrity.

Validates the internal integrity of a sys_heap. Intended for unit test and validation code, though potentially useful as a user API for applications with complicated runtime reliability requirements. Note: this cannot catch every possible error, but if it returns true then the heap is in a consistent state and can correctly handle any sys_heap_alloc() request and free any live pointer returned from a previous allocation.

Parameters:

  • heap – Heap to validate

Returns:

true, if the heap is valid, otherwise false

void sys_heap_stress(void *(*alloc_fn)(void *arg, size_t bytes), void (*free_fn)(void *arg, void *p), void *arg, size_t total_bytes, uint32_t op_count, void *scratch_mem, size_t scratch_bytes, int target_percent, struct z_heap_stress_result *result)

sys_heap stress test rig

Test rig for heap allocation validation. This will loop for op_count cycles, in each iteration making a random choice to allocate or free a pointer of randomized (power law) size based on heuristics designed to keep the heap in a state where it is near target_percent full. Allocation and free operations are provided by the caller as callbacks (i.e. this can in theory test any heap). Results, including counts of frees and successful/unsuccessful allocations, are returned via the result struct.

Parameters:

  • alloc_fn – Callback to perform an allocation. Passes back the arg parameter as a context handle.

  • free_fn – Callback to perform a free of a pointer returned from alloc. Passes back the arg parameter as a context handle.

  • arg – Context handle to pass back to the callbacks

  • total_bytes – Size of the byte array the heap was initialized in

  • op_count – How many iterations to test

  • scratch_mem – A pointer to scratch memory to be used by the test. Should be about 1/2 the size of the heap for tests that need to stress fragmentation.

  • scratch_bytes – Size of the memory pointed to by scratch_mem

  • target_percent – Percentage fill value (1-100) to which the random allocation choices will seek. High values will result in significant allocation failures and a very fragmented heap.

  • result – Struct into which to store test results.

void sys_heap_print_info(struct sys_heap *heap, bool dump_chunks)

Print heap internal structure information to the console.

Print information on the heap structure such as its size, chunk buckets, chunk list and some statistics for debugging purpose.

Parameters:

  • heap – Heap to print information about

  • dump_chunks – True to print the entire heap chunk list

group multi_heap_wrapper

Typedefs

typedef void *(*sys_multi_heap_fn_t)(struct sys_multi_heap *mheap, void *cfg, size_t align, size_t size)

Multi-heap choice function.

This is a user-provided functions whose responsibility is selecting a specific sys_heap backend based on the opaque cfg value, which is specified by the user as an argument to sys_multi_heap_alloc(), and performing the allocation on behalf of the caller. The callback is free to choose any registered heap backend to perform the allocation, and may choose to pad the user-provided values as needed, and to use an aligned allocation where required by the specified configuration.

NULL may be returned, which will cause the allocation to fail and a NULL reported to the calling code.

Param mheap:

Multi-heap structure.

Param cfg:

An opaque user-provided value. It may be interpreted in any way by the application

Param align:

Alignment of requested memory (or zero for no alignment)

Param size:

The user-specified allocation size in bytes

Return:

A pointer to the allocated memory

Functions

void sys_multi_heap_init(struct sys_multi_heap *heap, sys_multi_heap_fn_t choice_fn)

Initialize multi-heap.

Initialize a sys_multi_heap struct with the specified choice function. Note that individual heaps must be added later with sys_multi_heap_add_heap so that the heap bounds can be tracked by the multi heap code.

Note

In general a multiheap is likely to be instantiated semi-statically from system configuration (for example, via linker-provided bounds on available memory in different regions, or from devicetree definitions of hardware-provided addressable memory, etc…). The general expectation is that a soc- or board-level platform device will be initialized at system boot from these upstream configuration sources and not that an application will assemble a multi-heap on its own.

Parameters:

  • heap – A sys_multi_heap to initialize

  • choice_fn – A sys_multi_heap_fn_t callback used to select heaps at allocation time

void sys_multi_heap_add_heap(struct sys_multi_heap *mheap, struct sys_heap *heap, void *user_data)

Add sys_heap to multi heap.

This adds a known sys_heap backend to an existing multi heap, allowing the multi heap internals to track the bounds of the heap and determine which heap (if any) from which a freed block was allocated.

Parameters:

  • mheap – A sys_multi_heap to which to add a heap

  • heap – The heap to add

  • user_data – pointer to any data for the heap

void *sys_multi_heap_alloc(struct sys_multi_heap *mheap, void *cfg, size_t bytes)

Allocate memory from multi heap.

Just as for sys_heap_alloc(), allocates a block of memory of the specified size in bytes. Takes an opaque configuration pointer passed to the multi heap choice function, which is used by integration code to choose a heap backend.

Parameters:

  • mheap – Multi heap pointer

  • cfg – Opaque configuration parameter, as for sys_multi_heap_fn_t

  • bytes – Requested size of the allocation, in bytes

Returns:

A valid pointer to heap memory, or NULL if no memory is available

void *sys_multi_heap_aligned_alloc(struct sys_multi_heap *mheap, void *cfg, size_t align, size_t bytes)

Allocate aligned memory from multi heap.

Just as for sys_multi_heap_alloc(), allocates a block of memory of the specified size in bytes. Takes an additional parameter specifying a power of two alignment, in bytes.

Parameters:

  • mheap – Multi heap pointer

  • cfg – Opaque configuration parameter, as for sys_multi_heap_fn_t

  • align – Power of two alignment for the returned pointer, in bytes

  • bytes – Requested size of the allocation, in bytes

Returns:

A valid pointer to heap memory, or NULL if no memory is available

const struct sys_multi_heap_rec *sys_multi_heap_get_heap(const struct sys_multi_heap *mheap, void *addr)

Get a specific heap for provided address.

Finds a single system heap (with user_data) controlling the provided pointer

Parameters:

  • mheap – Multi heap pointer

  • addr – address to be found, must be a pointer to a block allocated by sys_multi_heap_alloc

Returns:

0 multi_heap_rec pointer to a structure to be filled with return data or NULL if the heap has not been found

void sys_multi_heap_free(struct sys_multi_heap *mheap, void *block)

Free memory allocated from multi heap.

Returns the specified block, which must be the return value of a previously successful sys_multi_heap_alloc() or sys_multi_heap_aligned_alloc() call, to the heap backend from which it was allocated.

Accepts NULL as a block parameter, which is specified to have no effect.

Parameters:

  • mheap – Multi heap pointer

  • block – Block to free, must be a pointer to a block allocated by sys_multi_heap_alloc

struct sys_multi_heap_rec
#include <multi_heap.h>
struct sys_multi_heap
#include <multi_heap.h>

Heap listener

group heap_listener_apis

Defines

HEAP_ID_FROM_POINTER(heap_pointer)

Construct heap identifier from heap pointer.

Construct a heap identifier from a pointer to the heap object, such as sys_heap.

Parameters:

  • heap_pointer – Pointer to the heap object

HEAP_ID_LIBC

Libc heap identifier.

Identifier of the global libc heap.

HEAP_LISTENER_ALLOC_DEFINE(name, _heap_id, _alloc_cb)

Define heap event listener node for allocation event.

Sample usage: 

void on_heap_alloc(uintptr_t heap_id, void *mem, size_t bytes)
{
  LOG_INF("Memory allocated at %p, size %ld", mem, bytes);
}

HEAP_LISTENER_ALLOC_DEFINE(my_listener, HEAP_ID_LIBC, on_heap_alloc);

Parameters:

  • name – Name of the heap event listener object

  • _heap_id – Identifier of the heap to be listened

  • _alloc_cb – Function to be called for allocation event

HEAP_LISTENER_FREE_DEFINE(name, _heap_id, _free_cb)

Define heap event listener node for free event.

Sample usage: 

void on_heap_free(uintptr_t heap_id, void *mem, size_t bytes)
{
  LOG_INF("Memory freed at %p, size %ld", mem, bytes);
}

HEAP_LISTENER_FREE_DEFINE(my_listener, HEAP_ID_LIBC, on_heap_free);

Parameters:

  • name – Name of the heap event listener object

  • _heap_id – Identifier of the heap to be listened

  • _free_cb – Function to be called for free event

HEAP_LISTENER_RESIZE_DEFINE(name, _heap_id, _resize_cb)

Define heap event listener node for resize event.

Sample usage: 

void on_heap_resized(uintptr_t heap_id, void *old_heap_end, void *new_heap_end)
{
  LOG_INF("Libc heap end moved from %p to %p", old_heap_end, new_heap_end);
}

HEAP_LISTENER_RESIZE_DEFINE(my_listener, HEAP_ID_LIBC, on_heap_resized);

Parameters:

  • name – Name of the heap event listener object

  • _heap_id – Identifier of the heap to be listened

  • _resize_cb – Function to be called when the listened heap is resized

Typedefs

typedef void (*heap_listener_resize_cb_t)(uintptr_t heap_id, void *old_heap_end, void *new_heap_end)

Callback used when heap is resized.

Note

Minimal C library does not emit this event.

Param heap_id:

Identifier of heap being resized

Param old_heap_end:

Pointer to end of heap before resize

Param new_heap_end:

Pointer to end of heap after resize

typedef void (*heap_listener_alloc_cb_t)(uintptr_t heap_id, void *mem, size_t bytes)

Callback used when there is heap allocation.

Note

Heaps managed by libraries outside of code in Zephyr main code repository may not emit this event.

Note

The number of bytes allocated may not match exactly to the request to the allocation function. Internal mechanism of the heap may allocate more than requested.

Param heap_id:

Heap identifier

Param mem:

Pointer to the allocated memory

Param bytes:

Size of allocated memory

typedef void (*heap_listener_free_cb_t)(uintptr_t heap_id, void *mem, size_t bytes)

Callback used when memory is freed from heap.

Note

Heaps managed by libraries outside of code in Zephyr main code repository may not emit this event.

Note

The number of bytes freed may not match exactly to the request to the allocation function. Internal mechanism of the heap dictates how memory is allocated or freed.

Param heap_id:

Heap identifier

Param mem:

Pointer to the freed memory

Param bytes:

Size of freed memory

Enums

enum heap_event_types

Values:

enumerator HEAP_EVT_UNKNOWN = 0
enumerator HEAP_RESIZE
enumerator HEAP_ALLOC
enumerator HEAP_FREE
enumerator HEAP_REALLOC
enumerator HEAP_MAX_EVENTS

Functions

void heap_listener_register(struct heap_listener *listener)

Register heap event listener.

Add the listener to the global list of heap listeners that can be notified by different heap implementations upon certain events related to the heap usage.

Parameters:
void heap_listener_unregister(struct heap_listener *listener)

Unregister heap event listener.

Remove the listener from the global list of heap listeners that can be notified by different heap implementations upon certain events related to the heap usage.

Parameters:
void heap_listener_notify_alloc(uintptr_t heap_id, void *mem, size_t bytes)

Notify listeners of heap allocation event.

Notify registered heap event listeners with matching heap identifier that an allocation has been done on heap

Parameters:

  • heap_id – Heap identifier

  • mem – Pointer to the allocated memory

  • bytes – Size of allocated memory

void heap_listener_notify_free(uintptr_t heap_id, void *mem, size_t bytes)

Notify listeners of heap free event.

Notify registered heap event listeners with matching heap identifier that memory is freed on heap

Parameters:

  • heap_id – Heap identifier

  • mem – Pointer to the freed memory

  • bytes – Size of freed memory

void heap_listener_notify_resize(uintptr_t heap_id, void *old_heap_end, void *new_heap_end)

Notify listeners of heap resize event.

Notify registered heap event listeners with matching heap identifier that the heap has been resized.

Parameters:

  • heap_id – Heap identifier

  • old_heap_end – Address of the heap end before the change

  • new_heap_end – Address of the heap end after the change

struct heap_listener
#include <heap_listener.h>

Public Members

sys_snode_t node

Singly linked list node.

uintptr_t heap_id

Identifier of the heap whose events are listened.

It can be a heap pointer, if the heap is represented as an object, or 0 in the case of the global libc heap.

enum heap_event_types event

The heap event to be notified.