This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Shared Multi Heap¶

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

The user can request allocation from the shared pool specifying the capability / attribute of interest for the memory (cacheable / non-cacheable memory, etc…).

The different heaps with their attributes available in the shared pool are defined into the DT file leveraging the reserved-memory nodes.

This is a DT example declaring three different memory regions with different cacheability attributes: cacheable and non-cacheable

/ {
     reserved-memory {
             compatible = "reserved-memory";
             #address-cells = <1>;
             #size-cells = <1>;

             res0: reserved@42000000 {
                     compatible = "shared-multi-heap";
                     reg = <0x42000000 0x1000>;
                     capability = "cacheable";
                     label = "res0";
             };

             res1: reserved@43000000 {
                     compatible = "shared-multi-heap";
                     reg = <0x43000000 0x2000>;
                     capability = "non-cacheable";
                     label = "res1";
             };

             res2: reserved2@44000000 {
                     compatible = "shared-multi-heap";
                     reg = <0x44000000 0x3000>;
                     capability = "cacheable";
                     label = "res2";
             };
     };

The user can then request 4K from heap memory cacheable or non-cacheable using the provided APIs:

// Allocate 4K from cacheable memory
shared_multi_heap_alloc(SMH_REG_ATTR_CACHEABLE, 0x1000);

// Allocate 4K from non-cacheable
shared_multi_heap_alloc(SMH_REG_ATTR_NON_CACHEABLE, 0x1000);

The backend implementation will allocate the memory region from the heap with the correct attribute and using the region able to accommodate the required size.

Special handling for MMU/MPU¶

For MMU/MPU enabled platform sometimes it is required to setup and configure the memory regions before these are added to the managed pool. This is done at init time using the shared_multi_heap_pool_init() function that is accepting a smh_init_reg_fn_t callback function. This callback will be called for each memory region at init time and it can be used to correctly map the region before this is considered valid and accessible.

Adding new attributes¶

Currently only two memory attributes are supported: cacheable and non-cacheable. To add a new attribute:

Add the new enum for the attribute in the smh_reg_attr
Add the corresponding attribute name in shared-multi-heap.yaml

group shared_multi_heap

Shared multi-heap interface.

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

The user can request allocation from the shared pool specifying the capability / attribute of interest for the memory (cacheable / non-cacheable memory, etc…)

Typedefs

typedef bool (*smh_init_reg_fn_t)(struct shared_multi_heap_region *reg, uint8_t **v_addr, size_t *size)¶

Region init function.

This is a user-provided function whose responsibility is to setup or initialize the memory region passed in input before this is added to the heap pool by the shared multi-heap manager. This function can be used by architectures using MMU / MPU that must correctly map the region before this is considered valid and accessible.

Param reg: Pointer to the SMH region structure.
Param v_addr: Virtual address obtained after mapping. For non-MMU architectures this value is the physical address of the region.
Param size: Size of the region after mapping.
Return: True if the region is ready to be added to the heap pool. False if the region must be skipped.

Enums

enum smh_reg_attr¶

Memory region attributes / capabilities.

** This list needs to be kept in sync with shared-multi-heap.yaml **

Values:

enumerator SMH_REG_ATTR_CACHEABLE¶: cacheable

enumerator SMH_REG_ATTR_NON_CACHEABLE¶: non-cacheable

enumerator SMH_REG_ATTR_NUM¶: must be the last item

Functions

int shared_multi_heap_pool_init(smh_init_reg_fn_t smh_init_reg_fn)¶

Init the pool.

Initialize the shared multi-heap pool and hook-up the region init function.

Parameters

smh_init_reg_fn – The function pointer to the region init function. Can be NULL for non-MPU / non-MMU architectures.

void *shared_multi_heap_alloc(enum smh_reg_attr attr, size_t bytes)¶

Allocate memory from the memory shared multi-heap pool.

Allocate a block of memory of the specified size in bytes and with a specified capability / attribute.

Parameters

attr – Capability / attribute requested for the memory block.
bytes – Requested size of the allocation in bytes.

Returns

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

void shared_multi_heap_free(void *block)¶

Free memory from the shared multi-heap pool.

Free the passed block of memory.

Parameters

block – Block to free.

struct shared_multi_heap_region¶

#include <shared_multi_heap.h>

SMH region struct.

This struct is carrying information about the memory region to be added in the multi-heap pool. This is filled by the manager with the information coming from the reserved memory children nodes in the DT.