[PATCH v2 09/11] docs: Add domain device tree binding documentation
Anup Patel
Anup.Patel at wdc.com
Sat Dec 5 04:51:10 EST 2020
> -----Original Message-----
> From: Anup Patel <Anup.Patel at wdc.com>
> Sent: 04 December 2020 21:22
> To: Atish Patra <Atish.Patra at wdc.com>; Alistair Francis
> <Alistair.Francis at wdc.com>
> Cc: Anup Patel <anup at brainfault.org>; opensbi at lists.infradead.org; Anup
> Patel <Anup.Patel at wdc.com>
> Subject: [PATCH v2 09/11] docs: Add domain device tree binding
> documentation
>
> 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
Applied this patch to the riscv/opensbi repo.
Regards,
Anup
More information about the opensbi
mailing list