Add documentation to introduce the Falcon Mode on RISC-V.
In this mode, the boot sequence is SPL -> OpenSBI -> Linux kernel.
Signed-off-by: Randolph
---
doc/develop/falcon.rst | 171 +
1 file changed, 171 insertions(+)
diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst
index 2f25fc8532..65644d1c57 100644
--- a/doc/develop/falcon.rst
+++ b/doc/develop/falcon.rst
@@ -256,3 +256,174 @@ the following command:
Falcon Mode was presented at the RMLL 2012. Slides are available at:
http://schedule2012.rmll.info/IMG/pdf/LSM2012_UbootFalconMode_Babic.pdf
+
+Falcon Mode Boot on RISC-V
+--
+
+Introduction
+
+
+In the RISC-V environment, OpenSBI is required to enable a supervisor mode
+binary to execute certain privileged operations. The typical boot sequence on
+RISC-V is SPL -> OpenSBI -> U-Boot -> Linux kernel. SPL will load and start
+the OpenSBI initializations, then OpenSBI will bring up the next image, U-Boot
+proper. The OpenSBI binary must be prepared in advance of the U-Boot build
+process and it will be packed together with U-Boot into a file called
+u-boot.itb.
+
+The Falcon Mode on RISC-V platforms is a distinct boot sequence. Borrowing
+ideas from the U-Boot Falcon Mode on ARM, it skips the U-Boot proper phase
+in the normal boot process and allows OpenSBI to load and start the Linux
+kernel. Its boot sequence is SPL -> OpenSBI -> Linux kernel. The OpenSBI
+binary and Linux kernel binary must be prepared prior to the U-Boot build
+process and they will be packed together as a FIT image named linux.itb in
+this process.
+
+CONFIG_SPL_LOAD_FIT_OPENSBI_OS_BOOT enables the Falcon Mode boot on RISC-V.
+This configuration setting tells OpenSBI that Linux kernel is its next OS
+image and makes it load and start the kernel afterwards.
+
+Note that the Falcon Mode boot bypasses a lot of initializations by U-Boot.
+If the Linux kernel expects hardware initializations by U-Boot, make sure to
+port the relevant code to the SPL build process.
+
+Configuration
+~
+
+CONFIG_SPL_LOAD_FIT_ADDRESS
+Specifies the address to load u-boot.itb in a normal boot. When the Falcon
+Mode boot is enabled, it specifies the load address of linux.itb.
+
+CONFIG_SYS_TEXT_BASE
+Specifies the address of the text section for a u-boot proper in a normal
+boot. When the Falcon Mode boot is enabled, it specifies the text section
+address for the Linux kernel image.
+
+CONFIG_SPL_PAYLOAD_ARGS_ADDR
+The address in the RAM to which the FDT blob is to be moved by the SPL.
+ SPL places the FDT blob right after the kernel. As the kernel does not
+include the BSS section in its size calculation, SPL ends up placing
+the FDT blob within the BSS section of the kernel. This may cause the
+FDT blob to be cleared during kernel BSS initialization. To avoid the
+issue, be sure to move the FDT blob out of the kernel first.
+
+CONFIG_SPL_LOAD_FIT_OPENSBI_OS_BOOT
+Activates the Falcon Mode boot on RISC-V.
+
+Function that a board must implement
+
+
+Initially, SPL places the FDT blob right after the kernel. As the kernel does
+not include the BSS section in its size calculation, SPL ends up placing the
+FDT blob within the BSS section of the kernel. This may cause the FDT blob to
+be cleared during kernel BSS initialization. To avoid the issue, be sure to
+move the FDT blob out of the kernel first.
+
+void spl_perform_fixups(struct spl_image_info *spl_image)
+required, necessary action to move the FDT blob out of the Linux kernel BSS
+section
+
+Example for Andes AE350 Board
+~
+
+A FDT blob is required to boot the Linux kernel from the SPL. Andes AE350
+platforms generally come with a builtin dtb. If you want to load a custom DTB,
+follow the steps below:
+
+1. Load the custom DTB to SDRAM::
+
+=> fatload mmc 0:1 0x2000 user_custom.dtb
+
+2. Set the SPI speed::
+
+=> sf probe 0:0 5000 0
+
+3. Erase sectors from the SPI Flash::
+
+=> sf erase 0xf 0x1
+
+4. Write the FDT blob to the erased sectors of the Flash::
+
+=> sf write 0x2000 0xf 0x1
+
+Console Log of AE350 Falcon Mode Boot
+~
+
+::
+
+U-Boot SPL 2023.01-00031-g777ecdea66 (Oct 31 2023 - 18:41:36 +0800)
+Trying to boot from RAM
+
+OpenSBI v1.2-51-g7304e42
+ _ _
+ / __ \ / | _ \_ _|
+ | | | |_ __ ___ _ __ | (___ | |_) || |
+ | | | | '_ \ / _ \ '_ \ \___ \| _ < | |
+ | |__| | |_) | __/ | | |) | |_) || |_
+ \/| .__/ \___|_| |_|_/|/_|
+| |
+|_|
+
+Platform Name : andestech,ax25
+Platform Features : medeleg
+Platform HART Count : 1
+Platform
