"Das U-Boot" Source Tree

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>

authored by

Yu Chien Peter Lin and committed by
Heinrich Schuchardt
093ff96e 98382917

+83
+1
MAINTAINERS
··· 1298 1298 T: git https://source.denx.de/u-boot/custodians/u-boot-riscv.git 1299 1299 F: arch/riscv/ 1300 1300 F: cmd/riscv/ 1301 + F: doc/arch/riscv.rst 1301 1302 F: doc/usage/sbi.rst 1302 1303 F: drivers/sysreset/sysreset_sbi.c 1303 1304 F: drivers/timer/andes_plmt_timer.c
+1
doc/arch/index.rst
··· 11 11 m68k 12 12 mips 13 13 nios2 14 + riscv 14 15 sandbox/index 15 16 sh 16 17 x86
+81
doc/arch/riscv.rst
··· 1 + .. SPDX-License-Identifier: GPL-2.0+ 2 + .. Copyright (C) 2023, Yu Chien Peter Lin <peterlin@andestech.com> 3 + 4 + RISC-V 5 + ====== 6 + 7 + Overview 8 + -------- 9 + 10 + This document outlines the U-Boot boot process for the RISC-V architecture. 11 + RISC-V is an open-source instruction set architecture (ISA) based on the 12 + principles of reduced instruction set computing (RISC). It has been designed 13 + to be flexible and customizable, allowing it to be adapted to different use 14 + cases, from embedded systems to high performance servers. 15 + 16 + Typical Boot Process 17 + -------------------- 18 + 19 + U-Boot can run in either M-mode or S-mode, depending on whether it runs before 20 + the initialization of the firmware providing SBI (Supervisor Binary Interface). 21 + The firmware is necessary in the RISC-V boot process as it serves as a SEE 22 + (Supervisor Execution Environment) to handle exceptions for the S-mode U-Boot 23 + or Operating System. 24 + 25 + In between the boot phases, the hartid is passed through the a0 register, and 26 + the start address of the devicetree is passed through the a1 register. 27 + 28 + As a reference, OpenSBI is an SBI implementation that can be used with U-Boot 29 + in different modes, see the 30 + `OpenSBI firmware document <https://github.com/riscv-software-src/opensbi/tree/master/docs/firmware>`_ 31 + for more details. 32 + 33 + M-mode U-Boot 34 + ^^^^^^^^^^^^^ 35 + 36 + When running in M-mode U-Boot, it will load the payload image (e.g. 37 + `fw_payload <https://github.com/riscv-software-src/opensbi/blob/master/docs/firmware/fw_payload.md>`_) 38 + which contains the firmware and the S-mode Operating System; in this case, you 39 + can use mkimage to package the payload image into an uImage format, and boot it 40 + using the bootm command. 41 + 42 + The following diagram illustrates the boot process:: 43 + 44 + <-----------( M-mode )----------><--( S-mode )--> 45 + +----------+ +--------------+ +------------+ 46 + | U-Boot |-->| SBI firmware |--->| OS | 47 + +----------+ +--------------+ +------------+ 48 + 49 + To examine the boot process with the QEMU virt machine, you can follow the 50 + steps in the "Building U-Boot" section of the following document: 51 + :doc:`../board/emulation/qemu-riscv`. 52 + 53 + S-mode U-Boot 54 + ^^^^^^^^^^^^^ 55 + 56 + RISC-V production boot images may include a U-Boot SPL for platform-specific 57 + initialization. The U-Boot SPL then loads a FIT image (u-boot.itb), which 58 + contains a firmware (e.g. 59 + `fw_dynamic <https://github.com/riscv-software-src/opensbi/blob/master/docs/firmware/fw_dynamic.md>`_) 60 + providing the SBI, as well as a regular U-Boot (or U-Boot proper) running in 61 + S-mode. Finally, the S-mode Operating 62 + System is loaded. 63 + 64 + The following diagram illustrates the boot process:: 65 + 66 + <-------------( M-mode )----------><----------( S-mode )-------> 67 + +------------+ +--------------+ +----------+ +----------+ 68 + | U-Boot SPL |-->| SBI firmware |--->| U-Boot |-->| OS | 69 + +------------+ +--------------+ +----------+ +----------+ 70 + 71 + To examine the boot process with the QEMU virt machine, you can follow the 72 + steps in the "Running U-Boot SPL" section of the following document: 73 + :doc:`../board/emulation/qemu-riscv`. 74 + 75 + Toolchain 76 + --------- 77 + 78 + You can build the 79 + `RISC-V GNU toolchain <https://github.com/riscv-collab/riscv-gnu-toolchain>`_ 80 + from scratch, or download a pre-built toolchain from the 81 + `releases page <https://github.com/riscv-collab/riscv-gnu-toolchain/releases>`_.