bartoszek/zephyr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Add documentation for the new allocator

Browse Source 
Add new documentation for the new attribute-based memory allocator.

Signed-off-by: Carlo Caione <ccaione@baylibre.com>
This commit is contained in:
Carlo Caione 2023-09-23 17:34:32 +02:00 committed by Carles Cufí
parent 09fd6b6ea5
commit 06571fc87b
1 changed files with 105 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
doc/services/mem_mgmt/index.rst
View File

@ -84,7 +84,112 @@ one by renaming the property and changing its value according to the following l
"IO" -> <( DT_ARM_MPU(ATTR_MPU_IO) )>
"EXTMEM" -> <( DT_ARM_MPU(ATTR_MPU_EXTMEM) )>
Memory Attributes Heap Allocator
********************************
It is possible to leverage the memory attribute property ``zephyr,memory-attr``
to define and create a set of memory heaps from which the user can allocate
memory from with certain attributes / capabilities.
When the :kconfig:option:`CONFIG_MEM_ATTR_HEAP` is set, every region marked
with one of the memory attributes listed in in
:zephyr_file:`include/zephyr/dt-bindings/memory-attr/memory-attr-sw.h` is added
to a pool of memory heaps used for dynamic allocation of memory buffers with
certain attributes.
Here a non exhaustive list of possible attributes:
.. code-block:: none
DT_MEM_SW_ALLOC_CACHE
DT_MEM_SW_ALLOC_NON_CACHE
DT_MEM_SW_ALLOC_DMA
For example we can define several memory regions with different attributes and
use the appropriate attribute to indicate that it is possible to dynamically
allocate memory from those regions:
.. code-block:: devicetree
mem_cacheable: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_CACHEABLE | DT_MEM_SW_ALLOC_CACHE )>;
};
mem_non_cacheable: memory@20000000 {
compatible = "mmio-sram";
reg = <0x20000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_NON_CACHEABLE | ATTR_SW_ALLOC_NON_CACHE )>;
};
mem_cacheable_big: memory@30000000 {
compatible = "mmio-sram";
reg = <0x30000000 0x10000>;
zephyr,memory-attr = <( DT_MEM_CACHEABLE | DT_MEM_OOO | DT_MEM_SW_ALLOC_CACHE )>;
};
mem_cacheable_dma: memory@40000000 {
compatible = "mmio-sram";
reg = <0x40000000 0x10000>;
zephyr,memory-attr = <( DT_MEM_CACHEABLE | DT_MEM_DMA |
DT_MEM_SW_ALLOC_CACHE | DT_MEM_SW_ALLOC_DMA )>;
};
The user can then dynamically carve memory out of those regions using the
provided functions, the library will take care of allocating memory from the
correct heap depending on the provided attribute and size:
.. code-block:: c
// Init the pool
mem_attr_heap_pool_init();
// Allocate 0x100 bytes of cacheable memory from `mem_cacheable`
block = mem_attr_heap_alloc(DT_MEM_SW_ALLOC_CACHE, 0x100);
// Allocate 0x200 bytes of non-cacheable memory aligned to 32 bytes
// from `mem_non_cacheable`
block = mem_attr_heap_aligned_alloc(ATTR_SW_ALLOC_NON_CACHE, 0x100, 32);
// Allocate 0x100 bytes of cacheable and dma-able memory from `mem_cacheable_dma`
block = mem_attr_heap_alloc(DT_MEM_SW_ALLOC_CACHE | DT_MEM_SW_ALLOC_DMA, 0x100);
When several regions are marked with the same attributes, the memory is allocated:
1. From the regions where the ``zephyr,memory-attr`` property has the requested
property (or properties).
2. Among the regions as at point 1, from the smallest region if there is any
unallocated space left for the requested size
3. If there is not enough space, from the next bigger region able to
accommodate the requested size
The following example shows the point 3:
.. code-block:: c
// This memory is allocated from `mem_non_cacheable`
block = mem_attr_heap_alloc(DT_MEM_SW_ALLOC_CACHE, 0x100);
// This memory is allocated from `mem_cacheable_big`
block = mem_attr_heap_alloc(DT_MEM_SW_ALLOC_CACHE, 0x5000);
.. note::
The framework is assuming that the memory regions used to create the heaps
are usable by the code and available at init time. The user must take of
initializing and setting the memory area before calling
:c:func:`mem_attr_heap_pool_init`.
That means that the region must be correctly configured in terms of MPU /
MMU (if needed) and that an actual heap can be created out of it, for
example by leveraging the ``zephyr,memory-region`` property to create a
proper linker section to accommodate the heap.
API Reference
*************
.. doxygengroup:: memory_attr_interface
.. doxygengroup:: memory_attr_heap