[RFC PATCH] doc: arch: Add document for RISC-V architecture

[Heinrich Schuchardt]

On 2/12/23 08:00, Yu Chien Peter Lin wrote:
> This patch adds a brief introduction to the RISC-V architecture and
> the typical boot process used on a variety of RISC-V platforms.
>
> Signed-off-by: Yu Chien Peter Lin <peterlin at andestech.com>
> ---
> Hi RISC-V community,
>
> Please leave a comment if there is anything I've missed that should
> be mentioned in the document. Thanks.
> ---
>   doc/arch/index.rst |  1 +
>   doc/arch/riscv.rst | 43 +++++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 44 insertions(+)
>   create mode 100644 doc/arch/riscv.rst
>
> diff --git a/doc/arch/index.rst b/doc/arch/index.rst
> index b3e85f9bf3..b8da4b8c8e 100644
> --- a/doc/arch/index.rst
> +++ b/doc/arch/index.rst
> @@ -11,6 +11,7 @@ Architecture-specific doc
>      m68k
>      mips
>      nios2
> +   riscv
>      sandbox/index
>      sh
>      x86
> diff --git a/doc/arch/riscv.rst b/doc/arch/riscv.rst
> new file mode 100644
> index 0000000000..243e7e7e2e
> --- /dev/null
> +++ b/doc/arch/riscv.rst
> @@ -0,0 +1,43 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (C) 2023, Yu Chien Peter Lin <peterlin at andestech.com>
> +
> +RISC-V
> +======
> +
> +Overview
> +--------
> +
> +This document outlines the U-Boot boot process for the RISC-V architecture.
> +RISC-V is an open-source instruction set architecture (ISA) based on the
> +principles of reduced instruction set computing (RISC). It has been designed
> +to be flexible and customizable, allowing it to be adapted to different use
> +cases, from embedded systems to high performance servers.
> +
> +Typical Boot Process
> +--------------------
> +
> +RISC-V production boot images typically include a U-Boot SPL for platform-specific

%s/typically include/may include/

Many boards don't use SPL:

ae350_rv32_defconfig
ae350_rv64_defconfig
sipeed_maix_bitm_defconfig
sipeed_maix_smode_defconfig
openpiton_riscv64_defconfig
qemu-riscv64_defconfig

Please provide a description of those boot processes too.

> +initialization. The U-Boot SPL then loads a FIT image (u-boot.itb), which contains
> +an SBI (Supervisor Binary Interface) firmware such as `OpenSBI <https://github.com/riscv-software-src/opensbi>`_, as well as a regular

Please, try to stay within 80 columns.

%s/an SBI (Supervisor Binary Interface) firmware/a firmware providing
the SBI (Supervisor Binary Interface)/

> +U-Boot (or U-Boot proper) running in S-mode. Finally, the S-mode Operating System
> +is loaded.
> +
> +In between the boot stages, the hartid is passed through the a0 register, and the
> +start address of the devicetree is passed through the a1 register.
> +
> +The following diagram illustrates the boot process::
> +
> +	<----------( M-mode )--------><-------( S-mode )------>
> +	+------------+   +---------+    +--------+   +--------+
> +	| U-Boot SPL |-->|   SBI   |--->| U-Boot |-->|   OS   |
> +	+------------+   +---------+    +--------+   +--------+

SBI (Supervisory Binary Interface) is an interface not a software. So it
does not fit into this diagram.

Best regards

Heinrich

> +
> +To examine the boot process with the QEMU virt machine, you can follow the steps
> +in the following document:
> +:doc:`../board/emulation/qemu-riscv.rst`
> +
> +Toolchain
> +---------
> +
> +You can build the `RISC-V GNU toolchain <https://github.com/riscv-collab/riscv-gnu-toolchain>`_ from scratch, or download a
> +pre-built toolchain from the `releases page <https://github.com/riscv-collab/riscv-gnu-toolchain/releases>`_.