From dadc3c215358af7c847deecacc14789605bc2ca9 Mon Sep 17 00:00:00 2001 From: Sam Povilus Date: Mon, 8 Jul 2024 10:48:11 -0600 Subject: [PATCH 01/20] doc: Remove FIT documentation that is elsewhere Before 9d0750064e (doc: Move external FIT docs into the main body), the FIT property data-size was not a mandatory property and still it is not expected to be set alongside the data property. Move the data-size property to the "Conditionally mandatory property" section, where it actually belongs. Signed-off-by: Sam Povilus Reviewed-by: Simon Glass --- doc/usage/fit/index.rst | 4 +- doc/usage/fit/source_file_format.rst | 684 +-------------------------- 2 files changed, 6 insertions(+), 682 deletions(-) diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst index bd25bd30b28..68231e93c7c 100644 --- a/doc/usage/fit/index.rst +++ b/doc/usage/fit/index.rst @@ -4,8 +4,8 @@ Flat Image Tree (FIT) ===================== U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging -images that it it reads and boots. Documentation about FIT is available at -doc/uImage.FIT +images that it reads and boots. Documentation about FIT is available in +`the Flattened Image Tree project `_. .. toctree:: :maxdepth: 1 diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst index 15990e3ff54..2bd8e792350 100644 --- a/doc/usage/fit/source_file_format.rst +++ b/doc/usage/fit/source_file_format.rst @@ -1,684 +1,8 @@ -.. SPDX-License-Identifier: GPL-2.0+ +.. SPDX-License-Identifier: GPL-2.0-or-later Flattened Image Tree (FIT) Format ================================= -Introduction ------------- - -The number of elements playing a role in the kernel booting process has -increased over time and now typically includes the devicetree, kernel image and -possibly a ramdisk image. Generally, all must be placed in the system memory and -booted together. - -For firmware images a similar process has taken place, with various binaries -loaded at different addresses, such as ARM's ATF, OpenSBI, FPGA and U-Boot -itself. - -FIT provides a flexible and extensible format to deal with this complexity. It -provides support for multiple components. It also supports multiple -configurations, so that the same FIT can be used to boot multiple boards, with -some components in common (e.g. kernel) and some specific to that board (e.g. -devicetree). - -Terminology -~~~~~~~~~~~ - -This document defines FIT by providing FDT (Flat Device Tree) bindings. These -describe the final form of the FIT at the moment when it is used. The user -perspective may be simpler, as some of the properties (like timestamps and -hashes) are filled in automatically by the U-Boot mkimage tool. - -To avoid confusion with the kernel FDT the following naming convention is used: - -FIT - Flattened Image Tree - -FIT is formally a flattened devicetree (in the libfdt meaning), which conforms -to bindings defined in this document. - -.its - image tree source - -.itb - flattened image tree blob - -Image-building procedure -~~~~~~~~~~~~~~~~~~~~~~~~ - -The following picture shows how the FIT is prepared. Input consists of -image source file (.its) and a set of data files. Image is created with the -help of standard U-Boot mkimage tool which in turn uses dtc (device tree -compiler) to produce image tree blob (.itb). The resulting .itb file is the -actual binary of a new FIT:: - - tqm5200.its - + - vmlinux.bin.gz mkimage + dtc xfer to target - eldk-4.2-ramdisk --------------> tqm5200.itb --------------> boot - tqm5200.dtb /|\ - | - 'new FIT' - -Steps: - -#. Create .its file, automatically filled-in properties are omitted - -#. Call mkimage tool on a .its file - -#. mkimage calls dtc to create .itb image and assures that - missing properties are added - -#. .itb (new FIT) is uploaded onto the target and used therein - - -Unique identifiers -~~~~~~~~~~~~~~~~~~ - -To identify FIT sub-nodes representing images, hashes, configurations (which -are defined in the following sections), the "unit name" of the given sub-node -is used as it's identifier as it assures uniqueness without additional -checking required. - - -External data -~~~~~~~~~~~~~ - -FIT is normally built initially with image data in the 'data' property of each -image node. It is also possible for this data to reside outside the FIT itself. -This allows the 'FDT' part of the FIT to be quite small, so that it can be -loaded and scanned without loading a large amount of data. Then when an image is -needed it can be loaded from an external source. - -External FITs use 'data-offset' or 'data-position' instead of 'data'. - -The mkimage tool can convert a FIT to use external data using the `-E` argument, -optionally using `-p` to specific a fixed position. - -It is often desirable to align each image to a block size or cache-line size -(e.g. 512 bytes), so that there is no need to copy it to an aligned address when -reading the image data. The mkimage tool provides a `-B` argument to support -this. - -Root-node properties --------------------- - -The root node of the FIT should have the following layout:: - - / o image-tree - |- description = "image description" - |- timestamp = <12399321> - |- #address-cells = <1> - | - o images - | | - | o image-1 {...} - | o image-2 {...} - | ... - | - o configurations - |- default = "conf-1" - | - o conf-1 {...} - o conf-2 {...} - ... - -Optional property -~~~~~~~~~~~~~~~~~ - -description - Textual description of the FIT - -Mandatory property -~~~~~~~~~~~~~~~~~~ - -timestamp - Last image modification time being counted in seconds since - 1970-01-01 00:00:00 - to be automatically calculated by mkimage tool. - -Conditionally mandatory property -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -#address-cells - Number of 32bit cells required to represent entry and - load addresses supplied within sub-image nodes. May be omitted when no - entry or load addresses are used. - -Mandatory nodes -~~~~~~~~~~~~~~~ - -images - This node contains a set of sub-nodes, each of them representing - single component sub-image (like kernel, ramdisk, etc.). At least one - sub-image is required. - -configurations - Contains a set of available configuration nodes and - defines a default configuration. - - -'/images' node --------------- - -This node is a container node for component sub-image nodes. Each sub-node of -the '/images' node should have the following layout:: - - o image-1 - |- description = "component sub-image description" - |- data = /incbin/("path/to/data/file.bin") - |- type = "sub-image type name" - |- arch = "ARCH name" - |- os = "OS name" - |- compression = "compression name" - |- load = <00000000> - |- entry = <00000000> - | - o hash-1 {...} - o hash-2 {...} - ... - -Mandatory properties -~~~~~~~~~~~~~~~~~~~~ - -description - Textual description of the component sub-image - -type - Name of component sub-image type. Supported types are: - - ==================== ================== - Sub-image type Meaning - ==================== ================== - invalid Invalid Image - aisimage Davinci AIS image - atmelimage ATMEL ROM-Boot Image - copro Coprocessor Image - fdt_legacy legacy Image with Flat Device Tree - filesystem Filesystem Image - firmware Firmware - firmware_ivt Firmware with HABv4 IVT - flat_dt Flat Device Tree - fpga FPGA Device Image (bitstream file, vendor specific) - gpimage TI Keystone SPL Image - imx8image NXP i.MX8 Boot Image - imx8mimage NXP i.MX8M Boot Image - imximage Freescale i.MX Boot Image - kernel Kernel Image - kernel_noload Kernel Image (no loading done) - kwbimage Kirkwood Boot Image - lpc32xximage LPC32XX Boot Image - mtk_image MediaTek BootROM loadable Image - multi Multi-File Image - mxsimage Freescale MXS Boot Image - omapimage TI OMAP SPL With GP CH - pblimage Freescale PBL Boot Image - pmmc TI Power Management Micro-Controller Firmware - ramdisk RAMDisk Image - rkimage Rockchip Boot Image - rksd Rockchip SD Boot Image - rkspi Rockchip SPI Boot Image - script Script - socfpgaimage Altera SoCFPGA CV/AV preloader - socfpgaimage_v1 Altera SoCFPGA A10 preloader - spkgimage Renesas SPKG Image - standalone Standalone Program - stm32image STMicroelectronics STM32 Image - sunxi_egon Allwinner eGON Boot Image - sunxi_toc0 Allwinner TOC0 Boot Image - tee Trusted Execution Environment Image - ublimage Davinci UBL image - vybridimage Vybrid Boot Image - x86_setup x86 setup.bin - zynqimage Xilinx Zynq Boot Image - zynqmpbif Xilinx ZynqMP Boot Image (bif) - zynqmpimage Xilinx ZynqMP Boot Image - ==================== ================== - -compression - Compression used by included data. If no compression is used, the - compression property should be set to "none". If the data is compressed but - it should not be uncompressed by the loader (e.g. compressed ramdisk), this - should also be set to "none". - - Supported compression types are: - - ==================== ================== - Compression type Meaning - ==================== ================== - none uncompressed - bzip2 bzip2 compressed - gzip gzip compressed - lz4 lz4 compressed - lzma lzma compressed - lzo lzo compressed - zstd zstd compressed - ==================== ================== - - -Conditionally mandatory property -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -data - Path to the external file which contains this node's binary data. Within - the FIT this is the contents of the file. This is mandatory unless - external data is used. - -data-offset - Offset of the data in a separate image store. The image store is placed - immediately after the last byte of the device tree binary, aligned to a - 4-byte boundary. This is mandatory if external data is used, with an offset. - -data-position - Machine address at which the data is to be found. This is a fixed address - not relative to the loading of the FIT. This is mandatory if external data - used with a fixed address. - -data-size - Size of the data in bytes. This is mandatory if external data is used. - -os - OS name, mandatory for types "kernel". Valid OS names are: - - ==================== ================== - OS name Meaning - ==================== ================== - invalid Invalid OS - 4_4bsd 4_4BSD - arm-trusted-firmware ARM Trusted Firmware - dell Dell - efi EFI Firmware - esix Esix - freebsd FreeBSD - integrity INTEGRITY - irix Irix - linux Linux - ncr NCR - netbsd NetBSD - openbsd OpenBSD - openrtos OpenRTOS - opensbi RISC-V OpenSBI - ose Enea OSE - plan9 Plan 9 - psos pSOS - qnx QNX - rtems RTEMS - sco SCO - solaris Solaris - svr4 SVR4 - tee Trusted Execution Environment - u-boot U-Boot - vxworks VxWorks - ==================== ================== - -arch - Architecture name, mandatory for types: "standalone", "kernel", - "firmware", "ramdisk" and "fdt". Valid architecture names are: - - ==================== ================== - Architecture type Meaning - ==================== ================== - invalid Invalid ARCH - alpha Alpha - arc ARC - arm64 AArch64 - arm ARM - avr32 AVR32 - blackfin Blackfin - ia64 IA64 - m68k M68K - microblaze MicroBlaze - mips64 MIPS 64 Bit - mips MIPS - nds32 NDS32 - nios2 NIOS II - or1k OpenRISC 1000 - powerpc PowerPC - ppc PowerPC - riscv RISC-V - s390 IBM S390 - sandbox Sandbox - sh SuperH - sparc64 SPARC 64 Bit - sparc SPARC - x86_64 AMD x86_64 - x86 Intel x86 - xtensa Xtensa - ==================== ================== - -entry - entry point address, address size is determined by - '#address-cells' property of the root node. - Mandatory for types: "firmware", and "kernel". - -load - load address, address size is determined by '#address-cells' - property of the root node. - Mandatory for types: "firmware", and "kernel". - -compatible - compatible method for loading image. - Mandatory for types: "fpga", and images that do not specify a load address. - Supported compatible methods: - - ========================== ========================================= - Compatible string Meaning - ========================== ========================================= - u-boot,fpga-legacy Generic fpga loading routine. - u-boot,zynqmp-fpga-ddrauth Signed non-encrypted FPGA bitstream for - Xilinx Zynq UltraScale+ (ZymqMP) device. - u-boot,zynqmp-fpga-enc Encrypted FPGA bitstream for Xilinx Zynq - UltraScale+ (ZynqMP) device. - ========================== ========================================= - -phase - U-Boot phase for which the image is intended. - - "spl" - image is an SPL image - - "u-boot" - image is a U-Boot image - -Optional nodes: - -hash-1 - Each hash sub-node represents separate hash or checksum - calculated for node's data according to specified algorithm. - -signature-1 - Each signature sub-node represents separate signature - calculated for node's data according to specified algorithm. - - -Hash nodes ----------- - -:: - - o hash-1 - |- algo = "hash or checksum algorithm name" - |- value = [hash or checksum value] - -Mandatory properties -~~~~~~~~~~~~~~~~~~~~ - -algo - Algorithm name. Supported algoriths and their value sizes are: - - ==================== ============ ========================================= - Sub-image type Size (bytes) Meaning - ==================== ============ ========================================= - crc16-ccitt 2 Cyclic Redundancy Check 16-bit - (Consultative Committee for International - Telegraphy and Telephony) - crc32 4 Cyclic Redundancy Check 32-bit - md5 16 Message Digest 5 (MD5) - sha1 20 Secure Hash Algorithm 1 (SHA1) - sha256 32 Secure Hash Algorithm 2 (SHA256) - sha384 48 Secure Hash Algorithm 2 (SHA384) - sha512 64 Secure Hash Algorithm 2 (SHA512) - ==================== ============ ========================================= - -value - Actual checksum or hash value. - -Image-signature nodes ---------------------- - -:: - - o signature-1 - |- algo = "algorithm name" - |- key-name-hint = "key name" - |- value = [hash or checksum value] - - -Mandatory properties -~~~~~~~~~~~~~~~~~~~~ - -_`FIT Algorithm`: - -algo - Algorithm name. Supported algoriths and their value sizes are shown below. - Note that the hash is specified separately from the signing algorithm, so - it is possible to mix and match any SHA algorithm with any signing - algorithm. The size of the signature relates to the signing algorithm, not - the hash, since it is the hash that is signed. - - ==================== ============ ========================================= - Sub-image type Size (bytes) Meaning - ==================== ============ ========================================= - sha1,rsa2048 256 SHA1 hash signed with 2048-bit - Rivest–Shamir–Adleman algorithm - sha1,rsa3072 384 SHA1 hash signed with 2048-bit RSA - sha1,rsa4096 512 SHA1 hash signed with 2048-bit RSA - sha1,ecdsa256 32 SHA1 hash signed with 256-bit Elliptic - Curve Digital Signature Algorithm - sha256,... - sha384,... - sha512,... - ==================== ============ ========================================= - -key-name-hint - Name of key to use for signing. The keys will normally be in - a single directory (parameter -k to mkimage). For a given key , its - private key is stored in .key and the certificate is stored in - .crt. - -sign-images - A list of images to sign, each being a property of the conf - node that contains then. The default is "kernel,fdt" which means that these - two images will be looked up in the config and signed if present. This is - used by mkimage to determine which images to sign. - -The following properies are added as part of signing, and are mandatory: - -value - Actual signature value. This is added by mkimage. - -hashed-nodes - A list of nodes which were hashed by the signer. Each is - a string - the full path to node. A typical value might be:: - - hashed-nodes = "/", "/configurations/conf-1", "/images/kernel", - "/images/kernel/hash-1", "/images/fdt-1", - "/images/fdt-1/hash-1"; - -hashed-strings - The start and size of the string region of the FIT that was hashed. The - start is normally 0, indicating the first byte of the string table. The size - indicates the number of bytes hashed as part of signing. - -The following properies are added as part of signing, and are optional: - -timestamp - Time when image was signed (standard Unix time_t format) - -signer-name - Name of the signer (e.g. "mkimage") - -signer-version - Version string of the signer (e.g. "2013.01") - -comment - Additional information about the signer or image - -padding - The padding algorithm, it may be pkcs-1.5 or pss, - if no value is provided we assume pkcs-1.5 - - -'/configurations' node ----------------------- - -The 'configurations' node creates convenient, labeled boot configurations, -which combine together kernel images with their ramdisks and fdt blobs. - -The 'configurations' node has the following structure:: - - o configurations - |- default = "default configuration sub-node unit name" - | - o config-1 {...} - o config-2 {...} - ... - - -Optional property -~~~~~~~~~~~~~~~~~ - -default - Selects one of the configuration sub-nodes as a default configuration. - -Mandatory nodes -~~~~~~~~~~~~~~~ - -configuration-sub-node-unit-name - At least one of the configuration sub-nodes is required. - -Optional nodes -~~~~~~~~~~~~~~ - -signature-1 - Each signature sub-node represents separate signature - calculated for the configuration according to specified algorithm. - - -Configuration nodes -------------------- - -Each configuration has the following structure:: - - o config-1 - |- description = "configuration description" - |- kernel = "kernel sub-node unit name" - |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...] - |- loadables = "loadables sub-node unit-name" - |- script = " - |- compatible = "vendor,board-style device tree compatible string" - o signature-1 {...} - -Mandatory properties -~~~~~~~~~~~~~~~~~~~~ - -description - Textual configuration description. - -kernel or firmware - Unit name of the corresponding kernel or firmware - (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified, - control is passed to the firmware image. - -Optional properties -~~~~~~~~~~~~~~~~~~~ - -fdt - Unit name of the corresponding fdt blob (component image node of a - "fdt type"). Additional fdt overlay nodes can be supplied which signify - that the resulting device tree blob is generated by the first base fdt - blob with all subsequent overlays applied. - -fpga - Unit name of the corresponding fpga bitstream blob - (component image node of a "fpga type"). - -loadables - Unit name containing a list of additional binaries to be - loaded at their given locations. "loadables" is a comma-separated list - of strings. U-Boot will load each binary at its given start-address and - may optionally invoke additional post-processing steps on this binary based - on its component image node type. - -script - The image to use when loading a U-Boot script (for use with the - source command). - -compatible - The root compatible string of the U-Boot device tree that - this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is - enabled. If this property is not provided, the compatible string will be - extracted from the fdt blob instead. This is only possible if the fdt is - not compressed, so images with compressed fdts that want to use compatible - string matching must always provide this property. - -The FDT blob is required to properly boot FDT based kernel, so the minimal -configuration for 2.6 FDT kernel is (kernel, fdt) pair. - -Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases -'struct bd_info' must be passed instead of FDT blob, thus fdt property *must -not* be specified in a configuration node. - -Configuration-signature nodes ------------------------------ - -:: - - o signature-1 - |- algo = "algorithm name" - |- key-name-hint = "key name" - |- sign-images = "path1", "path2"; - |- value = [hash or checksum value] - |- hashed-strings = <0 len> - - -Mandatory properties -~~~~~~~~~~~~~~~~~~~~ - -algo - See `FIT Algorithm`_. - -key-name-hint - Name of key to use for signing. The keys will normally be in - a single directory (parameter -k to mkimage). For a given key , its - private key is stored in .key and the certificate is stored in - .crt. - -The following properies are added as part of signing, and are mandatory: - -value - Actual signature value. This is added by mkimage. - -The following properies are added as part of signing, and are optional: - -timestamp - Time when image was signed (standard Unix time_t format) - -signer-name - Name of the signer (e.g. "mkimage") - -signer-version - Version string of the signer (e.g. "2013.01") - -comment - Additional information about the signer or image - -padding - The padding algorithm, it may be pkcs-1.5 or pss, - if no value is provided we assume pkcs-1.5 - - - -Examples --------- - -Some example files are available here, showing various scenarios - -.. toctree:: - :maxdepth: 1 - - kernel - kernel_fdt - kernel_fdts_compressed - multi - multi_spl - multi-with-fpga - multi-with-loadables - sec_firmware_ppa - sign-configs - sign-images - uefi - update3 - update_uboot - -.. sectionauthor:: Marian Balakowicz -.. sectionauthor:: External data additions, 25/1/16 Simon Glass +FIT format documentation has been moved to +`a separate project `_. Updates to the +format/specification should be submitted there. From 7aab2b6c1f9cff9d7f1192651ea81b6855b28a33 Mon Sep 17 00:00:00 2001 From: Sam Povilus Date: Mon, 8 Jul 2024 10:48:12 -0600 Subject: [PATCH 02/20] doc: add missing table of content links add missing table of content links, make alphabetical Signed-off-by: Sam Povilus Reviewed-by: Simon Glass --- doc/usage/fit/index.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst index 68231e93c7c..a822bf20cb2 100644 --- a/doc/usage/fit/index.rst +++ b/doc/usage/fit/index.rst @@ -10,10 +10,23 @@ images that it reads and boots. Documentation about FIT is available in .. toctree:: :maxdepth: 1 - source_file_format - howto - x86-fit-boot - signature - verified-boot beaglebone_vboot + howto + kernel_fdt + kernel_fdts_compressed + kernel + multi + multi_spl + multi-with-fpga + multi-with-loadables overlay-fdt-boot + sec_firmware_ppa + signature + sign-configs + sign-images + source_file_format + uefi + update3 + update_uboot + verified-boot + x86-fit-boot \ No newline at end of file From 5c1b5e6bc59a047c2ac65b2c22a2b511658b0f15 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 13 Jul 2024 13:30:29 +0200 Subject: [PATCH 03/20] efi_loader: find distro device-path for media devices The auto-generated load options for media device do not contain a partition node. We cannot expect the simple file protocol here. Get the partition device-path via the loaded image protocol. Fixes: e91b68fd6b83 ("efi_loader: load distro dtb in bootmgr") Reported-by: E Shattow Signed-off-by: Heinrich Schuchardt Tested-by: E Shattow --- include/efi_loader.h | 2 +- lib/efi_loader/efi_bootmgr.c | 2 +- lib/efi_loader/efi_fdt.c | 35 ++++++++++++++++++++--------------- 3 files changed, 22 insertions(+), 17 deletions(-) diff --git a/include/efi_loader.h b/include/efi_loader.h index ca8fc0820f6..f2e5063a970 100644 --- a/include/efi_loader.h +++ b/include/efi_loader.h @@ -1195,6 +1195,6 @@ efi_status_t efi_load_option_dp_join(struct efi_device_path **dp, int efi_get_distro_fdt_name(char *fname, int size, int seq); -void efi_load_distro_fdt(void **fdt, efi_uintn_t *fdt_size); +void efi_load_distro_fdt(efi_handle_t handle, void **fdt, efi_uintn_t *fdt_size); #endif /* _EFI_LOADER_H */ diff --git a/lib/efi_loader/efi_bootmgr.c b/lib/efi_loader/efi_bootmgr.c index 304ed43595c..589d3996b68 100644 --- a/lib/efi_loader/efi_bootmgr.c +++ b/lib/efi_loader/efi_bootmgr.c @@ -1277,7 +1277,7 @@ efi_status_t efi_bootmgr_run(void *fdt) if (fdt_lo) fdt = fdt_lo; if (!fdt) { - efi_load_distro_fdt(&fdt_distro, &fdt_size); + efi_load_distro_fdt(handle, &fdt_distro, &fdt_size); fdt = fdt_distro; } } diff --git a/lib/efi_loader/efi_fdt.c b/lib/efi_loader/efi_fdt.c index 86ba00c2bdd..4ccf2055be3 100644 --- a/lib/efi_loader/efi_fdt.c +++ b/lib/efi_loader/efi_fdt.c @@ -75,28 +75,34 @@ int efi_get_distro_fdt_name(char *fname, int size, int seq) /** * efi_load_distro_fdt() - load distro device-tree * + * @handle: handle of loaded image * @fdt: on return device-tree, must be freed via efi_free_pages() * @fdt_size: buffer size */ -void efi_load_distro_fdt(void **fdt, efi_uintn_t *fdt_size) +void efi_load_distro_fdt(efi_handle_t handle, void **fdt, efi_uintn_t *fdt_size) { - struct efi_device_path *rem, *dp; + struct efi_device_path *dp; efi_status_t ret; + struct efi_handler *handler; + struct efi_loaded_image *loaded_image; efi_handle_t device; *fdt = NULL; - dp = efi_get_dp_from_boot(NULL); - if (!dp) - return; - device = efi_dp_find_obj(dp, NULL, &rem); - ret = efi_search_protocol(device, &efi_simple_file_system_protocol_guid, - NULL); + /* Get boot device from loaded image protocol */ + ret = efi_search_protocol(handle, &efi_guid_loaded_image, &handler); if (ret != EFI_SUCCESS) - goto err; - memcpy(rem, &END, sizeof(END)); + return; + loaded_image = handler->protocol_interface; + device = loaded_image->device_handle; - /* try the various available names */ + /* Get device path of boot device */ + ret = efi_search_protocol(device, &efi_guid_device_path, &handler); + if (ret != EFI_SUCCESS) + return; + dp = handler->protocol_interface; + + /* Try the various available names */ for (int seq = 0; ; ++seq) { struct efi_device_path *file; char buf[255]; @@ -108,10 +114,9 @@ void efi_load_distro_fdt(void **fdt, efi_uintn_t *fdt_size) break; ret = efi_load_image_from_path(true, file, fdt, fdt_size); efi_free_pool(file); - if (ret == EFI_SUCCESS) + if (ret == EFI_SUCCESS) { + log_debug("Fdt %pD loaded\n", file); break; + } } - -err: - efi_free_pool(dp); } From c72a163e545d3f34d30c0384f1f47aa2de66f08f Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sun, 14 Jul 2024 09:18:04 +0200 Subject: [PATCH 04/20] doc: move out-of-tree building info to HTML Move the information about out-of-tree building from README to the generated HTML documentation. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- README | 20 -------------------- doc/build/gcc.rst | 28 ++++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/README b/README index b89768f1791..b76449b70a8 100644 --- a/README +++ b/README @@ -1684,26 +1684,6 @@ images ready for download to / installation on your system: - "u-boot" is an image in ELF binary format - "u-boot.srec" is in Motorola S-Record format -By default the build is performed locally and the objects are saved -in the source directory. One of the two methods can be used to change -this behavior and build U-Boot to some external directory: - -1. Add O= to the make command line invocations: - - make O=/tmp/build distclean - make O=/tmp/build NAME_defconfig - make O=/tmp/build all - -2. Set environment variable KBUILD_OUTPUT to point to the desired location: - - export KBUILD_OUTPUT=/tmp/build - make distclean - make NAME_defconfig - make all - -Note that the command line "O=" setting overrides the KBUILD_OUTPUT environment -variable. - User specific CPPFLAGS, AFLAGS and CFLAGS can be passed to the compiler by setting the according environment variables KCPPFLAGS, KAFLAGS and KCFLAGS. For example to treat all compiler warnings as errors: diff --git a/doc/build/gcc.rst b/doc/build/gcc.rst index 3c646577272..d8fcfdc4bf2 100644 --- a/doc/build/gcc.rst +++ b/doc/build/gcc.rst @@ -118,6 +118,34 @@ Assuming cross compiling on Debian for ARMv8 this would be CROSS_COMPILE=aarch64-linux-gnu- make +Out-of-tree building +~~~~~~~~~~~~~~~~~~~~ + +By default building is performed locally and the objects are saved in the source +directory. To build out-out-tree use one of the two methods below: + +Add O= parameter to the make command line: + +.. code-block:: bash + + make O=/tmp/build distclean + make O=/tmp/build NAME_defconfig + make O=/tmp/build + +Use environment variable KBUILD_OUTPUT: + +.. code-block:: bash + + export KBUILD_OUTPUT=/tmp/build + make distclean + make NAME_defconfig + make + +.. note:: + + The command line "O=" parameter overrides the KBUILD_OUTPUT environment + variable. + Build parameters ~~~~~~~~~~~~~~~~ From ff47fddf72189e1adfc94a143455f8717369e3c0 Mon Sep 17 00:00:00 2001 From: Michal Simek Date: Tue, 16 Jul 2024 15:56:51 +0200 Subject: [PATCH 05/20] efi_loader: Fix typo in EFI_RT_VOLATILE_STORE description Fix typo in EFI_RT_VOLATILE_STORE description. Fixes: c28d32f946f0 ("efi_loader: conditionally enable SetvariableRT") Signed-off-by: Michal Simek --- lib/efi_loader/Kconfig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/efi_loader/Kconfig b/lib/efi_loader/Kconfig index 2fb24d7af9a..38e64af2531 100644 --- a/lib/efi_loader/Kconfig +++ b/lib/efi_loader/Kconfig @@ -67,7 +67,7 @@ config EFI_RT_VOLATILE_STORE depends on EFI_VARIABLE_FILE_STORE help When EFI variables are stored on file we don't allow SetVariableRT, - since the OS doesn't know how to write that file. At he same time + since the OS doesn't know how to write that file. At the same time we copy runtime variables in DRAM and support GetVariableRT Enable this option to allow SetVariableRT on the RAM backend of From df86796028df6bd98e57f568016c9e346d0f6abb Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Tue, 16 Jul 2024 21:04:23 +0200 Subject: [PATCH 06/20] doc: enable ReadTheDocs addon management Up to now ReadTheDocs has been injecting code when building on their platform. This includes for instance improvements for the search function. To maintain the current output ReadTheDocs requires setting html_baseurl and html_context in conf.py. See: https://about.readthedocs.com/blog/2024/07/addons-by-default/ Signed-off-by: Heinrich Schuchardt Reviewed-by: Tom Rini --- doc/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index c9138a5a5d4..e79134cc3d7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -21,6 +21,12 @@ from subprocess import check_output # Get Sphinx version major, minor, patch = sphinx.version_info[:3] +# Set canonical URL from the Read the Docs Domain +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "") + +# Tell Jinja2 templates the build is running on Read the Docs +if os.environ.get("READTHEDOCS", "") == "True": + html_context["READTHEDOCS"] = True # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the From d5b6800374e73e1b50422baa290814ddb7d69e6c Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:51 +0100 Subject: [PATCH 07/20] MAINTAINERS: Rename BOOTDEVICE Rename this to BOOTSTD which is the normal name for the feature. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index 19ca57d200b..f9953944483 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -918,7 +918,7 @@ F: drivers/block/blkmap.c F: include/blkmap.h F: test/dm/blkmap.c -BOOTDEVICE +BOOTSTD M: Simon Glass S: Maintained F: boot/bootdev*.c From c684db989e86cc041da30114c4d7f8d549260875 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:52 +0100 Subject: [PATCH 08/20] doc: Move bootstd into its own directory Before adding more files, move the bootstd docs into a new directory, with an index. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- MAINTAINERS | 2 +- doc/board/starfive/milk-v_mars_cm.rst | 2 +- doc/develop/board_best_practices.rst | 2 +- doc/develop/bootstd/index.rst | 9 +++++++++ doc/develop/{bootstd.rst => bootstd/overview.rst} | 14 +++++++------- doc/develop/index.rst | 2 +- doc/usage/cmd/bootdev.rst | 2 +- doc/usage/cmd/bootflow.rst | 2 +- doc/usage/cmd/bootmeth.rst | 2 +- doc/usage/environment.rst | 2 +- 10 files changed, 24 insertions(+), 15 deletions(-) create mode 100644 doc/develop/bootstd/index.rst rename doc/develop/{bootstd.rst => bootstd/overview.rst} (99%) diff --git a/MAINTAINERS b/MAINTAINERS index f9953944483..a6e47e8a217 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -927,7 +927,7 @@ F: boot/bootmeth*.c F: boot/bootstd.c F: cmd/bootdev.c F: cmd/bootflow.c -F: doc/develop/bootstd.rst +F: doc/develop/bootstd/ F: doc/usage/bootdev.rst F: doc/usage/bootflow.rst F: doc/usage/bootmeth.rst diff --git a/doc/board/starfive/milk-v_mars_cm.rst b/doc/board/starfive/milk-v_mars_cm.rst index b31de6043bb..52d4e5e9098 100644 --- a/doc/board/starfive/milk-v_mars_cm.rst +++ b/doc/board/starfive/milk-v_mars_cm.rst @@ -89,7 +89,7 @@ provide a default value. The variable *$fdtfile* is used in the boot process to automatically load a device-tree provided by the operating system. For details of the boot -process refer to the :doc:`U-Boot Standard Boot <../../../develop/bootstd>` +process refer to the :doc:`/develop/bootstd/index` description. Boot source selection diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst index f44401eab7d..09632c80ce7 100644 --- a/doc/develop/board_best_practices.rst +++ b/doc/develop/board_best_practices.rst @@ -7,7 +7,7 @@ In addition to the regular best practices such as using :doc:`checkpatch` and following the :doc:`docstyle` and the :doc:`codingstyle` there are some things which are specific to creating a new board port. -* Implement :doc:`bootstd` to ensure that most operating systems will be +* Implement :doc:`bootstd/index` to ensure that most operating systems will be supported by the platform. * The platform defconfig file must be generated via `make savedefconfig`. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst new file mode 100644 index 00000000000..f4f87c7787c --- /dev/null +++ b/doc/develop/bootstd/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Standard Boot +============= + +.. toctree:: + :maxdepth: 2 + + overview diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst similarity index 99% rename from doc/develop/bootstd.rst rename to doc/develop/bootstd/overview.rst index bdda90fae3f..aa38ad9a0ea 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd/overview.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0+: -U-Boot Standard Boot -==================== +Standard Boot Overview +====================== Introduction ------------ @@ -17,7 +17,7 @@ introduces the following concepts: For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible for creating a bootflow for each kernel combination that it wants to offer. These bootflows are stored on media so they can be discovered by U-Boot. This -feature is typically called `distro boot` (see :doc:`distro`) because it is +feature is typically called `distro boot` (see :doc:`../distro`) because it is a way for distributions to boot on any hardware. Traditionally U-Boot has relied on scripts to implement this feature. See @@ -32,7 +32,7 @@ way to boot with U-Boot. The feature is extensible to different Operating Systems (such as Chromium OS) and devices (beyond just block and network devices). It supports EFI boot and EFI bootmgr too. -Finally, standard boot supports the operation of :doc:`vbe`. +Finally, standard boot supports the operation of :doc:`../vbe`. Bootflow -------- @@ -432,16 +432,16 @@ Three commands are available: `bootdev` Allows listing of available bootdevs, selecting a particular one and - getting information about it. See :doc:`../usage/cmd/bootdev` + getting information about it. See :doc:`/usage/cmd/bootdev` `bootflow` Allows scanning one or more bootdevs for bootflows, listing available bootflows, selecting one, obtaining information about it and booting it. - See :doc:`../usage/cmd/bootflow` + See :doc:`/usage/cmd/bootflow` `bootmeth` Allow listing of available bootmethds and setting the order in which they - are tried. See :doc:`../usage/cmd/bootmeth` + are tried. See :doc:`/usage/cmd/bootmeth` .. _BootflowStates: diff --git a/doc/develop/index.rst b/doc/develop/index.rst index f9c4bf839ee..c0107a783fc 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -29,7 +29,7 @@ Implementation directories bloblist - bootstd + bootstd/index ci_testing commands config_binding diff --git a/doc/usage/cmd/bootdev.rst b/doc/usage/cmd/bootdev.rst index f759abab354..98a0f43c580 100644 --- a/doc/usage/cmd/bootdev.rst +++ b/doc/usage/cmd/bootdev.rst @@ -22,7 +22,7 @@ Description The `bootdev` command is used to manage bootdevs. It can list available bootdevs, select one and obtain information about it. -See :doc:`../../develop/bootstd` for more information about bootdevs in general. +See :doc:`/develop/bootstd/index` for more information about bootdevs in general. bootdev list diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst index 6519e4880a9..5d41fe37a7a 100644 --- a/doc/usage/cmd/bootflow.rst +++ b/doc/usage/cmd/bootflow.rst @@ -26,7 +26,7 @@ Description The `bootflow` command is used to manage bootflows. It can scan bootdevs to locate bootflows, list them and boot them. -See :doc:`../../develop/bootstd` for more information. +See :doc:`/develop/bootstd/index` for more information. Note that `CONFIG_BOOTSTD_FULL` (which enables `CONFIG_CMD_BOOTFLOW_FULL) must be enabled to obtain full functionality with this command. Otherwise, it only diff --git a/doc/usage/cmd/bootmeth.rst b/doc/usage/cmd/bootmeth.rst index bac9fdf85cd..c3d2ec1574b 100644 --- a/doc/usage/cmd/bootmeth.rst +++ b/doc/usage/cmd/bootmeth.rst @@ -21,7 +21,7 @@ Description The `bootmeth` command is used to manage bootmeths. It can list them and change the order in which they are used. -See :doc:`../../develop/bootstd` for more information. +See :doc:`/develop/bootstd/index` for more information. .. _bootmeth_order: diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst index 7d4b448cb30..cc33d3ec0f2 100644 --- a/doc/usage/environment.rst +++ b/doc/usage/environment.rst @@ -100,7 +100,7 @@ to add environment variables. Board maintainers are encouraged to migrate to the text-based environment as it is easier to maintain. The distro-board script still requires the old-style -environments, so use :doc:`../develop/bootstd` instead. +environments, so use :doc:`/develop/bootstd/index` instead. List of environment variables From 1426f672d254a92202c1e50ad21b7dd4c8e9641a Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:53 +0100 Subject: [PATCH 09/20] doc: Mention automatic binding of bootmeths Add a note about how bootmeth drivers are instantiated. Signed-off-by: Simon Glass Reviewed-by: Mattijs Korpershoek Suggested-by: Heinrich Schuchardt --- doc/develop/bootstd/overview.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index aa38ad9a0ea..e04c683fb11 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -424,6 +424,9 @@ Bootmeth drivers are provided for: - EFI boot using boot manager - Android bootflow (boot image v4) +Each driver is controlled by a Kconfig option. If no bootmeth driver is +selected by a compatible string in the devicetree, all available bootmeth +drivers are bound automatically. Command interface ----------------- From b1bb34fecd84a1754e0e187aa2735ecfd2910ffd Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:54 +0100 Subject: [PATCH 10/20] doc: Add a description for bootmeth_extlinux Add documentation for the extlinux bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/extlinux.rst | 28 ++++++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 4 ++-- 3 files changed, 31 insertions(+), 2 deletions(-) create mode 100644 doc/develop/bootstd/extlinux.rst diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst new file mode 100644 index 00000000000..46e9ad9eea1 --- /dev/null +++ b/doc/develop/bootstd/extlinux.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Extlinux Bootmeth +================= + +`Extlinux `_ +(sometimes called syslinux) allows U-Boot to provide a menu of available +operating systems from which the user can choose. + +U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of +a list of named operating systems along with the kernel, initial ramdisk and +other settings. The file is stored in the `extlinux/` subdirectory, possibly +under the `boot/` subdirectory. This list of prefixes (``{"/", "/boot"}`` by +default) can be selected with the `filename-prefixes` property in the bootstd +device. + +Note that the PXE bootmeth uses the same file format, but in a network context. + +When invoked on a bootdev, this bootmeth searches for the file and creates a +bootflow if found. + +When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up +the context, then ``pxe_process()`` to process the file. Depending on the +contents, this may boot an operating system or provide a list of options to +the user, perhaps with a timeout. + +The compatible string "u-boot,extlinux" is used for the driver. It is present +if `CONFIG_BOOTMETH_EXTLINUX` is enabled. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index f4f87c7787c..5bbb3d633a3 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -7,3 +7,4 @@ Standard Boot :maxdepth: 2 overview + extlinux diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index e04c683fb11..26b798596c5 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -414,9 +414,9 @@ a good selection of boot options is available. Available bootmeth drivers -------------------------- -Bootmeth drivers are provided for: +Bootmeth drivers are provided for booting from various media: - - extlinux / syslinux boot from a disk + - :doc:`extlinux / syslinux ` boot from a storage device - extlinux boot from a network (PXE) - U-Boot scripts from disk, network or SPI flash - EFI boot using bootefi from disk From 64a1446bd09ec58ab259c9ec2b3160ac604b734f Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:55 +0100 Subject: [PATCH 11/20] doc: Add a description for bootmeth_pxe Add documentation for the pxe bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/extlinux.rst | 3 ++- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 2 +- doc/develop/bootstd/pxelinux.rst | 27 +++++++++++++++++++++++++++ 4 files changed, 31 insertions(+), 2 deletions(-) create mode 100644 doc/develop/bootstd/pxelinux.rst diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst index 46e9ad9eea1..bf27dc57aaa 100644 --- a/doc/develop/bootstd/extlinux.rst +++ b/doc/develop/bootstd/extlinux.rst @@ -14,7 +14,8 @@ under the `boot/` subdirectory. This list of prefixes (``{"/", "/boot"}`` by default) can be selected with the `filename-prefixes` property in the bootstd device. -Note that the PXE bootmeth uses the same file format, but in a network context. +Note that the :doc:`pxelinux` uses the same file format, but in a +network context. When invoked on a bootdev, this bootmeth searches for the file and creates a bootflow if found. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 5bbb3d633a3..5052afe448f 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -8,3 +8,4 @@ Standard Boot overview extlinux + pxelinux diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 26b798596c5..6afa1c29615 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -417,7 +417,7 @@ Available bootmeth drivers Bootmeth drivers are provided for booting from various media: - :doc:`extlinux / syslinux ` boot from a storage device - - extlinux boot from a network (PXE) + - :doc:`extlinux / syslinux ` boot from a network (PXE) - U-Boot scripts from disk, network or SPI flash - EFI boot using bootefi from disk - VBE diff --git a/doc/develop/bootstd/pxelinux.rst b/doc/develop/bootstd/pxelinux.rst new file mode 100644 index 00000000000..c4b7fbb4c9c --- /dev/null +++ b/doc/develop/bootstd/pxelinux.rst @@ -0,0 +1,27 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +PXE Bootmeth +============ + +PXE (Preboot eXecution-Environment) provides a way to boot an operating system +over a network interface. The PXE bootmeth supports PXELINUX and allows U-Boot to +provide a menu of possible Operating Systems from which the user can choose. + +U-Boot includes a parser for the `extlinux.conf` file described +`here `_. +It consists primarily of a list of named operating systems along with the +kernel, initial ramdisk and other settings. The file is retrieved from a network +server using the TFTP protocol. + +When invoked on a bootdev, this bootmeth searches for the file and creates a +bootflow if found. See +`PXELINUX `_ for +a full description of the search procedure. + +When the bootflow is booted, the bootmeth calls ``pxe_setup_ctx()`` to set up +the context, then ``pxe_process()`` to process the file. Depending on the +contents, this may boot an Operating System or provide a list of options to the +user, perhaps with a timeout. + +The compatible string "u-boot,extlinux-pxe" is used for the driver. It is +present if `CONFIG_BOOTMETH_EXTLINUX_PXE` is enabled. From 70a4982d4fd83d18cd1951b2be9f3e7538b8c499 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:56 +0100 Subject: [PATCH 12/20] doc: Add a description for bootmeth_qfw Add documentation for the qfw bootmeth. Fix up the compatible string to drop the 'extlinux' part, which is not relevant to this bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- boot/bootmeth_qfw.c | 2 +- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + doc/develop/bootstd/qfw.rst | 20 ++++++++++++++++++++ 4 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 doc/develop/bootstd/qfw.rst diff --git a/boot/bootmeth_qfw.c b/boot/bootmeth_qfw.c index dfaa944594e..2f8e00cf350 100644 --- a/boot/bootmeth_qfw.c +++ b/boot/bootmeth_qfw.c @@ -88,7 +88,7 @@ static struct bootmeth_ops qfw_bootmeth_ops = { }; static const struct udevice_id qfw_bootmeth_ids[] = { - { .compatible = "u-boot,qfw-extlinux" }, + { .compatible = "u-boot,qfw-bootmeth" }, { } }; diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 5052afe448f..f8fce7207ce 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -9,3 +9,4 @@ Standard Boot overview extlinux pxelinux + qfw diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 6afa1c29615..ef878963c9e 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -423,6 +423,7 @@ Bootmeth drivers are provided for booting from various media: - VBE - EFI boot using boot manager - Android bootflow (boot image v4) + - :doc:`QFW `: QEMU firmware interface Each driver is controlled by a Kconfig option. If no bootmeth driver is selected by a compatible string in the devicetree, all available bootmeth diff --git a/doc/develop/bootstd/qfw.rst b/doc/develop/bootstd/qfw.rst new file mode 100644 index 00000000000..70086ad1817 --- /dev/null +++ b/doc/develop/bootstd/qfw.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +QFW Bootmeth +============ + +`QEMU `_ is a system emulator which is able to boot +Operating Systems. QEMU provides specific support for booting an OS image +provided on the QEMU command line. + +When invoked on a bootdev for UCLASS_QFW, this bootmeth reads the kernel +provided by the QEMU `-kernel` argument, the initial ramdisk provided by +`-initrd` and the boot arguments (command line) provided by `-append` into +memory ready for booting. + +When the bootflow is booted, the bootmeth tries the `booti` command first, then +falls back to the `bootz` command. U-Boot's 'control' devicetree is passed +through to the kernel. + +The compatible string "u-boot,qfw-bootmeth" is used for the driver. It is +present if `CONFIG_QFW` is enabled. From 56418511e9fd5ca34c38c896a364ea0249c53610 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:57 +0100 Subject: [PATCH 13/20] doc: Add a description for bootmeth_cros Add documentation for the cros bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/cros.rst | 33 ++++++++++++++++++++++++++++++++ doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + 3 files changed, 35 insertions(+) create mode 100644 doc/develop/bootstd/cros.rst diff --git a/doc/develop/bootstd/cros.rst b/doc/develop/bootstd/cros.rst new file mode 100644 index 00000000000..85af10588c1 --- /dev/null +++ b/doc/develop/bootstd/cros.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +ChromiumOS Bootmeth +=================== + +ChromiumOS provides a mechanism for booting its Operating System from a block +device, described +`here `_. + +U-Boot includes support for reading the associated data structures from the +device and identifying a bootable ChromiumOS image. This structure includes the +kernel itself, boot arguments (kernel command line), as well as the x86 setup +block (for x86 only). + +When invoked on a bootdev, this bootmeth searches for kernel partitions with +the appropriate GUID (Globally Unique Identifier). When found, the information +is loaded and a bootflow is created. + +When the bootflow is booted, the bootmeth reads the kernel and boot arguments. +It then boots the kernel using zboot (on x86) or bootm (on ARM). The boot +arguments are adjusted to replace `%U` with the UUID of the selected kernel +partition. This results in the correct root disk being used, which is the next +partition after the kernel partition. + +For ARM, a :doc:`/usage/fit/index` is used. The `CONFIG_FIT_BEST_MATCH` option +must be enabled for U-Boot to select the correct devicetree to boot with. + +Note that a ChromiumOS image typically has two copies of the Operating System, +each with its own kernel and root disk. There is no initial ramdisk (initrd). +This means that this bootmeth typically locates two separate images. + +The compatible string "u-boot,cros" is used for the driver. It is present +if `CONFIG_BOOTMETH_CROS` is enabled. diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index f8fce7207ce..69fd3c2d2eb 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -10,3 +10,4 @@ Standard Boot extlinux pxelinux qfw + cros diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index ef878963c9e..de15fa41a1d 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -421,6 +421,7 @@ Bootmeth drivers are provided for booting from various media: - U-Boot scripts from disk, network or SPI flash - EFI boot using bootefi from disk - VBE + - :doc:`ChromiumOS ` ChromiumOS boot from a disk - EFI boot using boot manager - Android bootflow (boot image v4) - :doc:`QFW `: QEMU firmware interface From 95403023cfa890b4e5e7ce7040227e518b2da288 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:58 +0100 Subject: [PATCH 14/20] doc: Add a description for bootmeth_sandbox Add documentation for the sandbox bootmeth. Fix up the compatible string to drop the 'extlinux' part, which is not relevant to this bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- boot/bootmeth_sandbox.c | 2 +- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 1 + doc/develop/bootstd/sandbox.rst | 17 +++++++++++++++++ 4 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 doc/develop/bootstd/sandbox.rst diff --git a/boot/bootmeth_sandbox.c b/boot/bootmeth_sandbox.c index 0bc8f688e30..26c713bb5f3 100644 --- a/boot/bootmeth_sandbox.c +++ b/boot/bootmeth_sandbox.c @@ -55,7 +55,7 @@ static struct bootmeth_ops sandbox_bootmeth_ops = { }; static const struct udevice_id sandbox_bootmeth_ids[] = { - { .compatible = "u-boot,sandbox-extlinux" }, + { .compatible = "u-boot,sandbox-bootmeth" }, { } }; diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 69fd3c2d2eb..2c5d2d3fade 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -11,3 +11,4 @@ Standard Boot pxelinux qfw cros + sandbox diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index de15fa41a1d..20c5d56aad2 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -425,6 +425,7 @@ Bootmeth drivers are provided for booting from various media: - EFI boot using boot manager - Android bootflow (boot image v4) - :doc:`QFW `: QEMU firmware interface + - :doc:`sandbox ` used only for testing Each driver is controlled by a Kconfig option. If no bootmeth driver is selected by a compatible string in the devicetree, all available bootmeth diff --git a/doc/develop/bootstd/sandbox.rst b/doc/develop/bootstd/sandbox.rst new file mode 100644 index 00000000000..d501518c39a --- /dev/null +++ b/doc/develop/bootstd/sandbox.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Sandbox Bootmeth +================ + +The sandbox bootmeth is only used for testing. It does not provide any facility +for booting an OS. While sandbox can do all the processing before the actual +boot, it is not connected in this bootmeth. + +When invoked on a bootdev, this bootmeth pretends to find a bootflow and creates +the associated structure. + +When the bootflow is booted, the bootmeth returns `-ENOTSUPP` indicating that it +is not supported. + +The compatible string "u-boot,sandbox-bootmeth" is used for the driver. It is present +if `CONFIG_BOOTMETH_SANDBOX` is enabled. From cfed2219e36946902e3bd57d5c647ab8f10f6397 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:30:59 +0100 Subject: [PATCH 15/20] bootstd: Tidy up comments on the boothmeth drivers Fix a typo in the comment and add one to the EFI driver too. Signed-off-by: Simon Glass Reviewed-by: Heinrich Schuchardt Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- boot/bootmeth_efi.c | 1 + boot/bootmeth_extlinux.c | 2 +- boot/bootmeth_script.c | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/boot/bootmeth_efi.c b/boot/bootmeth_efi.c index 5a4c125835a..56a6e47f5b2 100644 --- a/boot/bootmeth_efi.c +++ b/boot/bootmeth_efi.c @@ -394,6 +394,7 @@ static const struct udevice_id distro_efi_bootmeth_ids[] = { { } }; +/* Put a number before 'efi' to provide a default ordering */ U_BOOT_DRIVER(bootmeth_4efi) = { .name = "bootmeth_efi", .id = UCLASS_BOOTMETH, diff --git a/boot/bootmeth_extlinux.c b/boot/bootmeth_extlinux.c index 9b55686948f..fbb05ef928e 100644 --- a/boot/bootmeth_extlinux.c +++ b/boot/bootmeth_extlinux.c @@ -183,7 +183,7 @@ static const struct udevice_id extlinux_bootmeth_ids[] = { { } }; -/* Put an number before 'extlinux' to provide a default ordering */ +/* Put a number before 'extlinux' to provide a default ordering */ U_BOOT_DRIVER(bootmeth_1extlinux) = { .name = "bootmeth_extlinux", .id = UCLASS_BOOTMETH, diff --git a/boot/bootmeth_script.c b/boot/bootmeth_script.c index 0e05d28d4d9..24da47c7259 100644 --- a/boot/bootmeth_script.c +++ b/boot/bootmeth_script.c @@ -250,7 +250,7 @@ static const struct udevice_id script_bootmeth_ids[] = { { } }; -/* Put an number before 'script' to provide a default ordering */ +/* Put a number before 'script' to provide a default ordering */ U_BOOT_DRIVER(bootmeth_2script) = { .name = "bootmeth_script", .id = UCLASS_BOOTMETH, From 60b180fdba1bf7bbd6181c1eef804a20fa485427 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:31:00 +0100 Subject: [PATCH 16/20] bootstd: Correct handling of script from network When reading a script from a network, no block device is available. Update the implementation to support this correctly, avoiding setting environment variables which relate only to block devices. Signed-off-by: Simon Glass Reviewed-by: Mattijs Korpershoek --- boot/bootmeth_script.c | 51 +++++++++++++++++++++++++----------------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/boot/bootmeth_script.c b/boot/bootmeth_script.c index 24da47c7259..c5cbf18c2e6 100644 --- a/boot/bootmeth_script.c +++ b/boot/bootmeth_script.c @@ -185,31 +185,42 @@ static int script_set_bootflow(struct udevice *dev, struct bootflow *bflow, static int script_boot(struct udevice *dev, struct bootflow *bflow) { - struct blk_desc *desc = dev_get_uclass_plat(bflow->blk); + struct blk_desc *desc; ulong addr; int ret = 0; - if (desc->uclass_id == UCLASS_USB) { - ret = env_set("devtype", "usb"); + if (bflow->blk) { + desc = dev_get_uclass_plat(bflow->blk); + if (desc->uclass_id == UCLASS_USB) { + ret = env_set("devtype", "usb"); + } else { + /* + * If the uclass is AHCI, but the driver is ATA + * (not scsi), set devtype to sata + */ + if (IS_ENABLED(CONFIG_SATA) && + desc->uclass_id == UCLASS_AHCI) + ret = env_set("devtype", "sata"); + else + ret = env_set("devtype", blk_get_devtype(bflow->blk)); + } + if (!ret) + ret = env_set_hex("devnum", desc->devnum); + if (!ret) + ret = env_set_hex("distro_bootpart", bflow->part); + if (!ret) + ret = env_set("prefix", bflow->subdir); + if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) && + !strcmp("mmc", blk_get_devtype(bflow->blk))) + ret = env_set_hex("mmc_bootdev", desc->devnum); } else { - /* If the uclass is AHCI, but the driver is ATA - * (not scsi), set devtype to sata - */ - if (IS_ENABLED(CONFIG_SATA) && - desc->uclass_id == UCLASS_AHCI) - ret = env_set("devtype", "sata"); - else - ret = env_set("devtype", blk_get_devtype(bflow->blk)); + const struct udevice *media = dev_get_parent(bflow->dev); + + ret = env_set("devtype", + uclass_get_name(device_get_uclass_id(media))); + if (!ret) + ret = env_set_hex("devnum", dev_seq(media)); } - if (!ret) - ret = env_set_hex("devnum", desc->devnum); - if (!ret) - ret = env_set_hex("distro_bootpart", bflow->part); - if (!ret) - ret = env_set("prefix", bflow->subdir); - if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) && - !strcmp("mmc", blk_get_devtype(bflow->blk))) - ret = env_set_hex("mmc_bootdev", desc->devnum); if (ret) return log_msg_ret("env", ret); From 87d00856df35f7e269dfa1f343035cff33dfea58 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Wed, 17 Jul 2024 09:31:01 +0100 Subject: [PATCH 17/20] doc: Add a description for bootmeth_script Add documentation for the script bootmeth. Signed-off-by: Simon Glass Reviewed-by: Quentin Schulz Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd/index.rst | 1 + doc/develop/bootstd/overview.rst | 2 +- doc/develop/bootstd/script.rst | 52 ++++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 doc/develop/bootstd/script.rst diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst index 2c5d2d3fade..9d35b567d55 100644 --- a/doc/develop/bootstd/index.rst +++ b/doc/develop/bootstd/index.rst @@ -11,4 +11,5 @@ Standard Boot pxelinux qfw cros + script sandbox diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst index 20c5d56aad2..bc7e4b39704 100644 --- a/doc/develop/bootstd/overview.rst +++ b/doc/develop/bootstd/overview.rst @@ -418,7 +418,7 @@ Bootmeth drivers are provided for booting from various media: - :doc:`extlinux / syslinux ` boot from a storage device - :doc:`extlinux / syslinux ` boot from a network (PXE) - - U-Boot scripts from disk, network or SPI flash + - :doc:`U-Boot scripts