Part 1
요약·해설
Descriptive property와 실제 mapping의 차이, deprecated MPU property 변환, smallest-fit region 선택과 initialization 책임을 설명합니다.
zephyr,memory-attr
mem-attr
Attribute + size
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
2EF93ECF527A21F7B9AE3F38D7F24931F017F157FCAFE8ADE8C12BA7CAD5B5BB
.. _mem_mgmt_api:
Memory Attributes
#################
It is possible in the devicetree to mark the memory regions with attributes by
using the ``zephyr,memory-attr`` property. This property and the related memory
region can then be retrieved at run-time by leveraging a provided helper
library.
The set of general attributes that can be specified in the property are defined
and explained in :zephyr_file:`include/zephyr/dt-bindings/memory-attr/memory-attr.h`.
For example, to mark a memory region in the devicetree as non-volatile, cacheable,
out-of-order:
.. code-block:: devicetree
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_NON_VOLATILE | DT_MEM_CACHEABLE | DT_MEM_OOO )>;
};
.. note::
The ``zephyr,memory-attr`` usage does not result in any memory region
actually created. When it is needed to create an actual section out of the
devicetree defined memory region, it is possible to use the compatible
:dtcompatible:`zephyr,memory-region` that will result (only when supported
by the architecture) in a new linker section and region.
The ``zephyr,memory-attr`` property can also be used to set
architecture-specific and software-specific custom attributes that can be
interpreted at run time. This is leveraged, among other things, to create MPU
regions out of devicetree defined memory regions, for example:
.. code-block:: devicetree
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-region = "NOCACHE_REGION";
zephyr,memory-attr = <( DT_MEM_ARM(ATTR_MPU_RAM_NOCACHE) )>;
};
See :zephyr_file:`include/zephyr/dt-bindings/memory-attr/memory-attr-arm.h` and
:ref:`arm_cortex_m_developer_guide` for more details about MPU usage.
The conventional and recommended way to deal and manage with memory regions
marked with attributes is by using the provided ``mem-attr`` helper library by
enabling :kconfig:option:`CONFIG_MEM_ATTR`. When this option is enabled the
list of memory regions and their attributes are compiled in a user-accessible
array and a set of functions is made available that can be used to query, probe
and act on regions and attributes (see next section for more details).
.. note::
The ``zephyr,memory-attr`` property is only a descriptive property of the
capabilities of the associated memory region, but it does not result in any
actual setting for the memory to be set. The user, code or subsystem willing
to use this information to do some work (for example creating an MPU region
out of the property) must use either the provided ``mem-attr`` library or
the usual devicetree helpers to perform the required work / setting.
A test for the ``mem-attr`` library and its usage is provided in
``tests/subsys/mem_mgmt/mem_attr/``.
Migration guide from `zephyr,memory-region-mpu`
***********************************************
When the ``zephyr,memory-attr`` property was introduced, the
``zephyr,memory-region-mpu`` property was removed and deprecated.
The developers that are still using the deprecated property can move to the new
one by renaming the property and changing its value according to the following list:
.. code-block:: none
"RAM" -> <( DT_ARM_MPU(ATTR_MPU_RAM) )>
"RAM_NOCACHE" -> <( DT_ARM_MPU(ATTR_MPU_RAM_NOCACHE) )>
"FLASH" -> <( DT_ARM_MPU(ATTR_MPU_FLASH) )>
"PPB" -> <( DT_ARM_MPU(ATTR_MPU_PPB) )>
"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
: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_NON_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
Part 3
한국어 전문 번역
Devicetree의 zephyr,memory-attr property로 memory region에 attribute를 표시할 수 있습니다. Runtime에는 helper library를 사용해 property와 연결된 region을 조회합니다.
일반 attribute 집합과 의미는 include/zephyr/dt-bindings/memory-attr/memory-attr.h에 정의돼 있습니다. 다음 예는 region을 non-volatile, cacheable, out-of-order로 표시합니다.
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-attr = <( DT_MEM_NON_VOLATILE | DT_MEM_CACHEABLE | DT_MEM_OOO )>;
};
zephyr,memory-attr에는 architecture-specific 또는 software-specific custom attribute도 넣어 runtime에 해석할 수 있습니다. 예를 들어 devicetree memory region에서 MPU region을 만들 때 다음처럼 사용합니다.
mem: memory@10000000 {
compatible = "mmio-sram";
reg = <0x10000000 0x1000>;
zephyr,memory-region = "NOCACHE_REGION";
zephyr,memory-attr = <( DT_MEM_ARM(ATTR_MPU_RAM_NOCACHE) )>;
};
ARM MPU attribute와 사용법은 include/zephyr/dt-bindings/memory-attr/memory-attr-arm.h와 ARM Cortex-M developer guide에서 설명합니다.
Attribute가 표시된 region은 CONFIG_MEM_ATTR을 활성화하고 mem-attr helper library로 관리하는 방식을 권장합니다. 활성화하면 memory region과 attribute 목록이 user-accessible array로 compile되고 region과 attribute를 query, probe, 처리하는 function이 제공됩니다.
Library test와 사용 예는 tests/subsys/mem_mgmt/mem_attr/에 있습니다.
zephyr,memory-region-mpu migration guide
zephyr,memory-attr이 도입되면서 zephyr,memory-region-mpu property는 제거되고 deprecated되었습니다. 기존 user는 property name을 바꾸고 value를 다음처럼 변환합니다.
"RAM" -> <( DT_ARM_MPU(ATTR_MPU_RAM) )>
"RAM_NOCACHE" -> <( DT_ARM_MPU(ATTR_MPU_RAM_NOCACHE) )>
"FLASH" -> <( DT_ARM_MPU(ATTR_MPU_FLASH) )>
"PPB" -> <( DT_ARM_MPU(ATTR_MPU_PPB) )>
"IO" -> <( DT_ARM_MPU(ATTR_MPU_IO) )>
"EXTMEM" -> <( DT_ARM_MPU(ATTR_MPU_EXTMEM) )>
Memory Attributes Heap Allocator
zephyr,memory-attr로 특정 attribute 또는 capability를 가진 memory를 allocate할 heap 묶음을 정의할 수 있습니다.
CONFIG_MEM_ATTR_HEAP을 설정하면 include/zephyr/dt-bindings/memory-attr/memory-attr-sw.h의 software allocation attribute가 표시된 모든 region이 dynamic buffer allocation용 heap pool에 들어갑니다. 대표 attribute는 다음과 같습니다.
DT_MEM_SW_ALLOC_CACHE
DT_MEM_SW_ALLOC_NON_CACHE
DT_MEM_SW_ALLOC_DMA
다음 예는 cacheable, non-cacheable, 더 큰 cacheable, DMA-capable cacheable region을 각각 정의합니다.
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 )>;
};
Library는 요청한 attribute와 size를 보고 올바른 heap에서 memory를 carve합니다.
// 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);
같은 attribute가 표시된 region이 여러 개라면 다음 순서로 선택합니다.
zephyr,memory-attr에 요청한 attribute를 모두 가진 region만 후보로 삼습니다.- 후보 중 요청 size를 넣을 unallocated space가 남은 가장 작은 region을 먼저 사용합니다.
- 공간이 부족하면 요청 size를 수용할 수 있는 다음으로 큰 region을 사용합니다.
다음 예에서 작은 non-cacheable request는 mem_non_cacheable에서, 0x5000-byte cacheable request는 작은 region에 들어가지 않으므로 mem_cacheable_big에서 할당됩니다.
// This memory is allocated from `mem_non_cacheable`
block = mem_attr_heap_alloc(DT_MEM_SW_ALLOC_NON_CACHE, 0x100);
// This memory is allocated from `mem_cacheable_big`
block = mem_attr_heap_alloc(DT_MEM_SW_ALLOC_CACHE, 0x5000);
API Reference
Memory attribute query API는 memory_attr_interface, attribute heap API는 memory_attr_heap Doxygen group에 있습니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.