multi_heap.h File Reference

#include <zephyr/types.h>

Go to the source code of this file.

Data Structures
struct	sys_multi_heap_rec
struct	sys_multi_heap

Macros
#define	MAX_MULTI_HEAPS   8

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.

Macro Definition Documentation

MAX_MULTI_HEAPS

#define MAX_MULTI_HEAPS   8

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)

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
	)

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
	)

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

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

sys_multi_heap_free()

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

sys_multi_heap_get_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.

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
	)

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