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