From 8c8153ead2bbcb2a62de1adcc115da851ae5e3a0 Mon Sep 17 00:00:00 2001 From: Yu Chien Peter Lin Date: Sun, 12 Feb 2023 15:09:51 +0800 Subject: doc: devicetree: dt_qemu.rst: Fix the typo and space Fix typo and whitespace in the document. Signed-off-by: Yu Chien Peter Lin Reviewed-by: Heinrich Schuchardt --- doc/develop/devicetree/dt_qemu.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/develop/devicetree/dt_qemu.rst b/doc/develop/devicetree/dt_qemu.rst index c25c4fb053d..8ba2b225590 100644 --- a/doc/develop/devicetree/dt_qemu.rst +++ b/doc/develop/devicetree/dt_qemu.rst @@ -13,7 +13,7 @@ When `CONFIG_OF_BOARD` is enabled Obtaining the QEMU devicetree ----------------------------- -Where QEMU generates its own devicetree to pass to U-Boot tou can use +Where QEMU generates its own devicetree to pass to U-Boot you can use `-dtb u-boot.dtb` to force QEMU to use U-Boot's in-tree version. To obtain the devicetree that qemu generates, add `-machine dumpdtb=qemu.dtb`, @@ -38,7 +38,7 @@ to produce a text file. It drops the duplicate header on the qemu one. Then it joins them up and runs them through dtc to compile the output:: qemu-system-arm -machine virt -machine dumpdtb=qemu.dtb - cat <(dtc -I dtb qemu.dtb) <(dtc -I dtb u-boot.dtb |grep -v /dts-v1/) |dtc - -o merged.dtb + cat <(dtc -I dtb qemu.dtb) <(dtc -I dtb u-boot.dtb | grep -v /dts-v1/) | dtc - -o merged.dtb You can then run qemu with the merged devicetree, e.g.:: -- cgit v1.3.1 From 34a1fee7565e46795c8f8404a0be68e928c1e63c Mon Sep 17 00:00:00 2001 From: Thomas Fitzsimmons Date: Mon, 13 Feb 2023 11:21:27 -0500 Subject: doc: board: bcm7xxx: Convert to reStructuredText format Convert the documentation for the Broadcom BCM7445 and BCM7260 boards to reStructuredText format and add the new filename to doc/board/broadcom/index.rst. Signed-off-by: Heinrich Schuchardt --- doc/README.bcm7xxx | 156 ----------------------------------- doc/board/broadcom/bcm7xxx.rst | 183 +++++++++++++++++++++++++++++++++++++++++ doc/board/broadcom/index.rst | 1 + 3 files changed, 184 insertions(+), 156 deletions(-) delete mode 100644 doc/README.bcm7xxx create mode 100644 doc/board/broadcom/bcm7xxx.rst diff --git a/doc/README.bcm7xxx b/doc/README.bcm7xxx deleted file mode 100644 index 6839da5f974..00000000000 --- a/doc/README.bcm7xxx +++ /dev/null @@ -1,156 +0,0 @@ -Summary -======= - -This document describes how to use U-Boot on the Broadcom 7445 SoC, as -a third stage bootloader loaded by Broadcom's BOLT bootloader. - -BOLT loads U-Boot as a generic ELF binary. Some U-Boot features such -as networking are not yet available but other important features are, -including: - - - ext4 file system traversal - - - support for loading FIT images - - - advanced scripting - - - support for FIT-provided DTBs instead of relying on the - BOLT-provided DTB - -A customized version of this port has been used in production. The -same approach may work on other BCM7xxx boards, with some -configuration adjustments and memory layout experimentation. - -Build -===== - -make bcm7445_defconfig -make -${CROSS_COMPILE}strip u-boot - -Run -=== - -To tell U-Boot which serial port to use for its console, set the -"stdout-path" property in the "/chosen" node of the BOLT-generated -device tree. For example: - -BOLT> dt add prop chosen stdout-path s serial0:115200n8 - -Flash the u-boot binary into board storage, then invoke it from BOLT. -For example: - -BOLT> boot -bsu -elf flash0.u-boot1 - -This port assumes that I-cache and D-cache are already enabled when -U-Boot is entered. - -Flattened Image Tree Support -============================ - -What follows is an example FIT image source file. Build it with: - -mkimage -f image.its image.itb - -Booting the resulting image.itb was tested on BOLT v1.20, with the -following kernels: - -https://github.com/Broadcom/stblinux-3.14 -https://github.com/Broadcom/stblinux-4.1 -https://github.com/Broadcom/stblinux-4.9 - -and with a generic ARMv7 root file system. - -image.its: -/dts-v1/; -/ { - description = "BCM7445 FIT"; - images { - kernel@1 { - description = "Linux kernel"; - /* - * This kernel image output format can be - * generated with: - * - * make vmlinux - * ${CROSS_COMPILE}objcopy -O binary -S vmlinux vmlinux.bin - * gzip -9 vmlinux.bin - * - * For stblinux-3.14, the specific Broadcom - * board type should be configured in the - * kernel, for example CONFIG_BCM7445D0=y. - */ - data = /incbin/(""); - type = "kernel"; - arch = "arm"; - os = "linux"; - compression = "gzip"; - load = <0x8000>; - entry = <0x8000>; - hash@1 { - algo = "sha256"; - }; - }; - ramdisk@1 { - description = "Initramfs root file system"; - data = /incbin/(""); - type = "ramdisk"; - arch = "arm"; - os = "linux"; - compression = "gzip"; - /* - * Set the environment variable initrd_high to - * 0xffffffff, and set "load" and "entry" here - * to 0x0 to keep initramfs in-place and to - * accommodate stblinux bmem/CMA reservations. - */ - load = <0x0>; - entry = <0x0>; - hash@1 { - algo = "sha256"; - }; - }; - fdt@1 { - description = "Device tree dumped from BOLT"; - /* - * This DTB should be similar to the - * BOLT-generated device tree, after BOLT has - * done its runtime modifications to it. For - * example, it can be dumped from within - * U-Boot (at ${fdtcontroladdr}), after BOLT - * has loaded U-Boot. The result can be added - * to the Linux source tree as a .dts file. - * - * To support modifications to the device tree - * in-place in U-Boot, add to Linux's - * arch/arm/boot/dts/Makefile: - * - * DTC_FLAGS ?= -p 4096 - * - * This will leave some padding in the DTB and - * thus reserve room for node additions. - * - * Also, set the environment variable fdt_high - * to 0xffffffff to keep the DTB in-place and - * to accommodate stblinux bmem/CMA - * reservations. - */ - data = /incbin/(".dtb"); - type = "flat_dt"; - arch = "arm"; - compression = "none"; - hash@1 { - algo = "sha256"; - }; - }; - }; - configurations { - default = "conf@bcm7445"; - conf@bcm7445 { - description = "BCM7445 configuration"; - kernel = "kernel@1"; - ramdisk = "ramdisk@1"; - fdt = "fdt@1"; - }; - }; -}; diff --git a/doc/board/broadcom/bcm7xxx.rst b/doc/board/broadcom/bcm7xxx.rst new file mode 100644 index 00000000000..f1994d9f975 --- /dev/null +++ b/doc/board/broadcom/bcm7xxx.rst @@ -0,0 +1,183 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2018, 2023 Thomas Fitzsimmons + +BCM7445 and BCM7260 +=================== + +This document describes how to use U-Boot on the Broadcom 7445 and +Broadcom 7260 SoC, as a third stage bootloader loaded by Broadcom's +BOLT bootloader. + +BOLT loads U-Boot as a generic ELF binary. Some U-Boot features such +as networking are not implemented but other important features are, +including: + +* ext4 file system traversal +* support for loading FIT images +* advanced scripting +* support for FIT-provided DTBs instead of relying on the BOLT-provided DTB + +A customized version of this port has been used in production. The +same approach may work on other BCM7xxx boards, with some +configuration adjustments and memory layout experimentation. + +Configure +--------- + +BCM7445 +^^^^^^^ + +.. code-block:: console + + $ make bcm7445_defconfig + +BCM7260 +^^^^^^^ + +.. code-block:: console + + $ make bcm7260_defconfig + +Build +----- + +.. code-block:: console + + $ make + $ ${CROSS_COMPILE}strip u-boot + +Run +--- + +To tell U-Boot which serial port to use for its console, set the +``stdout-path`` property in the ``/chosen`` node of the BOLT-generated +device tree. For example: + +:: + + BOLT> dt add prop chosen stdout-path s serial0:115200n8 + +Flash the ``u-boot`` binary into board storage, then invoke it from +BOLT. For example: + +:: + + BOLT> boot -bsu -elf flash0.u-boot1 + +This port assumes that I-cache and D-cache are already enabled when +U-Boot is entered. + +Flattened Image Tree Support +---------------------------- + +What follows is an example FIT image source file. Build it with: + +.. code-block:: console + + $ mkimage -f image.its image.itb + +Booting the resulting ``image.itb`` was tested on BOLT v1.20, with the +following kernels: + +* https://github.com/Broadcom/stblinux-3.14 +* https://github.com/Broadcom/stblinux-4.1 +* https://github.com/Broadcom/stblinux-4.9 + +and with a generic ARMv7 root file system. + +**image.its** + +:: + + /dts-v1/; + / { + description = "BCM7445 FIT"; + images { + kernel@1 { + description = "Linux kernel"; + /* + * This kernel image output format can be + * generated with: + * + * make vmlinux + * ${CROSS_COMPILE}objcopy -O binary -S vmlinux vmlinux.bin + * gzip -9 vmlinux.bin + * + * For stblinux-3.14, the specific Broadcom + * board type should be configured in the + * kernel, for example CONFIG_BCM7445D0=y. + */ + data = /incbin/(""); + type = "kernel"; + arch = "arm"; + os = "linux"; + compression = "gzip"; + load = <0x8000>; + entry = <0x8000>; + hash@1 { + algo = "sha256"; + }; + }; + ramdisk@1 { + description = "Initramfs root file system"; + data = /incbin/(""); + type = "ramdisk"; + arch = "arm"; + os = "linux"; + compression = "gzip"; + /* + * Set the environment variable initrd_high to + * 0xffffffff, and set "load" and "entry" here + * to 0x0 to keep initramfs in-place and to + * accommodate stblinux bmem/CMA reservations. + */ + load = <0x0>; + entry = <0x0>; + hash@1 { + algo = "sha256"; + }; + }; + fdt@1 { + description = "Device tree dumped from BOLT"; + /* + * This DTB should be similar to the + * BOLT-generated device tree, after BOLT has + * done its runtime modifications to it. For + * example, it can be dumped from within + * U-Boot (at ${fdtcontroladdr}), after BOLT + * has loaded U-Boot. The result can be added + * to the Linux source tree as a .dts file. + * + * To support modifications to the device tree + * in-place in U-Boot, add to Linux's + * arch/arm/boot/dts/Makefile: + * + * DTC_FLAGS ?= -p 4096 + * + * This will leave some padding in the DTB and + * thus reserve room for node additions. + * + * Also, set the environment variable fdt_high + * to 0xffffffff to keep the DTB in-place and + * to accommodate stblinux bmem/CMA + * reservations. + */ + data = /incbin/(".dtb"); + type = "flat_dt"; + arch = "arm"; + compression = "none"; + hash@1 { + algo = "sha256"; + }; + }; + }; + configurations { + default = "conf@bcm7445"; + conf@bcm7445 { + description = "BCM7445 configuration"; + kernel = "kernel@1"; + ramdisk = "ramdisk@1"; + fdt = "fdt@1"; + }; + }; + }; diff --git a/doc/board/broadcom/index.rst b/doc/board/broadcom/index.rst index 4f0e825fef9..a56bd1f0692 100644 --- a/doc/board/broadcom/index.rst +++ b/doc/board/broadcom/index.rst @@ -7,4 +7,5 @@ Broadcom .. toctree:: :maxdepth: 2 + bcm7xxx raspberrypi -- cgit v1.3.1 From 98382917d7924435f354567def119e55e84e2ba3 Mon Sep 17 00:00:00 2001 From: Tim Harvey Date: Mon, 13 Feb 2023 09:44:27 -0800 Subject: board: gateworks: venice: move README to RST Move board/gateworks/venice/README to RST documentation. Signed-off-by: Tim Harvey --- board/gateworks/venice/MAINTAINERS | 1 + board/gateworks/venice/README | 35 ------------------------ doc/board/gateworks/imx8mm_venice.rst | 50 +++++++++++++++++++++++++++++++++++ doc/board/gateworks/imx8mn_venice.rst | 50 +++++++++++++++++++++++++++++++++++ doc/board/gateworks/imx8mp_venice.rst | 50 +++++++++++++++++++++++++++++++++++ doc/board/gateworks/index.rst | 11 ++++++++ doc/board/index.rst | 1 + 7 files changed, 163 insertions(+), 35 deletions(-) delete mode 100644 board/gateworks/venice/README create mode 100644 doc/board/gateworks/imx8mm_venice.rst create mode 100644 doc/board/gateworks/imx8mn_venice.rst create mode 100644 doc/board/gateworks/imx8mp_venice.rst create mode 100644 doc/board/gateworks/index.rst diff --git a/board/gateworks/venice/MAINTAINERS b/board/gateworks/venice/MAINTAINERS index cfdea0cb8ad..01a47a15d6f 100644 --- a/board/gateworks/venice/MAINTAINERS +++ b/board/gateworks/venice/MAINTAINERS @@ -3,5 +3,6 @@ M: Tim Harvey S: Maintained F: arch/arm/dts/imx8m*-venice* F: board/gateworks/venice/ +F: doc/board/gateworks/*venice* F: include/configs/imx8m*_venice.h F: configs/imx8m*_venice_defconfig diff --git a/board/gateworks/venice/README b/board/gateworks/venice/README deleted file mode 100644 index ea9b8348a7d..00000000000 --- a/board/gateworks/venice/README +++ /dev/null @@ -1,35 +0,0 @@ -U-Boot for the Gateworks i.MX8M Mini Venice Development Kit boards - -Quick Start -=========== -- Build the ARM Trusted firmware binary -- Get ddr firmware -- Build U-Boot -- Flash to eMMC -- Boot - -Get and Build the ARM Trusted firmware -====================================== -$ git clone https://github.com/nxp-imx/imx-atf -$ git checkout imx_5.4.47_2.2.0 -$ make PLAT=imx8mm CROSS_COMPILE=aarch64-linux-gnu- bl31 -$ cp build/imx8mm/release/bl31.bin . - -Get the DDR Firmware -==================== -$ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.9.bin -$ chmod +x firmware-imx-8.9.bin -$ ./firmware-imx-8.9.bin -$ cp firmware-imx-8.9/firmware/ddr/synopsys/lpddr4*.bin . - -Build U-Boot -============ -$ make imx8mm_venice_defconfig -$ make CROSS_COMPILE=aarch64-linux-gnu- - -Update eMMC -=========== -=> tftpboot $loadaddr flash.bin -=> setexpr blkcnt $filesize + 0x1ff && setexpr blkcnt $blkcnt / 0x200 -=> mmc dev 2 && mmc write $loadaddr 0x42 $blkcnt # for IMX8MM -=> mmc dev 2 && mmc write $loadaddr 0x40 $blkcnt # for IMX8MN diff --git a/doc/board/gateworks/imx8mm_venice.rst b/doc/board/gateworks/imx8mm_venice.rst new file mode 100644 index 00000000000..f1e7e499445 --- /dev/null +++ b/doc/board/gateworks/imx8mm_venice.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx8mm_venice +============= + +U-Boot for the Gateworks i.MX8M Mini Venice Development Kit boards + +Quick Start +----------- +- Build the ARM Trusted firmware binary +- Get DDR firmware +- Build U-Boot +- Flash to eMMC +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +.. code-block:: bash + + $ git clone https://github.com/nxp-imx/imx-atf.git -b lf_v2.4 + $ make PLAT=imx8mm bl31 CROSS_COMPILE=aarch64-linux-gnu- + $ cp build/imx8mm/release/bl31.bin . + +Get the DDR Firmware +-------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.9.bin + $ chmod +x firmware-imx-8.9.bin + $ ./firmware-imx-8.9.bin + $ cp firmware-imx-8.9/firmware/ddr/synopsys/lpddr4*.bin . + +Build U-Boot +------------ + +.. code-block:: bash + + $ make imx8mm_venice_defconfig + $ make CROSS_COMPILE=aarch64-linux-gnu- + +Update eMMC +----------- + +.. code-block:: bash + + => tftpboot $loadaddr flash.bin + => setexpr blkcnt $filesize + 0x1ff && setexpr blkcnt $blkcnt / 0x200 + => mmc dev 2 && mmc write $loadaddr 0x42 $blkcnt diff --git a/doc/board/gateworks/imx8mn_venice.rst b/doc/board/gateworks/imx8mn_venice.rst new file mode 100644 index 00000000000..7ba953a4a85 --- /dev/null +++ b/doc/board/gateworks/imx8mn_venice.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx8mn_venice +============= + +U-Boot for the Gateworks i.MX8M Nano Venice Development Kit boards + +Quick Start +----------- +- Build the ARM Trusted firmware binary +- Get DDR firmware +- Build U-Boot +- Flash to eMMC +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +.. code-block:: bash + + $ git clone https://github.com/nxp-imx/imx-atf.git -b lf_v2.4 + $ make PLAT=imx8mn bl31 CROSS_COMPILE=aarch64-linux-gnu- + $ cp build/imx8mn/release/bl31.bin . + +Get the DDR Firmware +-------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.9.bin + $ chmod +x firmware-imx-8.9.bin + $ ./firmware-imx-8.9.bin + $ cp firmware-imx-8.9/firmware/ddr/synopsys/lpddr4*.bin . + +Build U-Boot +------------ + +.. code-block:: bash + + $ make imx8mn_venice_defconfig + $ make CROSS_COMPILE=aarch64-linux-gnu- + +Update eMMC +----------- + +.. code-block:: bash + + => tftpboot $loadaddr flash.bin + => setexpr blkcnt $filesize + 0x1ff && setexpr blkcnt $blkcnt / 0x200 + => mmc dev 2 && mmc write $loadaddr 0x40 $blkcnt diff --git a/doc/board/gateworks/imx8mp_venice.rst b/doc/board/gateworks/imx8mp_venice.rst new file mode 100644 index 00000000000..632cd742d1f --- /dev/null +++ b/doc/board/gateworks/imx8mp_venice.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx8mp_venice +============= + +U-Boot for the Gateworks i.MX8M Plus Venice Development Kit boards + +Quick Start +----------- +- Build the ARM Trusted firmware binary +- Get DDR firmware +- Build U-Boot +- Flash to eMMC +- Boot + +Get and Build the ARM Trusted firmware +-------------------------------------- + +.. code-block:: bash + + $ git clone https://github.com/nxp-imx/imx-atf.git -b lf_v2.4 + $ make PLAT=imx8mp bl31 CROSS_COMPILE=aarch64-linux-gnu- + $ cp build/imx8mp/release/bl31.bin . + +Get the DDR Firmware +-------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.9.bin + $ chmod +x firmware-imx-8.9.bin + $ ./firmware-imx-8.9.bin + $ cp firmware-imx-8.9/firmware/ddr/synopsys/lpddr4*.bin . + +Build U-Boot +------------ + +.. code-block:: bash + + $ make imx8mp_venice_defconfig + $ make CROSS_COMPILE=aarch64-linux-gnu- + +Update eMMC +----------- + +.. code-block:: bash + + => tftpboot $loadaddr flash.bin + => setexpr blkcnt $filesize + 0x1ff && setexpr blkcnt $blkcnt / 0x200 + => mmc dev 2 && mmc write $loadaddr 0x40 $blkcnt diff --git a/doc/board/gateworks/index.rst b/doc/board/gateworks/index.rst new file mode 100644 index 00000000000..6cf0839814d --- /dev/null +++ b/doc/board/gateworks/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Gateworks +========= + +.. toctree:: + :maxdepth: 2 + + imx8mm_venice + imx8mn_venice + imx8mp_venice diff --git a/doc/board/index.rst b/doc/board/index.rst index 1e628e99e63..618d22e616b 100644 --- a/doc/board/index.rst +++ b/doc/board/index.rst @@ -20,6 +20,7 @@ Board-specific doc congatec/index coreboot/index emulation/index + gateworks/index google/index highbank/index intel/index -- cgit v1.3.1 From 093ff96e741d5754e2c895a367fce06ae4464d16 Mon Sep 17 00:00:00 2001 From: Yu Chien Peter Lin Date: Tue, 14 Feb 2023 18:18:51 +0800 Subject: doc: arch: Add document for RISC-V architecture This patch adds a brief introduction to the RISC-V architecture and the typical boot process used on a variety of RISC-V platforms. Signed-off-by: Yu Chien Peter Lin Reviewed-by: Samuel Holland Reviewed-by: Simon Glass Reviewed-by: Rick Chen Reviewed-by: Heinrich Schuchardt --- MAINTAINERS | 1 + doc/arch/index.rst | 1 + doc/arch/riscv.rst | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+) create mode 100644 doc/arch/riscv.rst diff --git a/MAINTAINERS b/MAINTAINERS index 6f53f9c2f6f..41c9f265f81 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1298,6 +1298,7 @@ S: Maintained T: git https://source.denx.de/u-boot/custodians/u-boot-riscv.git F: arch/riscv/ F: cmd/riscv/ +F: doc/arch/riscv.rst F: doc/usage/sbi.rst F: drivers/sysreset/sysreset_sbi.c F: drivers/timer/andes_plmt_timer.c diff --git a/doc/arch/index.rst b/doc/arch/index.rst index b3e85f9bf34..b8da4b8c8e5 100644 --- a/doc/arch/index.rst +++ b/doc/arch/index.rst @@ -11,6 +11,7 @@ Architecture-specific doc m68k mips nios2 + riscv sandbox/index sh x86 diff --git a/doc/arch/riscv.rst b/doc/arch/riscv.rst new file mode 100644 index 00000000000..af0c48b8982 --- /dev/null +++ b/doc/arch/riscv.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2023, Yu Chien Peter Lin + +RISC-V +====== + +Overview +-------- + +This document outlines the U-Boot boot process for the RISC-V architecture. +RISC-V is an open-source instruction set architecture (ISA) based on the +principles of reduced instruction set computing (RISC). It has been designed +to be flexible and customizable, allowing it to be adapted to different use +cases, from embedded systems to high performance servers. + +Typical Boot Process +-------------------- + +U-Boot can run in either M-mode or S-mode, depending on whether it runs before +the initialization of the firmware providing SBI (Supervisor Binary Interface). +The firmware is necessary in the RISC-V boot process as it serves as a SEE +(Supervisor Execution Environment) to handle exceptions for the S-mode U-Boot +or Operating System. + +In between the boot phases, the hartid is passed through the a0 register, and +the start address of the devicetree is passed through the a1 register. + +As a reference, OpenSBI is an SBI implementation that can be used with U-Boot +in different modes, see the +`OpenSBI firmware document `_ +for more details. + +M-mode U-Boot +^^^^^^^^^^^^^ + +When running in M-mode U-Boot, it will load the payload image (e.g. +`fw_payload `_) +which contains the firmware and the S-mode Operating System; in this case, you +can use mkimage to package the payload image into an uImage format, and boot it +using the bootm command. + +The following diagram illustrates the boot process:: + + <-----------( M-mode )----------><--( S-mode )--> + +----------+ +--------------+ +------------+ + | U-Boot |-->| SBI firmware |--->| OS | + +----------+ +--------------+ +------------+ + +To examine the boot process with the QEMU virt machine, you can follow the +steps in the "Building U-Boot" section of the following document: +:doc:`../board/emulation/qemu-riscv`. + +S-mode U-Boot +^^^^^^^^^^^^^ + +RISC-V production boot images may include a U-Boot SPL for platform-specific +initialization. The U-Boot SPL then loads a FIT image (u-boot.itb), which +contains a firmware (e.g. +`fw_dynamic `_) +providing the SBI, as well as a regular U-Boot (or U-Boot proper) running in +S-mode. Finally, the S-mode Operating +System is loaded. + +The following diagram illustrates the boot process:: + + <-------------( M-mode )----------><----------( S-mode )-------> + +------------+ +--------------+ +----------+ +----------+ + | U-Boot SPL |-->| SBI firmware |--->| U-Boot |-->| OS | + +------------+ +--------------+ +----------+ +----------+ + +To examine the boot process with the QEMU virt machine, you can follow the +steps in the "Running U-Boot SPL" section of the following document: +:doc:`../board/emulation/qemu-riscv`. + +Toolchain +--------- + +You can build the +`RISC-V GNU toolchain `_ +from scratch, or download a pre-built toolchain from the +`releases page `_. -- cgit v1.3.1 From 67af329a741b546986be2f3b18933f8c8b373bed Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Mon, 13 Feb 2023 19:22:33 +0100 Subject: efi_loader: avoid buffer overrun in efi_var_mem_compare We should not scan beyond the end of string name. Signed-off-by: Heinrich Schuchardt --- lib/efi_loader/efi_var_mem.c | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/lib/efi_loader/efi_var_mem.c b/lib/efi_loader/efi_var_mem.c index e1058e3c6aa..d6b65aed12e 100644 --- a/lib/efi_loader/efi_var_mem.c +++ b/lib/efi_loader/efi_var_mem.c @@ -41,11 +41,13 @@ efi_var_mem_compare(struct efi_var_entry *var, const efi_guid_t *guid, i < sizeof(efi_guid_t) && match; ++i) match = (guid1[i] == guid2[i]); - for (data = var->name, var_name = name;; ++data, ++var_name) { + for (data = var->name, var_name = name;; ++data) { if (match) match = (*data == *var_name); if (!*data) break; + if (*var_name) + ++var_name; } ++data; -- cgit v1.3.1 From a135320b428a09b7856bb06c248eca0ffffb60f5 Mon Sep 17 00:00:00 2001 From: Masahisa Kojima Date: Wed, 15 Feb 2023 11:32:17 +0900 Subject: efi_loader: fix wrong attribute check for QueryVariableInfo QueryVariableInfo with EFI_VARIABLE_HARDWARE_ERROR_RECORD is accepted, remove wrong attribute check. Fixes: 454a9442fbce ("efi_loader: update attribute check for QueryVariableInfo()") Signed-off-by: Masahisa Kojima Reviewed-by: Heinrich Schuchardt --- lib/efi_loader/efi_variable.c | 3 --- 1 file changed, 3 deletions(-) diff --git a/lib/efi_loader/efi_variable.c b/lib/efi_loader/efi_variable.c index 4c85cfa607e..5804f69954a 100644 --- a/lib/efi_loader/efi_variable.c +++ b/lib/efi_loader/efi_variable.c @@ -366,9 +366,6 @@ efi_status_t efi_query_variable_info_int(u32 attributes, EFI_VARIABLE_RUNTIME_ACCESS) return EFI_INVALID_PARAMETER; - if (attributes & EFI_VARIABLE_HARDWARE_ERROR_RECORD) - return EFI_UNSUPPORTED; - if (attributes & ~(u32)EFI_VARIABLE_MASK) return EFI_INVALID_PARAMETER; -- cgit v1.3.1 From aa2d3945ce6df43903d76cadde1c0669d6d5d43b Mon Sep 17 00:00:00 2001 From: Etienne Carriere Date: Thu, 16 Feb 2023 17:29:48 +0100 Subject: efi_loader: Measure the loaded DTB Measures the DTB passed to the EFI application upon new boolean config switch CONFIG_EFI_TCG2_PROTOCOL_MEASURE_DTB. For platforms where the content of the DTB passed to the OS can change across reboots, there is not point measuring it hence the config switch to allow platform to not embed this feature. Co-developed-by: Ilias Apalodimas Signed-off-by: Ilias Apalodimas Signed-off-by: Etienne Carriere Tested-by: Ilias Apalodimas Reviewed-by: Ilias Apalodimas --- cmd/bootefi.c | 8 ++++++ include/efi_loader.h | 2 ++ include/efi_tcg2.h | 10 +++++++ include/tpm-v2.h | 2 ++ lib/efi_loader/Kconfig | 11 +++++++ lib/efi_loader/efi_tcg2.c | 73 +++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 106 insertions(+) diff --git a/cmd/bootefi.c b/cmd/bootefi.c index 2a7d42925d6..6618335ddf9 100644 --- a/cmd/bootefi.c +++ b/cmd/bootefi.c @@ -332,6 +332,14 @@ efi_status_t efi_install_fdt(void *fdt) efi_try_purge_kaslr_seed(fdt); + if (CONFIG_IS_ENABLED(EFI_TCG2_PROTOCOL_MEASURE_DTB)) { + ret = efi_tcg2_measure_dtb(fdt); + if (ret == EFI_SECURITY_VIOLATION) { + log_err("ERROR: failed to measure DTB\n"); + return ret; + } + } + /* Install device tree as UEFI table */ ret = efi_install_configuration_table(&efi_guid_fdt, fdt); if (ret != EFI_SUCCESS) { diff --git a/include/efi_loader.h b/include/efi_loader.h index c664d6cdf2c..1542b4b625c 100644 --- a/include/efi_loader.h +++ b/include/efi_loader.h @@ -531,6 +531,8 @@ efi_status_t efi_tcg2_notify_exit_boot_services_failed(void); efi_status_t efi_tcg2_measure_efi_app_invocation(struct efi_loaded_image_obj *handle); /* Measure efi application exit */ efi_status_t efi_tcg2_measure_efi_app_exit(void); +/* Measure DTB */ +efi_status_t efi_tcg2_measure_dtb(void *dtb); /* Called by bootefi to initialize root node */ efi_status_t efi_root_node_register(void); /* Called by bootefi to initialize runtime */ diff --git a/include/efi_tcg2.h b/include/efi_tcg2.h index 874306dc112..b1c3abd0975 100644 --- a/include/efi_tcg2.h +++ b/include/efi_tcg2.h @@ -233,6 +233,16 @@ struct efi_gpt_data { gpt_entry partitions[]; } __packed; +/** + * struct tdUEFI_PLATFORM_FIRMWARE_BLOB2 + * @blob_description_size: Byte size of @data + * @data: Description data + */ +struct uefi_platform_firmware_blob2 { + u8 blob_description_size; + u8 data[]; +} __packed; + struct efi_tcg2_protocol { efi_status_t (EFIAPI * get_capability)(struct efi_tcg2_protocol *this, struct efi_tcg2_boot_service_capability *capability); diff --git a/include/tpm-v2.h b/include/tpm-v2.h index 737e57551d7..2df3dad5532 100644 --- a/include/tpm-v2.h +++ b/include/tpm-v2.h @@ -105,6 +105,8 @@ struct udevice; "Exit Boot Services Returned with Failure" #define EFI_EXIT_BOOT_SERVICES_SUCCEEDED \ "Exit Boot Services Returned with Success" +#define EFI_DTB_EVENT_STRING \ + "DTB DATA" /* TPMS_TAGGED_PROPERTY Structure */ struct tpms_tagged_property { diff --git a/lib/efi_loader/Kconfig b/lib/efi_loader/Kconfig index c56904afc2e..c05a54df16a 100644 --- a/lib/efi_loader/Kconfig +++ b/lib/efi_loader/Kconfig @@ -346,6 +346,17 @@ config EFI_TCG2_PROTOCOL_EVENTLOG_SIZE this is going to be allocated twice. One for the eventlog it self and one for the configuration table that is required from the spec +config EFI_TCG2_PROTOCOL_MEASURE_DTB + bool "Measure DTB with EFI_TCG2_PROTOCOL" + depends on EFI_TCG2_PROTOCOL + help + When enabled, the DTB image passed to the booted EFI image is + measured using the EFI TCG2 protocol. Do not enable this feature if + the passed DTB contains data that change across platform reboots + and cannot be used has a predictable measurement. Otherwise + this feature allows better measurement of the system boot + sequence. + config EFI_LOAD_FILE2_INITRD bool "EFI_FILE_LOAD2_PROTOCOL for Linux initial ramdisk" default y diff --git a/lib/efi_loader/efi_tcg2.c b/lib/efi_loader/efi_tcg2.c index 918e9a26864..2dcc3171576 100644 --- a/lib/efi_loader/efi_tcg2.c +++ b/lib/efi_loader/efi_tcg2.c @@ -2175,6 +2175,79 @@ out1: return ret; } +/* Return the byte size of reserved map area in DTB or -1 upon error */ +static ssize_t size_of_rsvmap(void *dtb) +{ + struct fdt_reserve_entry e; + ssize_t size_max; + ssize_t size; + u8 *rsvmap_base; + + rsvmap_base = (u8 *)dtb + fdt_off_mem_rsvmap(dtb); + size_max = fdt_totalsize(dtb) - fdt_off_mem_rsvmap(dtb); + size = 0; + + do { + memcpy(&e, rsvmap_base + size, sizeof(e)); + size += sizeof(e); + if (size > size_max) + return -1; + } while (e.size); + + return size; +} + +/** + * efi_tcg2_measure_dtb() - measure DTB passed to the OS + * + * @dtb: pointer to the device tree blob + * + * Return: status code + */ +efi_status_t efi_tcg2_measure_dtb(void *dtb) +{ + struct uefi_platform_firmware_blob2 *blob; + struct fdt_header *header; + sha256_context hash_ctx; + struct udevice *dev; + ssize_t rsvmap_size; + efi_status_t ret; + u32 event_size; + + if (!is_tcg2_protocol_installed()) + return EFI_SUCCESS; + + ret = platform_get_tpm2_device(&dev); + if (ret != EFI_SUCCESS) + return EFI_SECURITY_VIOLATION; + + rsvmap_size = size_of_rsvmap(dtb); + if (rsvmap_size < 0) + return EFI_SECURITY_VIOLATION; + + event_size = sizeof(*blob) + sizeof(EFI_DTB_EVENT_STRING) + SHA256_SUM_LEN; + blob = calloc(1, event_size); + if (!blob) + return EFI_OUT_OF_RESOURCES; + + blob->blob_description_size = sizeof(EFI_DTB_EVENT_STRING); + memcpy(blob->data, EFI_DTB_EVENT_STRING, blob->blob_description_size); + + /* Measure populated areas of the DTB */ + header = dtb; + sha256_starts(&hash_ctx); + sha256_update(&hash_ctx, (u8 *)header, sizeof(struct fdt_header)); + sha256_update(&hash_ctx, (u8 *)dtb + fdt_off_dt_struct(dtb), fdt_size_dt_strings(dtb)); + sha256_update(&hash_ctx, (u8 *)dtb + fdt_off_dt_strings(dtb), fdt_size_dt_struct(dtb)); + sha256_update(&hash_ctx, (u8 *)dtb + fdt_off_mem_rsvmap(dtb), rsvmap_size); + sha256_finish(&hash_ctx, blob->data + blob->blob_description_size); + + ret = tcg2_measure_event(dev, 0, EV_POST_CODE, event_size, (u8 *)blob); + + free(blob); + return ret; +} + /** * efi_tcg2_measure_efi_app_invocation() - measure efi app invocation * -- cgit v1.3.1 From 4429393b5a41557c744b1fab912a32b34bee8d38 Mon Sep 17 00:00:00 2001 From: Etienne Carriere Date: Thu, 16 Feb 2023 18:21:41 +0100 Subject: efi_loader: set CapsuleMax from CONFIG_EFI_CAPSULE_MAX Adds CONFIG_EFI_CAPSULE_MAX to configure the max index value used in EFI capsule reports. Prior to this change is the hard coded value was 65535 which would exceed available storage for variables. Now the default value is 15 which should work fine with most systems. Signed-off-by: Etienne Carriere --- lib/efi_loader/Kconfig | 8 ++++++++ lib/efi_loader/efi_capsule.c | 48 +++++++++++++++++++++++++++++++------------- lib/efi_loader/efi_setup.c | 7 ++++++- 3 files changed, 48 insertions(+), 15 deletions(-) diff --git a/lib/efi_loader/Kconfig b/lib/efi_loader/Kconfig index c05a54df16a..c5835e6ef61 100644 --- a/lib/efi_loader/Kconfig +++ b/lib/efi_loader/Kconfig @@ -226,6 +226,14 @@ config EFI_CAPSULE_AUTHENTICATE Select this option if you want to enable capsule authentication +config EFI_CAPSULE_MAX + int "Max value for capsule index" + default 15 + range 0 65535 + help + Select the max capsule index value used for capsule report + variables. This value is used to create CapsuleMax variable. + config EFI_DEVICE_PATH_TO_TEXT bool "Device path to text protocol" default y diff --git a/lib/efi_loader/efi_capsule.c b/lib/efi_loader/efi_capsule.c index 0997cd248fe..d5d3ede7ae6 100644 --- a/lib/efi_loader/efi_capsule.c +++ b/lib/efi_loader/efi_capsule.c @@ -45,17 +45,7 @@ const efi_guid_t fwu_guid_os_request_fw_accept = static struct efi_file_handle *bootdev_root; #endif -/** - * get_last_capsule - get the last capsule index - * - * Retrieve the index of the capsule invoked last time from "CapsuleLast" - * variable. - * - * Return: - * * > 0 - the last capsule index invoked - * * 0xffff - on error, or no capsule invoked yet - */ -static __maybe_unused unsigned int get_last_capsule(void) +static __maybe_unused unsigned int get_capsule_index(const u16 *variable_name) { u16 value16[11]; /* "CapsuleXXXX": non-null-terminated */ char value[5]; @@ -65,7 +55,7 @@ static __maybe_unused unsigned int get_last_capsule(void) int i; size = sizeof(value16); - ret = efi_get_variable_int(u"CapsuleLast", &efi_guid_capsule_report, + ret = efi_get_variable_int(variable_name, &efi_guid_capsule_report, NULL, &size, value16, NULL); if (ret != EFI_SUCCESS || size != 22 || u16_strncmp(value16, u"Capsule", 7)) @@ -84,6 +74,35 @@ err: return index; } +/** + * get_last_capsule - get the last capsule index + * + * Retrieve the index of the capsule invoked last time from "CapsuleLast" + * variable. + * + * Return: + * * > 0 - the last capsule index invoked + * * 0xffff - on error, or no capsule invoked yet + */ +static __maybe_unused unsigned int get_last_capsule(void) +{ + return get_capsule_index(u"CapsuleLast"); +} + +/** + * get_max_capsule - get the max capsule index + * + * Retrieve the max capsule index value from "CapsuleMax" variable. + * + * Return: + * * > 0 - the max capsule index + * * 0xffff - on error, or "CapsuleMax" variable does not exist + */ +static __maybe_unused unsigned int get_max_capsule(void) +{ + return get_capsule_index(u"CapsuleMax"); +} + /** * set_capsule_result - set a result variable * @capsule: Capsule @@ -1290,7 +1309,7 @@ efi_status_t efi_launch_capsules(void) { struct efi_capsule_header *capsule = NULL; u16 **files; - unsigned int nfiles, index, i; + unsigned int nfiles, index, index_max, i; efi_status_t ret; bool capsule_update = true; bool update_status = true; @@ -1299,6 +1318,7 @@ efi_status_t efi_launch_capsules(void) if (check_run_capsules() != EFI_SUCCESS) return EFI_SUCCESS; + index_max = get_max_capsule(); index = get_last_capsule(); /* @@ -1317,7 +1337,7 @@ efi_status_t efi_launch_capsules(void) /* Launch capsules */ for (i = 0, ++index; i < nfiles; i++, index++) { log_debug("Applying %ls\n", files[i]); - if (index > 0xffff) + if (index > index_max) index = 0; ret = efi_capsule_read_file(files[i], &capsule); if (ret == EFI_SUCCESS) { diff --git a/lib/efi_loader/efi_setup.c b/lib/efi_loader/efi_setup.c index 69aaefab633..58d4e134023 100644 --- a/lib/efi_loader/efi_setup.c +++ b/lib/efi_loader/efi_setup.c @@ -130,12 +130,17 @@ static efi_status_t efi_init_capsule(void) efi_status_t ret = EFI_SUCCESS; if (IS_ENABLED(CONFIG_EFI_HAVE_CAPSULE_SUPPORT)) { + u16 var_name16[12]; + + efi_create_indexed_name(var_name16, sizeof(var_name16), + "Capsule", CONFIG_EFI_CAPSULE_MAX); + ret = efi_set_variable_int(u"CapsuleMax", &efi_guid_capsule_report, EFI_VARIABLE_READ_ONLY | EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS, - 22, u"CapsuleFFFF", false); + 22, var_name16, false); if (ret != EFI_SUCCESS) printf("EFI: cannot initialize CapsuleMax variable\n"); } -- cgit v1.3.1 From 5e957ae3504290a0c62188331a429ec9b908aa1b Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sun, 19 Feb 2023 21:26:24 +0100 Subject: doc: remove superfluous warning We have been using Sphinx >=3 since 2020. We don't expect issues. Signed-off-by: Heinrich Schuchardt --- doc/conf.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 3db70f80c12..00f24136647 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -47,10 +47,6 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', # the process to proceed; hopefully somebody will fix this properly soon. # if major >= 3: - sys.stderr.write('''WARNING: The kernel documentation build process - support for Sphinx v3.0 and above is brand new. Be prepared for - possible issues in the generated output. - ''') if (major > 3) or (minor > 0 or patch >= 2): # Sphinx c function parser is more pedantic with regards to type # checking. Due to that, having macros at c:function cause problems. -- cgit v1.3.1