1.. _mem_mgmt_api:
2
3Memory Attributes
4#################
5
6It is possible in the devicetree to mark the memory regions with attributes by
7using the ``zephyr,memory-attr`` property. This property and the related memory
8region can then be retrieved at run-time by leveraging a provided helper
9library.
10
11The set of general attributes that can be specified in the property are defined
12and explained in :zephyr_file:`include/zephyr/dt-bindings/memory-attr/memory-attr.h`.
13
14For example, to mark a memory region in the devicetree as non-volatile, cacheable,
15out-of-order:
16
17.. code-block:: devicetree
18
19   mem: memory@10000000 {
20       compatible = "mmio-sram";
21       reg = <0x10000000 0x1000>;
22       zephyr,memory-attr = <( DT_MEM_NON_VOLATILE | DT_MEM_CACHEABLE | DT_MEM_OOO )>;
23   };
24
25.. note::
26
27   The ``zephyr,memory-attr`` usage does not result in any memory region
28   actually created. When it is needed to create an actual section out of the
29   devicetree defined memory region, it is possible to use the compatible
30   :dtcompatible:`zephyr,memory-region` that will result (only when supported
31   by the architecture) in a new linker section and region.
32
33The ``zephyr,memory-attr`` property can also be used to set
34architecture-specific and software-specific custom attributes that can be
35interpreted at run time. This is leveraged, among other things, to create MPU
36regions out of devicetree defined memory regions, for example:
37
38.. code-block:: devicetree
39
40   mem: memory@10000000 {
41       compatible = "mmio-sram";
42       reg = <0x10000000 0x1000>;
43       zephyr,memory-region = "NOCACHE_REGION";
44       zephyr,memory-attr = <( DT_MEM_ARM(ATTR_MPU_RAM_NOCACHE) )>;
45   };
46
47See :zephyr_file:`include/zephyr/dt-bindings/memory-attr/memory-attr-arm.h` and
48:ref:`arm_cortex_m_developer_guide` for more details about MPU usage.
49
50The conventional and recommended way to deal and manage with memory regions
51marked with attributes is by using the provided ``mem-attr`` helper library by
52enabling :kconfig:option:`CONFIG_MEM_ATTR`. When this option is enabled the
53list of memory regions and their attributes are compiled in a user-accessible
54array and a set of functions is made available that can be used to query, probe
55and act on regions and attributes (see next section for more details).
56
57.. note::
58
59   The ``zephyr,memory-attr`` property is only a descriptive property of the
60   capabilities of the associated memory region, but it does not result in any
61   actual setting for the memory to be set. The user, code or subsystem willing
62   to use this information to do some work (for example creating an MPU region
63   out of the property) must use either the provided ``mem-attr`` library or
64   the usual devicetree helpers to perform the required work / setting.
65
66A test for the ``mem-attr`` library and its usage is provided in
67``tests/subsys/mem_mgmt/mem_attr/``.
68
69Migration guide from `zephyr,memory-region-mpu`
70***********************************************
71
72When the ``zephyr,memory-attr`` property was introduced, the
73``zephyr,memory-region-mpu`` property was removed and deprecated.
74
75The developers that are still using the deprecated property can move to the new
76one by renaming the property and changing its value according to the following list:
77
78.. code-block:: none
79
80   "RAM"         -> <( DT_ARM_MPU(ATTR_MPU_RAM) )>
81   "RAM_NOCACHE" -> <( DT_ARM_MPU(ATTR_MPU_RAM_NOCACHE) )>
82   "FLASH"       -> <( DT_ARM_MPU(ATTR_MPU_FLASH) )>
83   "PPB"         -> <( DT_ARM_MPU(ATTR_MPU_PPB) )>
84   "IO"          -> <( DT_ARM_MPU(ATTR_MPU_IO) )>
85   "EXTMEM"      -> <( DT_ARM_MPU(ATTR_MPU_EXTMEM) )>
86
87API Reference
88*************
89
90.. doxygengroup:: memory_attr_interface
91