Shared multi-heap interface

Shared Multi-Heap (SMH) interface. More...

Data Structures
struct	shared_multi_heap_region
	SMH region struct. More...

Macros
#define	MAX_SHARED_MULTI_HEAP_ATTR   SMH_REG_ATTR_NUM
	Maximum number of standard attributes.

Enumerations
enum	shared_multi_heap_attr { SMH_REG_ATTR_CACHEABLE , SMH_REG_ATTR_NON_CACHEABLE , SMH_REG_ATTR_NUM }
	SMH region attributes enumeration type. More...

Functions
int	shared_multi_heap_pool_init (void)
	Init the pool.
void *	shared_multi_heap_alloc (enum shared_multi_heap_attr attr, size_t bytes)
	Allocate memory from the memory shared multi-heap pool.
void *	shared_multi_heap_aligned_alloc (enum shared_multi_heap_attr attr, size_t align, size_t bytes)
	Allocate aligned memory from the memory shared multi-heap pool.
void	shared_multi_heap_free (void *block)
	Free memory from the shared multi-heap pool.
int	shared_multi_heap_add (struct shared_multi_heap_region *region, void *user_data)
	Add an heap region to the shared multi-heap pool.

Detailed Description

Shared Multi-Heap (SMH) interface.

The shared multi-heap manager uses the multi-heap allocator to manage a set of memory regions with different capabilities / attributes (cacheable, non-cacheable, etc...).

All the different regions can be added at run-time to the shared multi-heap pool providing an opaque "attribute" value (an integer or enum value) that can be used by drivers or applications to request memory with certain capabilities.

This framework is commonly used as follow:

• At boot time some platform code initialize the shared multi-heap framework using shared_multi_heap_pool_init and add the memory regions to the pool with shared_multi_heap_add, possibly gathering the needed information for the regions from the DT.
• Each memory region encoded in a shared_multi_heap_region structure. This structure is also carrying an opaque and user-defined integer value that is used to define the region capabilities (for example: cacheability, cpu affinity, etc...)
• When a driver or application needs some dynamic memory with a certain capability, it can use shared_multi_heap_alloc (or the aligned version) to request the memory by using the opaque parameter to select the correct set of attributes for the needed memory. The framework will take care of selecting the correct heap (thus memory region) to carve memory from, based on the opaque parameter and the runtime state of the heaps (available memory, heap state, etc...)

Macro Definition Documentation

MAX_SHARED_MULTI_HEAP_ATTR

#define MAX_SHARED_MULTI_HEAP_ATTR   SMH_REG_ATTR_NUM

#include <zephyr/multi_heap/shared_multi_heap.h>

Maximum number of standard attributes.

Enumeration Type Documentation

shared_multi_heap_attr

enum shared_multi_heap_attr

#include <zephyr/multi_heap/shared_multi_heap.h>

SMH region attributes enumeration type.

Enumeration type for some common memory region attributes.

Enumerator
SMH_REG_ATTR_CACHEABLE	cacheable
SMH_REG_ATTR_NON_CACHEABLE	non-cacheable
SMH_REG_ATTR_NUM	must be the last item

Function Documentation

shared_multi_heap_add()

int shared_multi_heap_add	(	struct shared_multi_heap_region *	region,
		void *	user_data
	)

#include <zephyr/multi_heap/shared_multi_heap.h>

Add an heap region to the shared multi-heap pool.

This adds a shared multi-heap region to the multi-heap pool.

Parameters

user_data	pointer to any data for the heap.
region	pointer to the memory region to be added.

Return values

0	on success.
-EINVAL	when the region attribute is out-of-bound.
-ENOMEM	when there are no more heaps available.
other	errno codes

shared_multi_heap_aligned_alloc()

void * shared_multi_heap_aligned_alloc	(	enum shared_multi_heap_attr	attr,
		size_t	align,
		size_t	bytes
	)

#include <zephyr/multi_heap/shared_multi_heap.h>

Allocate aligned memory from the memory shared multi-heap pool.

Allocates a block of memory of the specified size in bytes and with a specified capability / attribute. Takes an additional parameter specifying a power of two alignment in bytes.

Parameters

attr	capability / attribute requested for the memory block.
align	power of two alignment for the returned pointer, in bytes.
bytes	requested size of the allocation in bytes.

Return values

ptr	a valid pointer to heap memory.
err	NULL if no memory is available.

shared_multi_heap_alloc()

void * shared_multi_heap_alloc	(	enum shared_multi_heap_attr	attr,
		size_t	bytes
	)

#include <zephyr/multi_heap/shared_multi_heap.h>

Allocate memory from the memory shared multi-heap pool.

Allocates a block of memory of the specified size in bytes and with a specified capability / attribute. The opaque attribute parameter is used by the backend to select the correct heap to allocate memory from.

Parameters

attr	capability / attribute requested for the memory block.
bytes	requested size of the allocation in bytes.

Return values

ptr	a valid pointer to heap memory.
err	NULL if no memory is available.

shared_multi_heap_free()

void shared_multi_heap_free

(

void *

block

)

#include <zephyr/multi_heap/shared_multi_heap.h>

Free memory from the shared multi-heap pool.

Used to free the passed block of memory that must be the return value of a previously call to shared_multi_heap_alloc or shared_multi_heap_aligned_alloc.

Parameters

block

block to free, must be a pointer to a block allocated by shared_multi_heap_alloc or shared_multi_heap_aligned_alloc.

shared_multi_heap_pool_init()

int shared_multi_heap_pool_init

(

void

)

#include <zephyr/multi_heap/shared_multi_heap.h>

Init the pool.

This must be the first function to be called to initialize the shared multi-heap pool. All the individual heaps must be added later with shared_multi_heap_add.

Note

As for the generic multi-heap allocator the expectation is that this function will be called at soc- or board-level.

Return values

0	on success.
-EALREADY	when the pool was already inited.
other	errno codes