Skip to contentSkip to conversation

docs: Add OpenSBI DT configuration guide.

PATCH New Cheng Yang 2 participants 6 messages Feb 8, 2024 – Feb 20, 2024 1 message not in the archive

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): [email protected]

Cheng Yang

author
#1 lore raw

PATCH v3 2/4 docs: Add OpenSBI DT configuration guide.

This patch add docs/opensbi_config.md which describes the "/chosen/opensbi-config" DT node and properties

---
 docs/opensbi_config.md | 83 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 docs/opensbi_config.md
docs/opensbi_config.md new file +83 -0
new file mode 100644
index 0000000..0c42443
@@ -0,0 +1,83 @@
+OpenSBI Device Tree Configuration Guideline
+==================================
+
+Some configurations of OpenSBI's Generic Platform can be described
+in the **device tree (DT) blob** (or flattened device tree) passed
+to the OpenSBI firmwares by the previous booting stage. OpenSBI will
+parse and use these configurations during the boot phase, but delete
+them from the device tree at the end of cold boot.
+
+### OpenSBI Configuration Node
+
+All nodes related to OpenSBI configuration should be under the OpenSBI
+configuration DT node. The **/chosen** DT node is the preferred parent
+of the OpenSBI configuration DT node.
+
+The DT properties of a domain configuration DT node are as follows:
+
+* **compatible** (Mandatory) - The compatible string of the OpenSBI
+  configuration. This DT property should have value *"opensbi,config"*
+
+* **cold-boot-harts** (Optional) - If a platform lacks an override
+  cold_boot_allowed() mechanism, this DT property specifies that a
+  set of harts is permitted to perform a cold boot. Otherwise, all
+  harts are allowed to cold boot.
+
+The OpenSBI Configuration Node will be deleted at the end of cold boot
+(replace the node (subtree) with nop tags).
+
+### Example
+
+```text
+    chosen {
+        opensbi-config {
+            compatible = "opensbi,config";
+            cold-boot-harts = <&cpu1 &cpu2 &cpu3 &cpu4>;
+        };
+    };
+
+    cpus {
+        #address-cells = <1>;
+        #size-cells = <0>;
+        timebase-frequency = <10000000>;
+
+        cpu0: cpu at 0 {
+            device_type = "cpu";
+            reg = <0x00>;
+            compatible = "riscv";
+            ...
+        };
+
+        cpu1: cpu at 1 {
+            device_type = "cpu";
+            reg = <0x01>;
+            compatible = "riscv";
+            ...
+        };
+
+        cpu2: cpu at 2 {
+            device_type = "cpu";
+            reg = <0x02>;
+            compatible = "riscv";
+            ...
+        };
+
+        cpu3: cpu at 3 {
+            device_type = "cpu";
+            reg = <0x03>;
+            compatible = "riscv";
+            ...
+        };
+
+        cpu4: cpu at 4 {
+            device_type = "cpu";
+            reg = <0x04>;
+            compatible = "riscv";
+            ...
+        };
+    };
+
+    uart1: serial at 10011000 {
+        ...
+    };
+```
Signature · 1 line
2.34.1
Applied
#2 lore raw

PATCH v3 2/4 docs: Add OpenSBI DT configuration guide.

Quoted 5 lines · On Thu, Feb 8, 2024 at 8:50?AM Cheng Yang <[email protected]> wrote:

This patch add docs/opensbi_config.md which describes the "/chosen/opensbi-config" DT node and properties

The docs/opensbi_config.md needs to be added to docs/doxygen.cfg otherwise it looks good to me.

Applied this patch to the riscv/opensbi repo.

Thanks,
Anup

Quoted 97 lines
---
 docs/opensbi_config.md | 83 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 docs/opensbi_config.md
