Heap APIs

Data Structures
struct	k_heap

Macros
#define	K_HEAP_DEFINE(name, bytes)
	Define a static k_heap.
#define	K_HEAP_DEFINE_NOCACHE(name, bytes)
	Define a static k_heap in uncached memory.

Functions
void	k_heap_init (struct k_heap *h, void *mem, size_t bytes)
	Initialize a k_heap.
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.
void *	k_heap_alloc (struct k_heap *h, size_t bytes, k_timeout_t timeout)
	Allocate memory from a k_heap.
void *	k_heap_realloc (struct k_heap *h, void *ptr, size_t bytes, k_timeout_t timeout)
	Reallocate memory from a k_heap.
void	k_heap_free (struct k_heap *h, void *mem)
	Free memory allocated by k_heap_alloc()
void *	k_aligned_alloc (size_t align, size_t size)
	Allocate memory from the heap with a specified alignment.
void *	k_malloc (size_t size)
	Allocate memory from the heap.
void	k_free (void *ptr)
	Free memory allocated from heap.
void *	k_calloc (size_t nmemb, size_t size)
	Allocate memory from heap, array style.
void *	k_realloc (void *ptr, size_t size)
	Expand the size of an existing allocation.

Detailed Description

Macro Definition Documentation

K_HEAP_DEFINE

#define K_HEAP_DEFINE	(		name,
			bytes )

#include <zephyr/kernel.h>

Value:

        Z_HEAP_DEFINE_IN_SECT(name, bytes,                      \
                              __noinit_named(kheap_buf_##name))

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

#define K_HEAP_DEFINE_NOCACHE	(		name,
			bytes )

#include <zephyr/kernel.h>

Value:

        Z_HEAP_DEFINE_IN_SECT(name, bytes, __nocache)

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

Function Documentation

k_aligned_alloc()

void * k_aligned_alloc	(	size_t	align,
		size_t	size )

#include <zephyr/kernel.h>

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.

k_calloc()

void * k_calloc	(	size_t	nmemb,
		size_t	size )

#include <zephyr/kernel.h>

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.

k_free()

void k_free

(

void *

ptr

)

#include <zephyr/kernel.h>

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.

k_heap_aligned_alloc()

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

isr-ok

#include <zephyr/kernel.h>

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().

Note

timeout must be set to K_NO_WAIT if called from ISR.

When CONFIG_MULTITHREADING=n any timeout is treated as K_NO_WAIT.

Function properties (list may not be complete)

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

k_heap_alloc()

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

isr-ok

#include <zephyr/kernel.h>

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.

Note

timeout must be set to K_NO_WAIT if called from ISR.

When CONFIG_MULTITHREADING=n any timeout is treated as K_NO_WAIT.

Function properties (list may not be complete)

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

k_heap_free()

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

#include <zephyr/kernel.h>

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

k_heap_init()

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

#include <zephyr/kernel.h>

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

k_heap_realloc()

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

isr-ok

#include <zephyr/kernel.h>

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.

Note

timeout must be set to K_NO_WAIT if called from ISR.

When CONFIG_MULTITHREADING=n any timeout is treated as K_NO_WAIT.

Function properties (list may not be complete)

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

k_malloc()

void * k_malloc

(

size_t

size

)

#include <zephyr/kernel.h>

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.

k_realloc()

void * k_realloc	(	void *	ptr,
		size_t	size )

#include <zephyr/kernel.h>

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.