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

[Anup Patel]

On Thu, Feb 8, 2024 at 8:50 AM Cheng Yang <yangcheng.work at foxmail.com> wrote:
>
> This patch add docs/opensbi_config.md which describes the
> "/chosen/opensbi-config" DT node and properties
>
> Signed-off-by: Cheng Yang <yangcheng.work at foxmail.com>

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

Reviewed-by: Anup Patel <anup at brainfault.org>

Applied this patch to the riscv/opensbi repo.

Thanks,
Anup

> ---
>  docs/opensbi_config.md | 83 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 83 insertions(+)
>  create mode 100644 docs/opensbi_config.md
>
> diff --git a/docs/opensbi_config.md b/docs/opensbi_config.md
> new file mode 100644
> index 0000000..0c42443
> --- /dev/null
> +++ b/docs/opensbi_config.md
> @@ -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
>