devicetree: Add 'zephyr,memory-attr' and DT helpers

The 'zephyr,memory-region-mpu' property was addede gqas a
convenient way to create and configure MPU regions using information
coming from DT. It has been used a lot since it was introduced so I
guess we can consider it a Zephyr success story ™ .

Unfortunately it has been proved to be a bit limited and with some
important limitations:

1. It was introduced as a property of the compatible
   zephyr,memory-region that is used to create linker regions and
   sections from DT data. This means that we can actually create MPU
   regions only for DT-defined regions and sections.
2. The naming is unfortunate because it is implying that it is used only
   for MPU.
3. It is misplaced being in include/zephyr/linker/devicetree_regions.h
   and still it has nothing to do with the linker at all.
4. It is exporting a function called LINKER_DT_REGION_MPU that again has
   nothing to do with the linker.

Point (1) is also particularly limiting because it is preventing us to
characterize memory regions that are not generated using the
'zephyr,memory-region' compatible, like generic mmio-sram regions.

While we fix all the issues, we also want to extend a bit the range of
usefulness of this property. We are renaming it 'zephyr,memory-attr' and
it is now carrying information about the type of memory the property is
attached to (cacheable, non-cacheable, IO, eXecutable, etc...). The user
can use this property and the DT API coming with it to act on the memory
node it is accompanied by.

We are still providing the DT_MEMORY_ATTR_APPLY() macro that can be used
to create the MPU regions as before, but we are adding also a
DT_MEMORY_ATTR_FOREACH_NODE() macro that can be used to cycle through
the memory nodes and act on those.

Signed-off-by: Carlo Caione <[email protected]>

Author: carlocaione

doc/build/dts/api/api.rst

@@ -294,6 +294,15 @@ and properties related to them.
 
 .. doxygengroup:: devicetree-mbox
 
+.. _devicetree-memory-attr-api:
+
+Memory attributes
+=================
+
+These conveniences may be used for nodes with a memory attribute property.
+
+.. doxygengroup:: devicetree-memory-attr
+
 .. _devicetree-pinctrl-api:
 
 Pinctrl (pin control)

dts/bindings/base/zephyr,memory-attr.yaml

@@ -0,0 +1,20 @@
+# Copyright (c) 2023, Carlo Caione <[email protected]>
+# SPDX-License-Identifier: Apache-2.0
+
+include: [base.yaml]
+
+properties:
+  zephyr,memory-attr:
+    type: string
+    enum:
+      - "RAM"
+      - "RAM_NOCACHE"
+      - "FLASH"
+      - "PPB"
+      - "IO"
+      - "EXTMEM"
+    description: |
+      Attribute for the memory region.
+
+  reg:
+    required: true

dts/bindings/test/vnd,memory-attr.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2020 Linaro Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test memory and memory attributes
+
+compatible: "vnd,memory-attr"
+
+include: [base.yaml, "zephyr,memory-attr.yaml"]

include/zephyr/devicetree.h

@@ -4286,5 +4286,6 @@
 #include <zephyr/devicetree/can.h>
 #include <zephyr/devicetree/reset.h>
 #include <zephyr/devicetree/mbox.h>
+#include <zephyr/devicetree/memory-attr.h>
 
 #endif /* DEVICETREE_H */

include/zephyr/devicetree/memory-attr.h

