[PATCH v2 09/11] docs: Add domain device tree binding documentation
Anup Patel
anup.patel at wdc.com
Fri Dec 4 10:52:22 EST 2020
This patch adds domain device tree binding documentation in the
OpenSBI domain support documentation.
Signed-off-by: Anup Patel <anup.patel at wdc.com>
Reviewed-by: Atish Patra <atish.patra at wdc.com>
---
docs/domain_support.md | 208 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 208 insertions(+)
diff --git a/docs/domain_support.md b/docs/domain_support.md
index 04989df..73931f1 100644
--- a/docs/domain_support.md
+++ b/docs/domain_support.md
@@ -104,3 +104,211 @@ Few noteworthy effects of a system partitioned into domains are as follows:
only work if both HART A and HART B are assigned same domain
* A HART running in S-mode or U-mode can only access memory based on the
memory regions of the domain assigned to the HART
+
+Domain Device Tree Bindings
+---------------------------
+
+The OpenSBI domains can be described in the **device tree (DT) blob** (or
+flattened device tree) passed to the OpenSBI firmwares by the previous
+booting stage. This allows OpenSBI platform support to parse and populate
+OpenSBI domains from the device tree blob (or flattened device tree).
+
+### Domain Configuration Node
+
+All OpenSBI domain description related DT nodes should be under the domain
+configuration DT node. The **/chosen** DT node is the preferred parent of
+the domain configuration DT node.
+
+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"*
+
+### Domain Memory Region Node
+
+The domain memory region DT node describes details of a memory region and
+can be pointed by multiple domain instance DT nodes. The access permissions
+of the memory region are specified separately in domain instance node.
+
+The DT properties of a domain memory region DT node are as follows:
+
+* **compatible** (Mandatory) - The compatible string of the domain memory
+ region. This DT property should have value *"opensbi,domain,memregion"*
+* **base** (Mandatory) - The base address of the domain memory region. This
+ DT property should have a **2 ^ order** aligned 64 bit address (i.e. two
+ DT cells).
+* **order** (Mandatory) - The order of the domain memory region. This DT
+ property should have a 32 bit value (i.e. one DT cell) in the range
+ **3 <= order <= __riscv_xlen**.
+* **mmio** (Optional) - A boolean flag representing whether the domain
+ memory region is a memory-mapped I/O (MMIO) region.
+* **devices** (Optional) - The list of device DT node phandles for devices
+ which fall under this domain memory region.
+
+### Domain Instance Node
+
+The domain instance DT node describes set of possible HARTs, set of memory
+regions, and other details of a domain instance.
+
+The DT properties of a domain instance DT node are as follows:
+
+* **compatible** (Mandatory) - The compatible string of the domain instance.
+ This DT property should have value *"opensbi,domain,instance"*
+* **possible-harts** (Optional) - The list of CPU DT node phandles for the
+ the domain instance. This list represents the possible HARTs of the
+ domain instance.
+* **regions** (Optional) - The list of domain memory region DT node phandle
+ and access permissions for the domain instance. Each list entry is a pair
+ of DT node phandle and access permissions. The access permissions are
+ represented as a 32bit bitmask having bits: **readable** (BIT[0]),
+ **writeable** (BIT[1]), **executable** (BIT[2]), and **m-mode** (BIT[3]).
+* **boot-hart** (Optional) - The DT node phandle of the HART booting the
+ domain instance. If coldboot HART is assigned to the domain instance then
+ this DT property is ignored and the coldboot HART is assumed to be the
+ boot HART of the domain instance.
+* **next-arg1** (Optional) - The 64 bit next booting stage arg1 for the
+ domain instance. If this DT property is not available and coldboot HART
+ is not assigned to the domain instance then **0x0** is used as default
+ value. If this DT property is not available and coldboot HART is assigned
+ to the domain instance then **next booting stage arg1 of coldboot HART**
+ is used as default value.
+* **next-addr** (Optional) - The 64 bit next booting stage address for the
+ domain instance. If this DT property is not available and coldboot HART
+ is not assigned to the domain instance then **0x0** is used as default
+ value. If this DT property is not available and coldboot HART is assigned
+ to the domain instance then **next booting stage address of coldboot HART**
+ is used as default value.
+* **next-mode** (Optional) - The 32 bit next booting stage mode for the
+ domain instance. The possible values of this DT property are: **0x1**
+ (s-mode), and **0x0** (u-mode). If this DT property is not available
+ and coldboot HART is not assigned to the domain instance then **0x1**
+ is used as default value. If this DT property is not available and
+ coldboot HART is assigned to the domain instance then **next booting
+ stage mode of coldboot HART** is used as default value.
+* **system-reset-allowed** (Optional) - A boolean flag representing
+ whether the domain instance is allowed to do system reset.
+
+### Assigning HART To Domain Instance
+
+By default, all HARTs are assigned to **the ROOT domain**. The OpenSBI
+platform support can provide the HART to domain instance assignment using
+platform specific callback.
+
+The HART to domain instance assignment can be parsed from the device tree
+using optional DT property **opensbi,domain** in each CPU DT node. The
+value of DT property **opensbi,domain** is the DT phandle of the domain
+instance DT node. If **opensbi,domain** DT property is not specified then
+corresponding HART is assigned to **the ROOT domain**.
+
+### Domain Configuration Only Accessible to OpenSBI
+
+The software running inside a domain instance should only be aware of
+devices and hardware resources accessible to itself.
+
+To hide domain configuration from domain instances, the following should
+be done:
+
+* The previous booting stage should preferably provide a separate device
+ tree for each domain instance and mention location of device tree in
+ respective domain instance DT nodes using **next-arg1** DT property.
+* If domain assigned to a HART does not have separate device tree then
+ OpenSBI platform support should remove all domain configuration details
+ from the device tree passed by previous booting stage before passing it
+ to the next booting stage.
+
+### Example
+
+```
+ chosen {
+ opensbi-domains {
+ compatible = "opensbi,domain,config";
+
+ tmem: tmem {
+ compatible = "opensbi,domain,memregion";
+ base = <0x0 0x80100000>;
+ order = <20>;
+ };
+
+ tuart: tuart {
+ compatible = "opensbi,domain,memregion";
+ base = <0x0 0x10011000>;
+ order = <12>;
+ mmio;
+ devices = <&uart1>;
+ };
+
+ allmem: allmem {
+ compatible = "opensbi,domain,memregion";
+ base = <0x0 0x0>;
+ order = <64>;
+ };
+
+ tdomain: trusted-domain {
+ compatible = "opensbi,domain,instance";
+ possible-harts = <&cpu0>;
+ regions = <&tmem 0x7>, <&tuart 0x7>;
+ boot-hart = <&cpu0>;
+ next-arg1 = <0x0 0x0>;
+ next-addr = <0x0 0x80100000>;
+ next-mode = <0x0>;
+ system-reset-allowed;
+ };
+
+ udomain: untrusted-domain {
+ compatible = "opensbi,domain,instance";
+ possible-harts = <&cpu1 &cpu2 &cpu3 &cpu4>;
+ regions = <&tmem 0x0>, <&tuart 0x0>, <&allmem 0x7>;
+ };
+ };
+ };
+
+ cpus {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ timebase-frequency = <10000000>;
+
+ cpu0: cpu at 0 {
+ device_type = "cpu";
+ reg = <0x00>;
+ compatible = "riscv";
+ opensbi-domain = <&tdomain>;
+ ...
+ };
+
+ cpu1: cpu at 1 {
+ device_type = "cpu";
+ reg = <0x01>;
+ compatible = "riscv";
+ opensbi-domain = <&udomain>;
+ ...
+ };
+
+ cpu2: cpu at 2 {
+ device_type = "cpu";
+ reg = <0x02>;
+ compatible = "riscv";
+ opensbi-domain = <&udomain>;
+ ...
+ };
+
+ cpu3: cpu at 3 {
+ device_type = "cpu";
+ reg = <0x03>;
+ compatible = "riscv";
+ opensbi-domain = <&udomain>;
+ ...
+ };
+
+ cpu4: cpu at 4 {
+ device_type = "cpu";
+ reg = <0x04>;
+ compatible = "riscv";
+ opensbi-domain = <&udomain>;
+ ...
+ };
+ };
+
+ uart1: serial at 10011000 {
+ ...
+ };
+```
--
2.25.1
More information about the opensbi
mailing list