dts: bindings: Update Nordic owned memory bindings

57300 · 57300 · commit a0719f275ec6 · 2024-10-09T19:54:33.000+02:00
This concerns both `nordic,owned-memory` and `nordic,owned-partitions`.

Introduce a property named `nordic,access`, which is meant to replace
the `owner-id` and `perm-*` properties. It allows for describing how
multiple domains should access a single memory region, possibly with
different permissions per owner, but without having to create more than
one DT node for this purpose.

This change is also motivated by updated memory protection requirements
on the nRF54H20, which mandate that a given memory region must only be
reserved by one domain, even if multiple domains can have access to it.
This restriction is now described in the binding itself.

Signed-off-by: Grzegorz Swiderski &lt;grzegorz.swiderski@nordicsemi.no&gt;
diff --git a/dts/bindings/mtd/nordic,owned-partitions.yaml b/dts/bindings/mtd/nordic,owned-partitions.yaml
@@ -24,8 +24,7 @@ description: |
 
         rx-partitions {
             compatible = "nordic,owned-partitions";
-            perm-read;
-            perm-execute;
+            nordic,access = <NRF_OWNER_ID_APPLICATION NRF_PERM_RX>;
             #address-cells = <1>;
             #size-cells = <1>;
 
@@ -37,8 +36,7 @@ description: |
 
         rw-partitions {
             compatible = "nordic,owned-partitions";
-            perm-read;
-            perm-write;
+            nordic,access = <NRF_OWNER_ID_APPLICATION NRF_PERM_RW>;
             #address-cells = <1>;
             #size-cells = <1>;
 
diff --git a/dts/bindings/reserved-memory/nordic,owned-memory.yaml b/dts/bindings/reserved-memory/nordic,owned-memory.yaml
@@ -8,17 +8,64 @@ description: |
   will be recorded in the UICR of the compiled domain. Memory ownership and
   access is then configured for the domain at boot time, based on the UICR.
 
+  Example:
+
+    reserved-memory {
+        memory@2fc00000 {
+            compatible = "nordic,owned-memory";
+            reg = <0x2fc00000 0x1000>;
+            status = "okay";
+            nordic,access = <NRF_OWNER_ID_APPLICATION NRF_PERM_R>,
+                            <NRF_OWNER_ID_RADIOCORE NRF_PERM_W>;
+        };
+    };
+
+  A single local domain can request a memory region to be reserved on behalf of
+  multiple access owners. A single memory region shall be reserved by at most
+  one domain, by setting status "okay" on the associated node. For example, if
+  the region defined above is enabled by Application on behalf of Radiocore,
+  then the Radiocore's devicetree must set status "disabled" on that node.
+
+  Each of the different owners may have a different set of permissions granted,
+  as also shown above.
+
+  Note: one domain can also reserve memory for another domain and not itself.
+  Whichever domain has status "okay" set on the node does not need to be listed
+  as one of the access owners.
+
 compatible: "nordic,owned-memory"
 
-include: base.yaml
+include: [base.yaml, "zephyr,memory-common.yaml"]
 
 properties:
   reg:
     required: true
 
+  nordic,access:
+    type: array
+    description: |
+      Array of (owner-id, permission-flags) pairs, where:
+
+      - Owner ID represents the domain that will have access to this memory.
+        Valid values can be found in dts/common/nordic/<soc>.dtsi,
+        where they are defined as NRF_OWNER_ID_*
+
+      - Permissions are encoded as a 32-bit bitfield, using the flags found in
+        include/zephyr/dt-bindings/reserved-memory/nordic-owned-memory.h,
+        where they are defined as NRF_PERM_*
+
+        The same file defines all possible permission flag combinations.
+        For example, one can use:
+          <NRF_OWNER_ID_APPLICATION NRF_PERM_RWX>
+
+        as a shorthand for:
+          <NRF_OWNER_ID_APPLICATION (NRF_PERM_R | NRF_PERM_W | NRF_PERM_X)>
+
   owner-id:
     type: int
+    deprecated: true
     description: |
+      Deprecated, applies only if 'nordic,access' is not defined.
       Owner ID of the domain that will own this memory region. If not defined,
       the ownership will default to the domain being compiled.
 
@@ -27,20 +74,35 @@ properties:
 
   perm-read:
     type: boolean
-    description: Owner has read access to the region.
+    deprecated: true
+    description: |
+      Deprecated, applies only if 'nordic,access' is not defined.
+      Owner has read access to the region.
 
   perm-write:
     type: boolean
-    description: Owner has write access to the region.
+    deprecated: true
+    description: |
+      Deprecated, applies only if 'nordic,access' is not defined.
+      Owner has write access to the region.
 
   perm-execute:
     type: boolean
-    description: Owner can execute code from the region.
+    deprecated: true
+    description: |
+      Deprecated, applies only if 'nordic,access' is not defined.
+      Owner can execute code from the region.
 
   perm-secure:
     type: boolean
-    description: Owner has secure-only access to the region.
+    deprecated: true
+    description: |
+      Deprecated, applies only if 'nordic,access' is not defined.
+      Owner has secure-only access to the region.
 
   non-secure-callable:
     type: boolean
-    description: Memory region is used for non-secure-callable code.
+    deprecated: true
+    description: |
+      Deprecated, applies only if 'nordic,access' is not defined.
+      Memory region is used for non-secure-callable code.
diff --git a/dts/common/nordic/nrf54h20.dtsi b/dts/common/nordic/nrf54h20.dtsi
@@ -11,6 +11,7 @@
 #include <zephyr/dt-bindings/misc/nordic-domain-id-nrf54h20.h>
 #include <zephyr/dt-bindings/misc/nordic-owner-id-nrf54h20.h>
 #include <zephyr/dt-bindings/misc/nordic-tddconf.h>
+#include <zephyr/dt-bindings/reserved-memory/nordic-owned-memory.h>
 
 /delete-node/ &sw_pwm;
 
diff --git a/dts/common/nordic/nrf9280.dtsi b/dts/common/nordic/nrf9280.dtsi
@@ -10,6 +10,7 @@
 #include <zephyr/dt-bindings/misc/nordic-nrf-ficr-nrf9230-engb.h>
 #include <zephyr/dt-bindings/misc/nordic-domain-id-nrf9230.h>
 #include <zephyr/dt-bindings/misc/nordic-owner-id-nrf9230.h>
+#include <zephyr/dt-bindings/reserved-memory/nordic-owned-memory.h>
 
 /delete-node/ &sw_pwm;
 
diff --git a/include/zephyr/dt-bindings/reserved-memory/nordic-owned-memory.h b/include/zephyr/dt-bindings/reserved-memory/nordic-owned-memory.h
@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DT_BINDINGS_RESERVED_MEMORY_NORDIC_OWNED_MEMORY_H_
+#define ZEPHYR_INCLUDE_DT_BINDINGS_RESERVED_MEMORY_NORDIC_OWNED_MEMORY_H_
+
+#include <zephyr/dt-bindings/dt-util.h>
+
+/**
+ * @name Basic memory permission flags.
+ * @{
+ */
+
+/** Readable. */
+#define NRF_PERM_R BIT(0)
+/** Writable. */
+#define NRF_PERM_W BIT(1)
+/** Executable. */
+#define NRF_PERM_X BIT(2)
+/** Secure-only. */
+#define NRF_PERM_S BIT(3)
+/** Non-secure-callable. */
+#define NRF_PERM_NSC BIT(4)
+
+/**
+ * @}
+ */
+
+/**
+ * @name Memory permission flag combinations.
+ * @note NRF_PERM_NSC overrides all other flags, so it is not included here.
+ * @{
+ */
+
+#define NRF_PERM_RW   (NRF_PERM_R | NRF_PERM_W)
+#define NRF_PERM_RX   (NRF_PERM_R | NRF_PERM_X)
+#define NRF_PERM_RS   (NRF_PERM_R | NRF_PERM_S)
+#define NRF_PERM_WX   (NRF_PERM_W | NRF_PERM_X)
+#define NRF_PERM_WS   (NRF_PERM_W | NRF_PERM_S)
+#define NRF_PERM_XS   (NRF_PERM_X | NRF_PERM_S)
+#define NRF_PERM_RWX  (NRF_PERM_R | NRF_PERM_W | NRF_PERM_X)
+#define NRF_PERM_RWS  (NRF_PERM_R | NRF_PERM_W | NRF_PERM_S)
+#define NRF_PERM_RXS  (NRF_PERM_R | NRF_PERM_X | NRF_PERM_S)
+#define NRF_PERM_WXS  (NRF_PERM_W | NRF_PERM_X | NRF_PERM_S)
+#define NRF_PERM_RWXS (NRF_PERM_R | NRF_PERM_W | NRF_PERM_X | NRF_PERM_S)
+
+/**
+ * @}
+ */
+
+#endif /* ZEPHYR_INCLUDE_DT_BINDINGS_RESERVED_MEMORY_NORDIC_OWNED_MEMORY_H_ */