docs/opensbi_config.md new file +83 -1
new file mode 100644
index 0000000..0c42443
@@ -0,0 +1,83 @@
+OpenSBI Device Tree Configuration Guideline
+==================================
+
+Some configurations of OpenSBI's Generic Platform can be described
+in the **device tree (DT) blob** (or flattened device tree) passed
+to the OpenSBI firmwares by the previous booting stage. OpenSBI will
+parse and use these configurations during the boot phase, but delete
+them from the device tree at the end of cold boot.
+
+### OpenSBI Configuration Node
+
+All nodes related to OpenSBI configuration should be under the OpenSBI
+configuration DT node. The **/chosen** DT node is the preferred parent
+of the OpenSBI configuration DT node.
+
+The DT properties of a domain configuration DT node are as follows:
+
+* **compatible** (Mandatory) - The compatible string of the OpenSBI
+  configuration. This DT property should have value *"opensbi,config"*
+
+* **cold-boot-harts** (Optional) - If a platform lacks an override
+  cold_boot_allowed() mechanism, this DT property specifies that a
+  set of harts is permitted to perform a cold boot. Otherwise, all
+  harts are allowed to cold boot.
+
+The OpenSBI Configuration Node will be deleted at the end of cold boot
+(replace the node (subtree) with nop tags).
+
+### Example
+
+```text
+    chosen {
+        opensbi-config {
+            compatible = "opensbi,config";
+            cold-boot-harts = <&cpu1 &cpu2 &cpu3 &cpu4>;
+        };
+    };
+
+    cpus {
+        #address-cells = <1>;
+        #size-cells = <0>;
+        timebase-frequency = <10000000>;
+
+        cpu0: cpu at 0 {
+            device_type = "cpu";
+            reg = <0x00>;
+            compatible = "riscv";
+            ...
+        };
+
+        cpu1: cpu at 1 {
+            device_type = "cpu";
+            reg = <0x01>;
+            compatible = "riscv";
+            ...
+        };
+
+        cpu2: cpu at 2 {
+            device_type = "cpu";
+            reg = <0x02>;
+            compatible = "riscv";
+            ...
+        };
+
+        cpu3: cpu at 3 {
+            device_type = "cpu";
+            reg = <0x03>;
+            compatible = "riscv";
+            ...
+        };
+
+        cpu4: cpu at 4 {
+            device_type = "cpu";
+            reg = <0x04>;
+            compatible = "riscv";
+            ...
+        };
+    };
+
+    uart1: serial at 10011000 {
+        ...
+    };
+```
--

2.34.1

author
#3 lore raw

PATCH v3 3/4 platform: generic: Parse system suspend test from config node.

In reply to a message not in the archive

This patch update generic_domains_init() so that "system-suspend-test" is parsed from "/chosen/opensbi-config" DT node.

---
 platform/generic/platform.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
platform/generic/platform.c +1 -1
index 5f76193..407d5b1 100644
@@ -316,7 +316,7 @@ static int generic_domains_init(void)
 
 	if (offset >= 0) {
 		offset = fdt_node_offset_by_compatible(fdt, offset,
-						       "opensbi,domain,config");
+						       "opensbi,config");
 		if (offset >= 0 &&
 		    fdt_get_property(fdt, offset, "system-suspend-test", NULL))
 			sbi_system_suspend_test_enable();
Signature · 1 line
2.34.1
Applied
#4 lore raw

PATCH v3 3/4 platform: generic: Parse system suspend test from config node.

Quoted 5 lines · On Thu, Feb 8, 2024 at 8:50?AM Cheng Yang <[email protected]> wrote:

This patch update generic_domains_init() so that "system-suspend-test" is parsed from "/chosen/opensbi-config" DT node.

LGTM.

Applied this patch to the riscv/opensbi repo.

Thanks,
Anup

Quoted 20 lines
---
 platform/generic/platform.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
platform/generic/platform.c +1 -2
index 5f76193..407d5b1 100644
@@ -316,7 +316,7 @@ static int generic_domains_init(void)
 
        if (offset >= 0) {
                offset = fdt_node_offset_by_compatible(fdt, offset,
-                                                      "opensbi,domain,config");
+                                                      "opensbi,config");
                if (offset >= 0 &&
                    fdt_get_property(fdt, offset, "system-suspend-test", NULL))
                        sbi_system_suspend_test_enable();
--

2.34.1

author
#5 lore raw

PATCH v3 4/4 docs: move documentation of system suspend test.

In reply to a message not in the archive

