.. _memory_management_shared_multi_heap:

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``

.. code-block:: devicetree

   / {
        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:

.. code-block:: c

   // 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 :c:func:`shared_multi_heap_pool_init()` function that is
accepting a :c:type:`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:

1. Add the new ``enum`` for the attribute in the :c:enum:`smh_reg_attr`
2. Add the corresponding attribute name in :file:`shared-multi-heap.yaml`

.. doxygengroup:: shared_multi_heap
   :project: Zephyr