diff mbox series

[V3,1/3] doc: falcon: riscv: Falcon Mode boot on RISC-V

Message ID 20231116130136.2796918-2-randolph@andestech.com
State Changes Requested
Delegated to: Andes
Headers show
Series doc: falcon: riscv: Falcon Mode boot on RISC-V | expand

Commit Message

Randolph Lin Nov. 16, 2023, 1:01 p.m. UTC
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 <randolph@andestech.com>
---
 doc/develop/falcon.rst | 171 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 171 insertions(+)

Comments

Leo Liang Dec. 4, 2023, 1 p.m. UTC | #1
On Thu, Nov 16, 2023 at 09:01:34PM +0800, Randolph wrote:
> 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 <randolph@andestech.com>
> ---
>  doc/develop/falcon.rst | 171 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 171 insertions(+)

Reviewed-by: Leo Yu-Chi Liang <ycliang@andestech.com>
diff mbox series

Patch

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 0x20000000 user_custom.dtb
+
+2. Set the SPI speed::
+
+        => sf probe 0:0 50000000 0
+
+3. Erase sectors from the SPI Flash::
+
+        => sf erase 0xf0000 0x10000
+
+4. Write the FDT blob to the erased sectors of the Flash::
+
+        => sf write 0x20000000 0xf0000 0x10000
+
+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 IPI Device       : andes_plicsw
+        Platform Timer Device     : andes_plmt @ 60000000Hz
+        Platform Console Device   : uart8250
+        Platform HSM Device       : andes_smu
+        Platform PMU Device       : andes_pmu
+        Platform Reboot Device    : atcwdt200
+        Platform Shutdown Device  : ---
+        Firmware Base             : 0x0
+        Firmware Size             : 196 KB
+        Runtime SBI Version       : 1.0
+
+        Domain0 Name              : root
+        Domain0 Boot HART         : 0
+        Domain0 HARTs             : 0*
+        Domain0 Region00          : 0x0000000000000000-0x000000000003ffff ()
+        Domain0 Region01          : 0x00000000e6000000-0x00000000e60fffff (I,R)
+        Domain0 Region02          : 0x00000000e6400000-0x00000000e67fffff (I)
+        Domain0 Region03          : 0x0000000000000000-0xffffffffffffffff (R,W,X)
+        Domain0 Next Address      : 0x0000000001800000
+        Domain0 Next Arg1         : 0x0000000001700000
+        Domain0 Next Mode         : S-mode
+        Domain0 SysReset          : yes
+
+        Boot HART ID              : 0
+        Boot HART Domain          : root
+        Boot HART Priv Version    : v1.11
+        Boot HART Base ISA        : rv64imafdcx
+        Boot HART ISA Extensions  : none
+        Boot HART PMP Count       : 8
+        Boot HART PMP Granularity : 4
+        Boot HART PMP Address Bits: 31
+        Boot HART MHPM Count      : 4
+        Boot HART MHPM Bits       : 64
+        Boot HART MIDELEG         : 0x0000000000000222
+        Boot HART MEDELEG         : 0x000000000000b109
+        [    0.000000] Linux version 6.1.47-09019-g0584b09ad862-dirty
+        [    0.000000] OF: fdt: Ignoring memory range 0x0 - 0x1800000
+        [    0.000000] Machine model: andestech,ax25
+        [    0.000000] earlycon: sbi0 at I/O port 0x0 (options '')
+        [    0.000000] printk: bootconsole [sbi0] enabled
+        [    0.000000] Disabled 4-level and 5-level paging
+        [    0.000000] efi: UEFI not found.
+        [    0.000000] Zone ranges:
+        [    0.000000]   DMA32    [mem 0x0000000001800000-0x000000003fffffff]
+        [    0.000000]   Normal   empty
+        [    0.000000] Movable zone start for each node
+        [    0.000000] Early memory node ranges
+        [    0.000000]   node   0: [mem 0x0000000001800000-0x000000003fffffff]
+        [    0.000000] Initmem setup node 0 [mem 0x0000000001800000-0x000000003fffffff]
+        [    0.000000] SBI specification v1.0 detected
+        [    0.000000] SBI implementation ID=0x1 Version=0x10002
+        [    0.000000] SBI TIME extension detected
+        [    0.000000] SBI IPI extension detected
+        [    0.000000] SBI RFENCE extension detected
+        [    0.000000] SBI SRST extension detected
+        [    0.000000] SBI HSM extension detected
+        [    0.000000] riscv: base ISA extensions acim
+        [    0.000000] riscv: ELF capabilities acim
+        [    0.000000] percpu: Embedded 18 pages/cpu s35000 r8192 d30536 u73728
+        [    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 252500