This patch move documentation of "system-suspend-test" from docs/domain_support.md to docs/opensbi_config.md

---
 docs/domain_support.md | 4 ----
 docs/opensbi_config.md | 4 ++++
 2 files changed, 4 insertions(+), 4 deletions(-)
docs/domain_support.md +0 -4
index b285d65..65b6142 100644
@@ -126,9 +126,6 @@ The DT properties of a domain configuration DT node are as follows:
 * **compatible** (Mandatory) - The compatible string of the domain
   configuration. This DT property should have value *"opensbi,domain,config"*
 
-* **system-suspend-test** (Optional) - When present, enable a system
-  suspend test implementation which simply waits five seconds and issues a WFI.
-
 ### Domain Memory Region Node
 
 The domain memory region DT node describes details of a memory region and
@@ -237,7 +234,6 @@ be done:
     chosen {
         opensbi-domains {
             compatible = "opensbi,domain,config";
-            system-suspend-test;
 
             tmem: tmem {
                 compatible = "opensbi,domain,memregion";
docs/opensbi_config.md +4 -0
index 0c42443..1b710f1 100644
@@ -23,6 +23,9 @@ The DT properties of a domain configuration DT node are as follows:
   set of harts is permitted to perform a cold boot. Otherwise, all
   harts are allowed to cold boot.
 
+* **system-suspend-test** (Optional) - When present, enable a system
+  suspend test implementation which simply waits five seconds and issues a WFI.
+
 The OpenSBI Configuration Node will be deleted at the end of cold boot
 (replace the node (subtree) with nop tags).
 
@@ -33,6 +36,7 @@ The OpenSBI Configuration Node will be deleted at the end of cold boot
         opensbi-config {
             compatible = "opensbi,config";
             cold-boot-harts = <&cpu1 &cpu2 &cpu3 &cpu4>;
+            system-suspend-test;
         };
     };
 
Signature · 1 line
2.34.1
Applied
#6 lore raw

PATCH v3 4/4 docs: move documentation of system suspend test.

Quoted 5 lines · On Thu, Feb 8, 2024 at 8:50?AM Cheng Yang <[email protected]> wrote:

This patch move documentation of "system-suspend-test" from docs/domain_support.md to docs/opensbi_config.md

LGTM.

Applied this patch to the riscv/opensbi repo.

Thanks,
Anup

Quoted 52 lines
---
 docs/domain_support.md | 4 ----
 docs/opensbi_config.md | 4 ++++
 2 files changed, 4 insertions(+), 4 deletions(-)
docs/domain_support.md +0 -4
index b285d65..65b6142 100644
@@ -126,9 +126,6 @@ The DT properties of a domain configuration DT node are as follows:
 * **compatible** (Mandatory) - The compatible string of the domain
   configuration. This DT property should have value *"opensbi,domain,config"*
 
-* **system-suspend-test** (Optional) - When present, enable a system
-  suspend test implementation which simply waits five seconds and issues a WFI.
-
 ### Domain Memory Region Node
 
 The domain memory region DT node describes details of a memory region and
@@ -237,7 +234,6 @@ be done:
     chosen {
         opensbi-domains {
             compatible = "opensbi,domain,config";
-            system-suspend-test;
 
             tmem: tmem {
                 compatible = "opensbi,domain,memregion";
docs/opensbi_config.md +4 -1
index 0c42443..1b710f1 100644
@@ -23,6 +23,9 @@ The DT properties of a domain configuration DT node are as follows:
   set of harts is permitted to perform a cold boot. Otherwise, all
   harts are allowed to cold boot.
 
+* **system-suspend-test** (Optional) - When present, enable a system
+  suspend test implementation which simply waits five seconds and issues a WFI.
+
 The OpenSBI Configuration Node will be deleted at the end of cold boot
 (replace the node (subtree) with nop tags).
 
@@ -33,6 +36,7 @@ The OpenSBI Configuration Node will be deleted at the end of cold boot
         opensbi-config {
             compatible = "opensbi,config";
             cold-boot-harts = <&cpu1 &cpu2 &cpu3 &cpu4>;
+            system-suspend-test;
         };
     };
 
--

2.34.1