From 8ba1fd7ddc8e5aab6f128c1c72ff13740416b2a7 Mon Sep 17 00:00:00 2001 From: Carlo Caione Date: Wed, 5 Jul 2023 15:10:32 +0200 Subject: [PATCH] devicetree: Add 'zephyr,memory-attr' and DT helpers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- doc/build/dts/api/api.rst | 9 ++ dts/bindings/base/zephyr,memory-attr.yaml | 18 +++ dts/bindings/test/vnd,memory-attr.yaml | 8 ++ include/zephyr/devicetree.h | 1 + include/zephyr/devicetree/memory-attr.h | 162 ++++++++++++++++++++++ tests/lib/devicetree/api/app.overlay | 13 ++ tests/lib/devicetree/api/src/main.c | 64 +++++++++ 7 files changed, 275 insertions(+) create mode 100644 dts/bindings/base/zephyr,memory-attr.yaml create mode 100644 dts/bindings/test/vnd,memory-attr.yaml create mode 100644 include/zephyr/devicetree/memory-attr.h diff --git a/doc/build/dts/api/api.rst b/doc/build/dts/api/api.rst index 7d802838041d3ee..bdf213268fc350c 100644 --- a/doc/build/dts/api/api.rst +++ b/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) diff --git a/dts/bindings/base/zephyr,memory-attr.yaml b/dts/bindings/base/zephyr,memory-attr.yaml new file mode 100644 index 000000000000000..53a4ffec33b56e3 --- /dev/null +++ b/dts/bindings/base/zephyr,memory-attr.yaml @@ -0,0 +1,18 @@ +# Copyright (c) 2023, Carlo Caione +# SPDX-License-Identifier: Apache-2.0 + +properties: + zephyr,memory-attr: + type: string + enum: + - "RAM" + - "RAM_NOCACHE" + - "FLASH" + - "PPB" + - "IO" + - "EXTMEM" + description: | + Attribute for the memory region. + + reg: + required: true diff --git a/dts/bindings/test/vnd,memory-attr.yaml b/dts/bindings/test/vnd,memory-attr.yaml new file mode 100644 index 000000000000000..0303d255c54724e --- /dev/null +++ b/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"] diff --git a/include/zephyr/devicetree.h b/include/zephyr/devicetree.h index 94ab5b8d3adafe0..ff0ecb0a33f5674 100644 --- a/include/zephyr/devicetree.h +++ b/include/zephyr/devicetree.h @@ -4286,5 +4286,6 @@ #include #include #include +#include #endif /* DEVICETREE_H */ diff --git a/include/zephyr/devicetree/memory-attr.h b/include/zephyr/devicetree/memory-attr.h new file mode 100644 index 000000000000000..e67d4b39cd3b52e --- /dev/null +++ b/include/zephyr/devicetree/memory-attr.h @@ -0,0 +1,162 @@ +/* + * Copyright (c) 2023 Carlo Caione + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#ifndef ZEPHYR_INCLUDE_MEMORY_ATTR_H_ +#define ZEPHYR_INCLUDE_MEMORY_ATTR_H_ + +#include +#include + +/** + * @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_MEM_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_ */ diff --git a/tests/lib/devicetree/api/app.overlay b/tests/lib/devicetree/api/app.overlay index 03fd7765570dffe..446fcfc2029685b 100644 --- a/tests/lib/devicetree/api/app.overlay +++ b/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 { diff --git a/tests/lib/devicetree/api/src/main.c b/tests/lib/devicetree/api/src/main.c index eb96de5a81dbfe6..adeee59bf1f2db4 100644 --- a/tests/lib/devicetree/api/src/main.c +++ b/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