[PATCH V2] doc: falcon: riscv: Falcon Mode boot on RISC-V

Sun Nov 5 05:12:25 CET 2023

On 11/2/23 13:10, 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 at andestech.com>
> ---
>   doc/develop/falcon.rst | 159 +++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 159 insertions(+)
> 
> diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst
> index 2f25fc8532..b553f0d0ea 100644
> --- a/doc/develop/falcon.rst
> +++ b/doc/develop/falcon.rst
> @@ -256,3 +256,162 @@ 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
> +------------

Thank you for documenting this.

In HTML we want this to be a <h3></h3> title.

The underscore type controls the title level. Please, use
    ~~~~~~~~~~~~
for the underline. Same below.

> +
> +In the RISC-V environment, OpenSBI is required to enable a supervisor mode

%s/mode/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.

%s/U-Boot/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 process. Borrowing

%s/processs/sequence/

> +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 linux.itb in this process.

%s/linux.itb/a FIT image named linux.itb/

> +
> +CONFIG_SPL_LOAD_FIT_OPENSBI_OS_BOOT enables the Falcon Mode boot on RISC-V.
> +This configuration tells OpenSBI that Linux kernel is its next OS image and

%s/configuration/configuration setting/

> +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.
> +
> +Configurations

%s/Configurations/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_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

Shouldn't we have a generic function for this? Why should we want 
duplicate code?

> +
> +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
> +-------------------------------------
> +

Please, indent following log and precede it by '::'

Best regards

Heinrich

> +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