Zephyr Project API 3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

Data Structures

struct  sys_multi_heap_rec
 
struct  sys_multi_heap
 

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

Detailed Description

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 <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
mheapMulti-heap structure.
cfgAn opaque user-provided value. It may be interpreted in any way by the application
alignAlignment of requested memory (or zero for no alignment)
sizeThe 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 <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
mheapA sys_multi_heap to which to add a heap
heapThe heap to add
user_datapointer 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 <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
mheapMulti heap pointer
cfgOpaque configuration parameter, as for sys_multi_heap_fn_t
alignPower of two alignment for the returned pointer, in bytes
bytesRequested 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 
)

#include <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
mheapMulti heap pointer
cfgOpaque configuration parameter, as for sys_multi_heap_fn_t
bytesRequested 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 <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
mheapMulti heap pointer
blockBlock 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 <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
mheapMulti heap pointer
addraddress 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 <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
heapA sys_multi_heap to initialize
choice_fnA sys_multi_heap_fn_t callback used to select heaps at allocation time