doc: lib/os: Add overview docs for sys_multi_heap

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

Signed-off-by: Andy Ross <[email protected]>

Author: Andy Ross

doc/reference/kernel/memory/heap.rst

@@ -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
 ***********