1.. _memory_management_shared_multi_heap:
2
3Shared Multi Heap
4#################
5
6The shared multi-heap memory pool manager uses the multi-heap allocator to
7manage a set of reserved memory regions with different capabilities /
8attributes (cacheable, non-cacheable, etc...).
9
10All the different regions can be added at run-time to the shared multi-heap
11pool providing an opaque "attribute" value (an integer or enum value) that can
12be used by drivers or applications to request memory with certain capabilities.
13
14This framework is commonly used as follow:
15
161. At boot time some platform code initialize the shared multi-heap framework
17   using :c:func:`shared_multi_heap_pool_init()` and add the memory regions to
18   the pool with :c:func:`shared_multi_heap_add()`, possibly gathering the
19   needed information for the regions from the DT.
20
212. Each memory region encoded in a :c:struct:`shared_multi_heap_region`
22   structure.  This structure is also carrying an opaque and user-defined
23   integer value that is used to define the region capabilities (for example:
24   cacheability, cpu affinity, etc...)
25
26.. code-block:: c
27
28   // Init the shared multi-heap pool
29   shared_multi_heap_pool_init()
30
31   // Fill the struct with the data for cacheable memory
32   struct shared_multi_heap_region cacheable_r0 = {
33        .addr = addr_r0,
34        .size = size_r0,
35        .attr = SMH_REG_ATTR_CACHEABLE,
36   };
37
38   // Add the region to the pool
39   shared_multi_heap_add(&cacheable_r0, NULL);
40
41   // Add another cacheable region
42   struct shared_multi_heap_region cacheable_r1 = {
43        .addr = addr_r1,
44        .size = size_r1,
45        .attr = SMH_REG_ATTR_CACHEABLE,
46   };
47
48   shared_multi_heap_add(&cacheable_r0, NULL);
49
50   // Add a non-cacheable region
51   struct shared_multi_heap_region non_cacheable_r2 = {
52        .addr = addr_r2,
53        .size = size_r2,
54        .attr = SMH_REG_ATTR_NON_CACHEABLE,
55   };
56
57   shared_multi_heap_add(&non_cacheable_r2, NULL);
58
593. When a driver or application needs some dynamic memory with a certain
60   capability, it can use :c:func:`shared_multi_heap_alloc()` (or the aligned
61   version) to request the memory by using the opaque parameter to select the
62   correct set of attributes for the needed memory. The framework will take
63   care of selecting the correct heap (thus memory region) to carve memory
64   from, based on the opaque parameter and the runtime state of the heaps
65   (available memory, heap state, etc...)
66
67.. code-block:: c
68
69   // Allocate 4K from cacheable memory
70   shared_multi_heap_alloc(SMH_REG_ATTR_CACHEABLE, 0x1000);
71
72   // Allocate 4K from non-cacheable memory
73   shared_multi_heap_alloc(SMH_REG_ATTR_NON_CACHEABLE, 0x1000);
74
75Adding new attributes
76*********************
77
78The API does not enforce any attributes, but at least it defines the two most
79common ones: :c:enumerator:`SMH_REG_ATTR_CACHEABLE` and :c:enumerator:`SMH_REG_ATTR_NON_CACHEABLE`.
80
81.. doxygengroup:: shared_multi_heap
82