michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: lib/os: Add overview docs for sys_multi_heap

Browse source 
Add a short section to the "heap" page detailing the new
sys_multi_heap utility.

Signed-off-by: Andy Ross <andrew.j.ross@intel.com>
This commit is contained in:
Andy Ross 2021-10-01 08:32:01 -07:00 • committed by Anas Nashif
commit a8f02ed5ee
1 changed files with 37 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

37
doc/reference/kernel/memory/heap.rst
View file

@ -95,6 +95,43 @@ unbounded list searches, at the expense of some fragmentation
resistance. This :c:kconfig:`CONFIG_SYS_HEAP_ALLOC_LOOPS` value may be
chosen by the user at build time, and defaults to a value of 3.
Multi-Heap Wrapper Utility
**************************
The ``sys_heap`` utility requires that all managed memory be in a
single contiguous block. It is common for complicated microcontroller
applications to have more complicated memory setups that they still
want to manage dynamically as a "heap". For example, the memory might
exist as separate discontiguous regions, different areas may have
different cache, performance or power behavior, peripheral devices may
only be able to perform DMA to certain regions, etc...
For those situations, Zephyr provides a ``sys_multi_heap`` utility.
Effectively this is a simple wrapper around a set of one or more
``sys_heap`` objects. It should be initialized after its child heaps
via :c:func:`sys_multi_heap_init`, after which each heap can be added
to the managed set via :c:func:`sys_multi_heap_add_heap`. No
destruction utility is provided; just as for ``sys_heap``,
applications that want to destroy a multi heap should simply ensure
all allocated blocks are freed (or at least will never be used again)
and repurpose the underlying memory for another usage.
It has a single pair of allocation entry points,
:c:func:`sys_multi_heap_alloc` and
:c:func:`sys_multi_heap_aligned_alloc`. These behave identically to
the ``sys_heap`` functions with similar names, except that they also
accept an opaque "configuration" parameter. This pointer is
uninspected by the multi heap code itself; instead it is passed to a
callback function provided at initialization time. This
application-provided callback is responsible for doing the underlying
allocation from one of the managed heaps, and may use the
configuration parameter in any way it likes to make that decision.
When unused, a multi heap may be freed via
:c:func:`sys_multi_heap_free`. The application does not need to pass
a configuration parameter. Memory allocated from any of the managed
``sys_heap`` objects may be freed with in the same way.
System Heap
***********