Multi-Heap Wrapper

Data Structures
struct	sys_multi_heap_rec
struct	sys_multi_heap

Macros
#define	sys_multi_heap_realloc(mheap, cfg, ptr, bytes)

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.

Functions
void	sys_multi_heap_init (struct sys_multi_heap *heap, sys_multi_heap_fn_t choice_fn)
	Initialize multi-heap.
void	sys_multi_heap_add_heap (struct sys_multi_heap *mheap, struct sys_heap *heap, void *user_data)
	Add sys_heap to multi heap.
void *	sys_multi_heap_alloc (struct sys_multi_heap *mheap, void *cfg, size_t bytes)
	Allocate memory from multi heap.
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.
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.
void	sys_multi_heap_free (struct sys_multi_heap *mheap, void *block)
	Free memory allocated from multi heap.
void *	sys_multi_heap_aligned_realloc (struct sys_multi_heap *mheap, void *cfg, void *ptr, size_t align, size_t bytes)
	Expand the size of an existing allocation on the multi heap.

Detailed Description

Macro Definition Documentation

sys_multi_heap_realloc

#define sys_multi_heap_realloc	(		mheap,
			cfg,
			ptr,
			bytes )

#include <zephyr/sys/multi_heap.h>

Value:

        sys_multi_heap_aligned_realloc(mheap, cfg, ptr, 0, bytes)

Typedef Documentation

sys_multi_heap_fn_t

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

#include <zephyr/sys/multi_heap.h>

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.

Parameters

mheap	Multi-heap structure.
cfg	An opaque user-provided value. It may be interpreted in any way by the application
align	Alignment of requested memory (or zero for no alignment)
size	The user-specified allocation size in bytes

Returns

A pointer to the allocated memory

Function Documentation

sys_multi_heap_add_heap()

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

#include <zephyr/sys/multi_heap.h>

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

sys_multi_heap_aligned_alloc()

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

#include <zephyr/sys/multi_heap.h>

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

sys_multi_heap_aligned_realloc()

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

#include <zephyr/sys/multi_heap.h>

Expand the size of an existing allocation on the multi heap.

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. If a new allocation is needed, the choice for the heap used will be bases on the cfg parameter (same as in sys_multi_heap_aligned_alloc).

Parameters

mheap	Multi heap pointer
cfg	Opaque configuration parameter, as for sys_multi_heap_fn_t
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

sys_multi_heap_alloc()

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

#include <zephyr/sys/multi_heap.h>

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

sys_multi_heap_free()

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

#include <zephyr/sys/multi_heap.h>

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

sys_multi_heap_get_heap()

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

#include <zephyr/sys/multi_heap.h>

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

sys_multi_heap_init()

void sys_multi_heap_init	(	struct sys_multi_heap *	heap,
		sys_multi_heap_fn_t	choice_fn )

#include <zephyr/sys/multi_heap.h>

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