@@ -0,0 +1,163 @@
+/*
+ * Copyright (c) 2023 Carlo Caione <[email protected]>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_MEMORY_ATTR_H_
+#define ZEPHYR_INCLUDE_MEMORY_ATTR_H_
+
+#include <zephyr/devicetree.h>
+#include <zephyr/linker/devicetree_regions.h>
+#include <zephyr/sys/util.h>
+
+/**
+ * @file
+ * @brief Memory-attr helpers
+ */
+
+/**
+ * @defgroup devicetree-memory-attr Memory attributes
+ * @ingroup devicetree
+ * @{
+ */
+
+/** @cond INTERNAL_HIDDEN */
+
+#define _DT_MEM_ATTR	zephyr_memory_attr
+#define _DT_ATTR(token)	UTIL_CAT(UTIL_CAT(REGION_, token), _ATTR)
+
+#define _UNPACK(node_id, fn)						\
+	fn(COND_CODE_1(DT_NODE_HAS_PROP(node_id, zephyr_memory_region),	\
+		       (LINKER_DT_NODE_REGION_NAME(node_id)),		\
+		       (DT_NODE_FULL_NAME(node_id))),			\
+	   DT_REG_ADDR(node_id),					\
+	   DT_REG_SIZE(node_id),					\
+	   _DT_ATTR(DT_STRING_TOKEN(node_id, _DT_MEM_ATTR))),
+
+#define _APPLY(node_id, fn)					\
+	COND_CODE_1(DT_NODE_HAS_PROP(node_id, _DT_MEM_ATTR),	\
+		    (_UNPACK(node_id, fn)),			\
+		    ())
+
+
+#define _FILTER(node_id, fn)					\
+	COND_CODE_1(DT_NODE_HAS_PROP(node_id, _DT_MEM_ATTR),	\
+		    (fn(node_id)),				\
+		    ())
+
+/** @endcond */
+
+/**
+ * @brief Invokes @p fn for every node in the tree with property
+ *        `zephyr,memory-attr`
+ *
+ * The macro @p fn must take one parameter, which will be a node identifier
+ * with the `zephyr,memory-attr` property. The macro is expanded once for each
+ * node in the tree. The order that nodes are visited in is not specified.
+ *
+ * @param fn macro to invoke
+ */
+#define DT_MEMORY_ATTR_FOREACH_NODE(fn) \
+	DT_FOREACH_STATUS_OKAY_NODE_VARGS(_FILTER, fn)
+
+/**
+ * @brief Invokes @p fn for MPU/MMU regions generation from the device tree
+ *	  nodes with `zephyr,memory-attr` property.
+ *
+ * Helper macro to invoke a @p fn macro on all the memory regions declared
+ * using the `zephyr,memory-attr` property
+ *
+ * The macro @p fn must take the form:
+ *
+ * @code{.c}
+ *   #define MPU_FN(name, base, size, attr) ...
+ * @endcode
+ *
+ * The @p name, @p base and @p size parameters are retrieved from the DT node.
+ * When the `zephyr,memory-region` property is present in the node, the @p name
+ * parameter is retrived from there, otherwise the full node name is used.
+ *
+ * The `zephyr,memory-attr` enum property is passed as an extended token
+ * to the @p fn macro using the @p attr parameter in the form of a macro
+ * REGION_{attr}_ATTR.
+ *
+ * The following enums are supported for the `zephyr,memory-attr` property (see
+ * `zephyr,memory-attr.yaml` for a complete list):
+ *
+ *  - RAM
+ *  - RAM_NOCACHE
+ *  - FLASH
+ *  - PPB
+ *  - IO
+ *  - EXTMEM
+ *
+ * This means that usually the user code would provide some macros or defines
+ * with the same name of the extended property, that is:
+ *
+ *  - REGION_RAM_ATTR
+ *  - REGION_RAM_NOCACHE_ATTR
+ *  - REGION_FLASH_ATTR
+ *  - REGION_PPB_ATTR
+ *  - REGION_IO_ATTR
+ *  - REGION_EXTMEM_ATTR
+ *
+ * Example devicetree fragment:
+ *
+ * @code{.dts}
+ *     / {
+ *             soc {
+ *                     res0: memory@20000000 {
+ *                         reg = <0x20000000 0x4000>;
+ *                         zephyr,memory-region = "MY_NAME";
+ *                         zephyr,memory-attr = "RAM_NOCACHE";
+ *                     };
+ *
+ *                     res1: memory@30000000 {
+ *                         reg = <0x30000000 0x2000>;
+ *                         zephyr,memory-attr = "RAM";
+ *                     };
+
+ *             };
+ *     };
+ * @endcode
+ *
+ * Example usage:
+ *
+ * @code{.c}
+ *   #define REGION_RAM_NOCACHE_ATTR 0xAAAA
+ *   #define REGION_RAM_ATTR         0xBBBB
+ *   #define REGION_FLASH_ATTR       0xCCCC
+ *
+ *   #define MPU_FN(p_name, p_base, p_size, p_attr) \
+ *       {                                          \
+ *           .name = p_name,                        \
+ *           .base = p_base,                        \
+ *           .size = p_size,                        \
+ *           .attr = p_attr,                        \
+ *       }
+ *
+ *   static const struct arm_mpu_region mpu_regions[] = {
+ *       DT_MEMORY_ATTR_APPLY(MPU_FN)
+ *   };
+ * @endcode
+ *
+ * This expands to:
+ *
+ * @code{.c}
+ *   static const struct arm_mpu_region mpu_regions[] = {
+ *       { "MY_NAME",         0x20000000, 0x4000, 0xAAAA },
+ *       { "memory@30000000", 0x30000000, 0x2000, 0xBBBB },
+ *   };
+ * @endcode
+ *
+ * @param fn macro to invoke
+ */
+#define DT_MEMORY_ATTR_APPLY(fn) \
+	DT_FOREACH_STATUS_OKAY_NODE_VARGS(_APPLY, fn)
+
+/**
+ * @}
+ */
+
+#endif /* ZEPHYR_INCLUDE_MEMORY_ATTR_H_ */

