[PATCH V2] doc: falcon: riscv: Falcon Mode boot on RISC-V
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 | 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 +------------ + +In the RISC-V environment, OpenSBI is required to enable a supervisor mode +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. +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 +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. + +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 +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 +-------------- + +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 + +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
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@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
participants (2)
-
Heinrich Schuchardt -
Randolph