doc: arch: Add document for RISC-V architecture

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@andestech.com>
Reviewed-by: Samuel Holland <samuel@sholland.org>
Reviewed-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Rick Chen <rick@andestech.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>

diff --git a/MAINTAINERS b/MAINTAINERS
index 6f53f9c2f6f7bf13bdb4ec3d5cf574d211e04719..41c9f265f815a342b7a754bdbd6e68f7f8d8853a 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1298,6 +1298,7 @@ S:        Maintained
 T:     git https://source.denx.de/u-boot/custodians/u-boot-riscv.git
 F:     arch/riscv/
 F:     cmd/riscv/
+F:     doc/arch/riscv.rst
 F:     doc/usage/sbi.rst
 F:     drivers/sysreset/sysreset_sbi.c
 F:     drivers/timer/andes_plmt_timer.c

diff --git a/doc/arch/index.rst b/doc/arch/index.rst
index b3e85f9bf34753bea37300ccb16410a14bdf147f..b8da4b8c8e5086d1aa932ee9b0c4e2e1a0235eb9 100644 (file)
--- 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 (file)
index 0000000..af0c48b
--- /dev/null
+++ b/doc/arch/riscv.rst
@@ -0,0 +1,81 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (C) 2023, Yu Chien Peter Lin <peterlin@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
+--------------------
+
+U-Boot can run in either M-mode or S-mode, depending on whether it runs before
+the initialization of the firmware providing SBI (Supervisor Binary Interface).
+The firmware is necessary in the RISC-V boot process as it serves as a SEE
+(Supervisor Execution Environment) to handle exceptions for the S-mode U-Boot
+or Operating System.
+
+In between the boot phases, the hartid is passed through the a0 register, and
+the start address of the devicetree is passed through the a1 register.
+
+As a reference, OpenSBI is an SBI implementation that can be used with U-Boot
+in different modes, see the
+`OpenSBI firmware document <https://github.com/riscv-software-src/opensbi/tree/master/docs/firmware>`_
+for more details.
+
+M-mode U-Boot
+^^^^^^^^^^^^^
+
+When running in M-mode U-Boot, it will load the payload image (e.g.
+`fw_payload <https://github.com/riscv-software-src/opensbi/blob/master/docs/firmware/fw_payload.md>`_)
+which contains the firmware and the S-mode Operating System; in this case, you
+can use mkimage to package the payload image into an uImage format, and boot it
+using the bootm command.
+
+The following diagram illustrates the boot process::
+
+       <-----------( M-mode )----------><--( S-mode )-->
+       +----------+   +--------------+    +------------+
+       |  U-Boot  |-->| SBI firmware |--->|     OS     |
+       +----------+   +--------------+    +------------+
+
+To examine the boot process with the QEMU virt machine, you can follow the
+steps in the "Building U-Boot" section of the following document:
+:doc:`../board/emulation/qemu-riscv`.
+
+S-mode U-Boot
+^^^^^^^^^^^^^
+
+RISC-V production boot images may include a U-Boot SPL for platform-specific
+initialization. The U-Boot SPL then loads a FIT image (u-boot.itb), which
+contains a firmware (e.g.
+`fw_dynamic <https://github.com/riscv-software-src/opensbi/blob/master/docs/firmware/fw_dynamic.md>`_)
+providing the SBI, as well as a regular U-Boot (or U-Boot proper) running in
+S-mode. Finally, the S-mode Operating
+System is loaded.
+
+The following diagram illustrates the boot process::
+
+       <-------------( M-mode )----------><----------( S-mode )------->
+       +------------+   +--------------+    +----------+   +----------+
+       | U-Boot SPL |-->| SBI firmware |--->|  U-Boot  |-->|    OS    |
+       +------------+   +--------------+    +----------+   +----------+
+
+To examine the boot process with the QEMU virt machine, you can follow the
+steps in the "Running U-Boot SPL" section of the following document:
+:doc:`../board/emulation/qemu-riscv`.
+
+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>`_.