tests/lib/devicetree/api/app.overlay

@@ -636,6 +636,19 @@
 			compatible = "vnd,string-array-unquoted";
 			val = "XA XPLUS XB", "XC XPLUS XD", "XA XMINUS XB", "XC XMINUS XD";
 		};
+
+		test_mem_ram: memory@aabbccdd {
+			compatible = "vnd,memory-attr";
+			reg = < 0xaabbccdd 0x4000 >;
+			zephyr,memory-attr = "RAM";
+		};
+
+		test_mem_ram_nocache: memory@44332211 {
+			compatible = "vnd,memory-attr";
+			reg = < 0x44332211 0x2000 >;
+			zephyr,memory-attr = "RAM_NOCACHE";
+		};
+
 	};
 
 	test_64 {

tests/lib/devicetree/api/src/main.c

@@ -2667,6 +2667,70 @@ ZTEST(devicetree_api, test_mbox)
 				  DT_NODELABEL(test_mbox_zero_cell)), "");
 }
 
+ZTEST(devicetree_api, test_memory_attr)
+{
+	#define REGION_RAM_ATTR		(0xDEDE)
+	#define REGION_RAM_NOCACHE_ATTR	(0xCACA)
+
+	#define TEST_FUNC(p_name, p_base, p_size, p_attr)	\
+		{ .name = (p_name),				\
+		  .base = (p_base),				\
+		  .size = (p_size),				\
+		  .attr = (p_attr),				\
+		}
+
+	struct vnd_memory_binding {
+		char *name;
+		uintptr_t base;
+		size_t size;
+		unsigned int attr;
+	};
+
+	struct vnd_memory_binding val_apply[] = {
+		DT_MEMORY_ATTR_APPLY(TEST_FUNC)
+	};
+
+	zassert_true(!strcmp(val_apply[0].name, "memory@aabbccdd"), "");
+	zassert_equal(val_apply[0].base, 0xaabbccdd, "");
+	zassert_equal(val_apply[0].size, 0x4000, "");
+	zassert_equal(val_apply[0].attr, 0xDEDE, "");
+
+	zassert_true(!strcmp(val_apply[1].name, "memory@44332211"), "");
+	zassert_equal(val_apply[1].base, 0x44332211, "");
+	zassert_equal(val_apply[1].size, 0x2000, "");
+	zassert_equal(val_apply[1].attr, 0xCACA, "");
+
+	#undef TEST_FUNC
+	#undef REGION_RAM_ATTR
+	#undef REGION_RAM_NOCACHE_ATTR
+
+	#define TEST_FUNC(node_id) DT_NODE_FULL_NAME(node_id),
+
+	static const char * const val_func[] = {
+		DT_MEMORY_ATTR_FOREACH_NODE(TEST_FUNC)
+	};
+
+	zassert_true(!strcmp(val_func[0], "memory@aabbccdd"), "");
+	zassert_true(!strcmp(val_func[1], "memory@44332211"), "");
+
+	#undef TEST_FUNC
+
+	#define TEST_FUNC(node_id) \
+		COND_CODE_1(DT_ENUM_HAS_VALUE(node_id,			\
+					      zephyr_memory_attr,	\
+					      RAM_NOCACHE),		\
+			    (DT_REG_ADDR(node_id)),			\
+			    ())
+
+	uintptr_t val_filt[] = {
+		DT_MEMORY_ATTR_FOREACH_NODE(TEST_FUNC)
+	};
+
+	zassert_equal(val_filt[0], 0x44332211, "");
+
+	#undef TEST_FUNC
+}
+
 ZTEST(devicetree_api, test_string_token)
 {
 #undef DT_DRV_COMPAT