diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.pxe | 292 | ||||
| -rw-r--r-- | doc/android/fastboot.rst | 16 | ||||
| -rw-r--r-- | doc/board/nxp/imx93_frdm.rst | 75 | ||||
| -rw-r--r-- | doc/board/nxp/imx95_evk.rst | 12 | ||||
| -rw-r--r-- | doc/board/nxp/index.rst | 1 | ||||
| -rw-r--r-- | doc/board/qualcomm/debugging.rst | 2 | ||||
| -rw-r--r-- | doc/board/qualcomm/index.rst | 7 | ||||
| -rw-r--r-- | doc/board/qualcomm/iq8.rst | 43 | ||||
| -rw-r--r-- | doc/board/qualcomm/phones.rst | 2 | ||||
| -rw-r--r-- | doc/board/qualcomm/rb3gen2.rst | 2 | ||||
| -rw-r--r-- | doc/board/samsung/e850-96.rst | 85 | ||||
| -rw-r--r-- | doc/board/ti/j784s4_evm.rst | 9 | ||||
| -rw-r--r-- | doc/develop/release_cycle.rst | 6 | ||||
| -rw-r--r-- | doc/develop/uefi/u-boot_on_efi.rst | 18 | ||||
| -rw-r--r-- | doc/git-mailrc | 2 | ||||
| -rw-r--r-- | doc/sphinx/requirements.txt | 4 | ||||
| -rw-r--r-- | doc/usage/fit/signature.rst | 8 | ||||
| -rw-r--r-- | doc/usage/fit/x86-fit-boot.rst | 7 | ||||
| -rw-r--r-- | doc/usage/index.rst | 1 | ||||
| -rw-r--r-- | doc/usage/pxe.rst | 346 |
20 files changed, 597 insertions, 341 deletions
diff --git a/doc/README.pxe b/doc/README.pxe deleted file mode 100644 index ba189080e8c..00000000000 --- a/doc/README.pxe +++ /dev/null @@ -1,292 +0,0 @@ -SPDX-License-Identifier: GPL-2.0+ -/* - * Copyright 2010-2011 Calxeda, Inc. - */ - -The 'pxe' commands provide a near subset of the functionality provided by -the PXELINUX boot loader. This allows U-Boot based systems to be controlled -remotely using the same PXE based techniques that many non U-Boot based servers -use. - -Commands -======== - -pxe get -------- - syntax: pxe get - - follows PXELINUX's rules for retrieving configuration files from a tftp - server, and supports a subset of PXELINUX's config file syntax. - - Environment - ----------- - 'pxe get' requires two environment variables to be set: - - pxefile_addr_r - should be set to a location in RAM large enough to hold - pxe files while they're being processed. Up to 16 config files may be - held in memory at once. The exact number and size of the files varies with - how the system is being used. A typical config file is a few hundred bytes - long. - - bootfile,serverip - these two are typically set in the DHCP response - handler, and correspond to fields in the DHCP response. - - 'pxe get' optionally supports these two environment variables being set: - - ethaddr - this is the standard MAC address for the ethernet adapter in use. - 'pxe get' uses it to look for a configuration file specific to a system's - MAC address. - - pxeuuid - this is a UUID in standard form using lower case hexadecimal - digits, for example, 550e8400-e29b-41d4-a716-446655440000. 'pxe get' uses - it to look for a configuration file based on the system's UUID. - - File Paths - ---------- - 'pxe get' repeatedly tries to download config files until it either - successfully downloads one or runs out of paths to try. The order and - contents of paths it tries mirrors exactly that of PXELINUX - you can - read in more detail about it at: - - http://syslinux.zytor.com/wiki/index.php/Doc/pxelinux - -pxe boot --------- - syntax: pxe boot [pxefile_addr_r] - - Interprets a pxe file stored in memory. - - pxefile_addr_r is an optional argument giving the location of the pxe file. - The file must be terminated with a NUL byte. - - Environment - ----------- - There are some environment variables that may need to be set, depending - on conditions. - - pxefile_addr_r - if the optional argument pxefile_addr_r is not supplied, - an environment variable named pxefile_addr_r must be supplied. This is - typically the same value as is used for the 'pxe get' command. - - bootfile - typically set in the DHCP response handler based on the - same field in the DHCP respone, this path is used to generate the base - directory that all other paths to files retrieved by 'pxe boot' will use. - If no bootfile is specified, paths used in pxe files will be used as is. - - serverip - typically set in the DHCP response handler, this is the IP - address of the tftp server from which other files will be retrieved. - - kernel_addr_r, initrd_addr_r - locations in RAM at which 'pxe boot' will - store the kernel(or FIT image) and initrd it retrieves from tftp. These - locations will be passed to the bootm command to boot the kernel. These - environment variables are required to be set. - - fdt_addr_r - location in RAM at which 'pxe boot' will store the fdt blob it - retrieves from tftp. The retrieval is possible if 'fdt' label is defined in - pxe file and 'fdt_addr_r' is set. If retrieval is possible, 'fdt_addr_r' - will be passed to bootm command to boot the kernel. - - fdt_addr - the location of a fdt blob. 'fdt_addr' will be passed to bootm - command if it is set and 'fdt_addr_r' is not passed to bootm command. - - fdtoverlay_addr_r - location in RAM at which 'pxe boot' will temporarily store - fdt overlay(s) before applying them to the fdt blob stored at 'fdt_addr_r'. - - pxe_label_override - override label to be used, if exists, instead of the - default label. This will allow consumers to choose a pxe label at - runtime instead of having to prompt the user. If "pxe_label_override" is set - but does not exist in the pxe menu, pxe would fallback to the default label if - given, and no failure is returned but rather a warning message. - -pxe file format -=============== -The pxe file format is nearly a subset of the PXELINUX file format; see -http://syslinux.zytor.com/wiki/index.php/PXELINUX. It's composed of one line -commands - global commands, and commands specific to labels. Lines begining -with # are treated as comments. White space between and at the beginning of -lines is ignored. - -The size of pxe files and the number of labels is only limited by the amount -of RAM available to U-Boot. Memory for labels is dynamically allocated as -they're parsed, and memory for pxe files is statically allocated, and its -location is given by the pxefile_addr_r environment variable. The pxe code is -not aware of the size of the pxefile memory and will outgrow it if pxe files -are too large. - -Supported global commands -------------------------- -Unrecognized commands are ignored. - -default <label> - the label named here is treated as the default and is - the first label 'pxe boot' attempts to boot. - -fallback <label> - the label named here is treated as a fallback option that - may be attempted should it be detected that booting of - the default has failed to complete, for example via - U-Boot's boot count limit functionality. - -menu title <string> - sets a title for the menu of labels being displayed. - -menu include <path> - use tftp to retrieve the pxe file at <path>, which - is then immediately parsed as if the start of its - contents were the next line in the current file. nesting - of include up to 16 files deep is supported. - -prompt <flag> - if 1, always prompt the user to enter a label to boot - from. if 0, only prompt the user if timeout expires. - -timeout <num> - wait for user input for <num>/10 seconds before - auto-booting a node. - -label <name> - begin a label definition. labels continue until - a command not recognized as a label command is seen, - or EOF is reached. - -Supported label commands ------------------------- -labels end when a command not recognized as a label command is reached, or EOF. - -menu default - set this label as the default label to boot; this is - the same behavior as the global default command but - specified in a different way - -kernel <path> - if this label is chosen, use tftp to retrieve the kernel - (or FIT image) at <path>. it will be stored at the address - indicated in the kernel_addr_r environment variable, and - that address will be passed to bootm to boot this kernel. - For FIT image, The configuration specification can be - appended to the file name, with the format: - <path>#<conf>[#<extra-conf[#...]] - It will passed to bootm with that address. - (see: doc/uImage.FIT/command_syntax_extensions.txt) - It useful for overlay selection in pxe file - (see: doc/usage/fit/overlay-fdt-boot.rst). - -fdtoverlays <path> [...] - if this label is chosen, use tftp to retrieve the DT - overlay(s) at <path>. it will be temporarily stored at the - address indicated in the fdtoverlay_addr_r environment variable, - and then applied in the load order to the fdt blob stored at the - address indicated in the fdt_addr_r environment variable. - -devicetree-overlay <path> [...] - if this label is chosen, use tftp to retrieve the DT - overlay(s) at <path>. it will be temporarily stored at the - address indicated in the fdtoverlay_addr_r environment variable, - and then applied in the load order to the fdt blob stored at the - address indicated in the fdt_addr_r environment variable. - Alias for fdtoverlays. - -kaslrseed - set this label to request random number from hwrng as kaslr seed. - -append <string> - use <string> as the kernel command line when booting this - label. Environment variable references like ${var} are - substituted before boot. - -initrd <path> - if this label is chosen, use tftp to retrieve the initrd - at <path>. it will be stored at the address indicated in - the initrd_addr_r environment variable, and that address - will be passed to bootm. - For FIT image, the initrd can be provided with the same value than - kernel, including configuration: - <path>#<conf>[#<extra-conf[#...]] - In this case, kernel_addr_r is passed to bootm. - -fdt <path> - if this label is chosen, use tftp to retrieve the fdt blob - at <path>. it will be stored at the address indicated in - the fdt_addr_r environment variable, and that address will - be passed to bootm. - For FIT image, the device tree can be provided with the same value - than kernel, including configuration: - <path>#<conf>[#<extra-conf[#...]] - In this case, kernel_addr_r is passed to bootm. - -devicetree <path> - if this label is chosen, use tftp to retrieve the fdt blob - at <path>. it will be stored at the address indicated in - the fdt_addr_r environment variable, and that address will - be passed to bootm. Alias for fdt. - -fdtdir <path> - if this label is chosen, use tftp to retrieve a fdt blob - relative to <path>. If the fdtfile environment variable - is set, <path>/<fdtfile> is retrieved. Otherwise, the - filename is generated from the soc and board environment - variables, i.e. <path>/<soc>-<board>.dtb is retrieved. - If the fdt command is specified, fdtdir is ignored. - -localboot <flag> - Run the command defined by "localcmd" in the environment. - <flag> is ignored and is only here to match the syntax of - PXELINUX config files. - -Example -------- -Here's a couple of example files to show how this works. - -------------/tftpboot/pxelinux.cfg/menus/base.menu----------- -menu title Linux selections - -# This is the default label -label install - menu label Default Install Image - kernel kernels/install.bin - append console=ttyAMA0,38400 debug earlyprintk - initrd initrds/uzInitrdDebInstall - -# Just another label -label linux-2.6.38 - kernel kernels/linux-2.6.38.bin - append root=/dev/sdb1 - -# The locally installed kernel -label local - menu label Locally installed kernel - append root=/dev/sdb1 - localboot 1 -------------------------------------------------------------- - -------------/tftpboot/pxelinux.cfg/default------------------- -menu include pxelinux.cfg/menus/base.menu -timeout 500 - -default linux-2.6.38 -------------------------------------------------------------- - -When a pxe client retrieves and boots the default pxe file, -'pxe boot' will wait for user input for 5 seconds before booting -the linux-2.6.38 label, which will cause /tftpboot/kernels/linux-2.6.38.bin -to be downloaded, and boot with the command line "root=/dev/sdb1" - -Differences with PXELINUX -========================= -The biggest difference between U-Boot's pxe and PXELINUX is that since -U-Boot's pxe support is written entirely in C, it can run on any platform -with network support in U-Boot. Here are some other differences between -PXELINUX and U-Boot's pxe support. - -- U-Boot's pxe does not support the PXELINUX DHCP option codes specified - in RFC 5071, but could be extended to do so. - -- when U-Boot's pxe fails to boot, it will return control to U-Boot, - allowing another command to run, other U-Boot command, instead of resetting - the machine like PXELINUX. - -- U-Boot's pxe doesn't rely on or provide an UNDI/PXE stack in memory, it - only uses U-Boot. - -- U-Boot's pxe doesn't provide the full menu implementation that PXELINUX - does, only a simple text based menu using the commands described in - this README. With PXELINUX, it's possible to have a graphical boot - menu, submenus, passwords, etc. U-Boot's pxe could be extended to support - a more robust menuing system like that of PXELINUX's. - -- U-Boot's pxe expects U-Boot uimg's as kernels. Anything that would work - with the 'bootm' command in U-Boot could work with the 'pxe boot' command. - -- U-Boot's pxe only recognizes a single file on the initrd command line. It - could be extended to support multiple. - -- in U-Boot's pxe, the localboot command doesn't necessarily cause a local - disk boot - it will do whatever is defined in the 'localcmd' env - variable. And since it doesn't support a full UNDI/PXE stack, the - type field is ignored. - -- the interactive prompt in U-Boot's pxe only allows you to choose a label - from the menu. If you want to boot something not listed, you can ctrl+c - out of 'pxe boot' and use existing U-Boot commands to accomplish it. diff --git a/doc/android/fastboot.rst b/doc/android/fastboot.rst index 6f92cd28eb1..19e2ee9d407 100644 --- a/doc/android/fastboot.rst +++ b/doc/android/fastboot.rst @@ -32,7 +32,7 @@ The following OEM commands are supported (if enabled): - ``oem console`` - this dumps U-Boot console record buffer - ``oem board`` - this executes a custom board function which is defined by the vendor -Support for both eMMC and NAND devices is included. +Support for eMMC, NAND and SPI flash memory devices is included. Client installation ------------------- @@ -97,8 +97,9 @@ Raw partition descriptors ^^^^^^^^^^^^^^^^^^^^^^^^^ In cases where no partition table is present, a raw partition descriptor can be -defined, specifying the offset, size, and optionally the MMC hardware partition -number for a given partition name. +defined, specifying the memory offset and size. + +Currently, this support is available only for eMMC and SPI flash memory devices. This is useful when using fastboot to flash files (e.g. SPL or U-Boot) to a specific offset in the eMMC boot partition, without having to update the entire @@ -106,6 +107,15 @@ boot partition. To define a raw partition descriptor, add an environment variable similar to:: + fastboot_raw_partition_<raw partition name>=<offset> <size> + +for example:: + + fastboot_raw_partition_boot=0x100 0x1f00 + +Optionally, in the eMMC case, the hardware partition number can also be +specified for a given partition name:: + fastboot_raw_partition_<raw partition name>=<offset> <size> [mmcpart <num>] for example:: diff --git a/doc/board/nxp/imx93_frdm.rst b/doc/board/nxp/imx93_frdm.rst new file mode 100644 index 00000000000..a1f526fd4cc --- /dev/null +++ b/doc/board/nxp/imx93_frdm.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +imx93_frdm +========== + +U-Boot for the NXP i.MX93 FRDM board + +Quick Start +----------- + +- Get and Build the ARM Trusted firmware +- Get the DDR firmware +- Get ahab-container.img +- Build U-Boot +- Boot from the SD card + +Get and Build the ARM Trusted firmware +-------------------------------------- + +Note: srctree is U-Boot source directory +Get ATF from: https://github.com/nxp-imx/imx-atf/ +branch: lf_v2.8 + +.. code-block:: bash + + $ unset LDFLAGS + $ make PLAT=imx93 bl31 + $ cp build/imx93/release/bl31.bin $(srctree) + +Get the DDR firmware +-------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.21.bin + $ chmod +x firmware-imx-8.21.bin + $ ./firmware-imx-8.21.bin + $ cp firmware-imx-8.21/firmware/ddr/synopsys/lpddr4*.bin $(srctree) + +Get ahab-container.img +---------------------- + +.. code-block:: bash + + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-sentinel-0.11.bin + $ chmod +x firmware-sentinel-0.11.bin + $ ./firmware-sentinel-0.11.bin + $ cp firmware-sentinel-0.11/mx93a1-ahab-container.img $(srctree) + +Build U-Boot +------------ + +.. code-block:: bash + + $ export CROSS_COMPILE=aarch64-poky-linux- + $ make imx93_frdm_defconfig + $ make + +Copy the flash.bin binary to the MicroSD card at offset 32KB: + +.. code-block:: bash + + $ dd if=flash.bin of=/dev/sd[x] bs=1k seek=32; sync + +Boot from the SD card +--------------------- + +- Configure SW1 boot switches to SD boot mode: + 0011 SW1[3:0] - ("USDHC2 4-bit SD3.0" Boot Mode) +- Insert the SD card in the SD slot (P13) of the board. +- Connect a USB Type-C cable into the P16 Debug USB Port and connect + using a terminal emulator at 115200 bps, 8n1. The console will show up + at /dev/ttyACM0. +- Power on the board by connecting a USB Type-C cable into the P1 + Power USB Port. diff --git a/doc/board/nxp/imx95_evk.rst b/doc/board/nxp/imx95_evk.rst index 9121f7561ab..27cd15eb7c9 100644 --- a/doc/board/nxp/imx95_evk.rst +++ b/doc/board/nxp/imx95_evk.rst @@ -23,9 +23,9 @@ Note: srctree is U-Boot source directory .. code-block:: bash - $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-ele-imx-1.3.0-17945fc.bin - $ sh firmware-ele-imx-1.3.0-17945fc.bin --auto-accept - $ cp firmware-ele-imx-1.3.0-17945fc/mx95a0-ahab-container.img $(srctree) + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-ele-imx-2.0.2-89161a8.bin + $ sh firmware-ele-imx-2.0.2-89161a8.bin --auto-accept + $ cp firmware-ele-imx-2.0.2-89161a8/mx95b0-ahab-container.img $(srctree) Get DDR PHY Firmware Images -------------------------------------- @@ -34,9 +34,9 @@ Note: srctree is U-Boot source directory .. code-block:: bash - $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.26-d4c33ab.bin - $ sh firmware-imx-8.26-d4c33ab.bin --auto-accept - $ cp firmware-imx-8.26-d4c33ab/firmware/ddr/synopsys/lpddr5*v202311.bin $(srctree) + $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.28-994fa14.bin + $ sh firmware-imx-8.28-994fa14.bin --auto-accept + $ cp firmware-imx-8.28-994fa14/firmware/ddr/synopsys/lpddr5*v202409.bin $(srctree) Get and Build OEI Images -------------------------------------- diff --git a/doc/board/nxp/index.rst b/doc/board/nxp/index.rst index e7ec725cc04..aa7d857346d 100644 --- a/doc/board/nxp/index.rst +++ b/doc/board/nxp/index.rst @@ -15,6 +15,7 @@ NXP Semiconductors imx91_11x11_evk imx93_9x9_qsb imx93_11x11_evk + imx93_frdm imx95_evk imxrt1020-evk imxrt1050-evk diff --git a/doc/board/qualcomm/debugging.rst b/doc/board/qualcomm/debugging.rst index 1c35d1909d1..c3289c9e4e3 100644 --- a/doc/board/qualcomm/debugging.rst +++ b/doc/board/qualcomm/debugging.rst @@ -1,5 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0+ -.. sectionauthor:: Caleb Connolly <caleb.connolly@linaro.org> +.. sectionauthor:: Casey Connolly <casey.connolly@linaro.org> Qualcomm debugging ================== diff --git a/doc/board/qualcomm/index.rst b/doc/board/qualcomm/index.rst index ccf834208e9..3238a68e859 100644 --- a/doc/board/qualcomm/index.rst +++ b/doc/board/qualcomm/index.rst @@ -6,10 +6,11 @@ Qualcomm .. toctree:: :maxdepth: 2 + board + debugging dragonboard410c - rb3gen2 dragonwing - board + rb3gen2 + iq8 phones - debugging rdp diff --git a/doc/board/qualcomm/iq8.rst b/doc/board/qualcomm/iq8.rst new file mode 100644 index 00000000000..f3df0ee00bc --- /dev/null +++ b/doc/board/qualcomm/iq8.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. sectionauthor:: Balaji Selvanathan <balaji.selvanathan@oss.qualcomm.com> + +Qualcomm DragonWing IQ8 +======================================== + +The Dragonwing IQ8 Series (which includes QCS8300) powers computeheavy and AI-based devices, and is designed +to operate in an expanded temperature range with available built-in safety features. +Dragonwing IQ8 Series delivers industrial-grade AI performance of up to 40 TOPS, an octa-core +Qualcomm Kryo Gen 6 CPU, a powerful Qualcomm Adreno 623 GPU, support for +up to 12 concurrent cameras, and 4K video encode and decode alongside multiple displays. + +More information can be found on the `Qualcomm's IQ8 product page`_. + +.. _Qualcomm's IQ8 product page: https://docs.qualcomm.com/bundle/publicresource/87-83839-1_REV_A_Qualcomm_IQ8_Series_Product_Brief________.pdf + +Installation +------------ +First, setup ``CROSS_COMPILE`` for aarch64. Then, build U-Boot for ``QCS8300``:: + + $ export CROSS_COMPILE=<aarch64 toolchain prefix> + $ make qcom_qcs8300_defconfig + $ make -j8 u-boot.mbn + +This will build the signed ``u-boot.mbn`` in the configured output directory. +The firmware expects firmware ELF images to be "signed". The signature +does not provide any security in this case, but it provides the firmware +with some required metadata. + +Then flash the resulting ``u-boot.mbn`` to the ``uefi_a`` partition +on your device with ``fastboot flash uefi_a u-boot.mbn``. + +U-Boot should be running after a reboot (``fastboot reboot``). + +Note that fastboot is not yet supported in U-Boot on Dragonwing IQ8, as a result, to flash +back the original firmware, or new versoins of the U-Boot, EDL mode must be used. + +A tool like bkerler's `edl`_ can be used for flashing. + +$ edl.py --loader /path/to/prog_firehose_ddr.elf w uefi_a u-boot.mbn + +.. _qtestsign: https://github.com/msm8916-mainline/qtestsign +.. _edl: https://github.com/bkerler/edl diff --git a/doc/board/qualcomm/phones.rst b/doc/board/qualcomm/phones.rst index 1d27196cf54..8afc7587731 100644 --- a/doc/board/qualcomm/phones.rst +++ b/doc/board/qualcomm/phones.rst @@ -1,5 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0+ -.. sectionauthor:: Caleb Connolly <caleb.connolly@linaro.org> +.. sectionauthor:: Casey Connolly <casey.connolly@linaro.org> ====================================== Booting U-Boot on Qualcomm smartphones diff --git a/doc/board/qualcomm/rb3gen2.rst b/doc/board/qualcomm/rb3gen2.rst index 4240606224f..518d01c4c3a 100644 --- a/doc/board/qualcomm/rb3gen2.rst +++ b/doc/board/qualcomm/rb3gen2.rst @@ -1,5 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0+ -.. sectionauthor:: Caleb Connolly <caleb.connolly@linaro.org> +.. sectionauthor:: Casey Connolly <casey.connolly@linaro.org> Qualcomm Robotics RB3 Gen 2 =========================== diff --git a/doc/board/samsung/e850-96.rst b/doc/board/samsung/e850-96.rst index 0a7b6fc0c9d..b435fa8b353 100644 --- a/doc/board/samsung/e850-96.rst +++ b/doc/board/samsung/e850-96.rst @@ -43,17 +43,19 @@ Legend: BL31 in terms of ARM boot flow * ``LDFW``: Loadable Firmware -Build Procedure +Unbricking Note --------------- -.. warning:: - At the moment USB is not enabled in U-Boot for this board. Although eMMC is - enabled, you won't be able to flash images over USB (fastboot). So flashing - U-Boot binary **WILL** effectively brick your board. The ``dltool`` [8]_ can - be used then to perform USB boot and flash LittleKernel bootloader binary [7]_ - to unbrick and revive the board. Flashing U-Boot binary might be helpful for - developers or anybody who want to check current state of U-Boot enablement on - E850-96 (which is mostly serial console, eMMC and related blocks). +In case the board is bricked for some reason, the ``dltool`` [8]_ can be used to +unbrick and revive it. This tool performs USB boot, and uploads the LittleKernel +bootloader over USB, which is then being executed on the board. The loaded +bootloader further enters fastboot mode, so that the user can flash the +functional bootloader binary (U-Boot or LittleKernel [7]_) to eMMC using +``fastboot`` tool. Please read the ``dltool`` README file for more details about +the procedure. + +Build Procedure +--------------- Build U-Boot binary from source code (using AArch64 baremetal GCC toolchain): @@ -64,8 +66,9 @@ Build U-Boot binary from source code (using AArch64 baremetal GCC toolchain): make e850-96_defconfig make -Boot E850-96 board into fastboot mode as described in board software doc [9]_, -and flash U-Boot binary into ``bootloader`` eMMC partition: +The original E850-96 board is shipped with LittleKernel-based bootloader flashed +in eMMC. To replace it with U-Boot, boot into fastboot mode (as described in +the board software documentation [9]_), and flash U-Boot binary: .. prompt:: bash $ @@ -74,6 +77,66 @@ and flash U-Boot binary into ``bootloader`` eMMC partition: U-Boot will boot up to the shell. +Flashing +-------- + +User area of eMMC contains GPT partition table (either Linux or Android). Boot +Partition A (``mmc0boot0``) contains all firmware/bootloaders. Boot Partition +B (``mmc0boot1``) contains U-Boot environment. + +First make sure to format eMMC accordingly. Prepare the initial environment: + +.. prompt:: bash => + + env default -f -a + env save + +For Linux, just format eMMC using default ``$partitions`` definitions: + +.. prompt:: bash => + + gpt write mmc 0 $partitions + +For Android, use ``$partitions_android`` instead: + +.. prompt:: bash => + + setenv partitions_linux $partitions + setenv partitions $partitions_android + env save + gpt write mmc 0 $partitions + +In case of Linux, there are two partitions available: ``esp`` (EFI System +Partition) and ``rootfs``. It is recommended to use fastboot to flash images to +those partitions. Enter fastboot mode on your device: + +.. prompt:: bash => + + fastboot usb 0 + +And then flash the images: + +.. prompt:: bash $ + + fastboot flash esp esp.img + fastboot flash rootfs rootfs.img + +To update the firmware, it's easier to use DFU. Enter DFU mode on the board: + +.. prompt:: bash => + + dfu 0 mmc 0 + +To update U-Boot: + +.. prompt:: bash $ + + dfu-util -D u-boot.bin -a bootloader + +It's also possible to use fastboot to flash the whole ``mmc0boot0`` HW +partition, but it's not so straightforward, as one have to prepare the image for +the whole ``boot0`` partition containing all firmware binaries first. + References ---------- diff --git a/doc/board/ti/j784s4_evm.rst b/doc/board/ti/j784s4_evm.rst index 349fb394d74..22442874110 100644 --- a/doc/board/ti/j784s4_evm.rst +++ b/doc/board/ti/j784s4_evm.rst @@ -90,6 +90,15 @@ Set the variables corresponding to this platform: export OPTEE_PLATFORM=k3-j784s4 export OPTEE_EXTRA_ARGS="CFG_CONSOLE_UART=0x8" +.. note:: + + For AM69-SK, use the following U_BOOT_CFG instead: + + .. prompt:: bash + + export UBOOT_CFG_CORTEXR=am69_sk_r5_defconfig + export UBOOT_CFG_CORTEXA=am69_sk_a72_defconfig + .. j784s4_evm_rst_include_start_build_steps 1. Trusted Firmware-A diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst index f2ffcf3d331..7aa36166a5d 100644 --- a/doc/develop/release_cycle.rst +++ b/doc/develop/release_cycle.rst @@ -55,7 +55,7 @@ Current Status * U-Boot v2025.07 was released on Monday, 07 July 2025. -* The Merge Window for the next release (|next_ver|) is **open** until the -rc1 +* The Merge Window for the next release (|next_ver|) is **closed** with the -rc1 release on Monday, 28 July 2025. * The next branch is now **closed** until the -rc2 release on Monday, 11 August @@ -69,9 +69,9 @@ Future Releases .. The following commented out dates are for when release candidates are planned to be tagged. -.. For the next scheduled release, release candidates were made on:: +For the next scheduled release, release candidates were made on:: -.. * U-Boot |next_ver|-rc1 was released on Mon 28 July 2025. +* U-Boot |next_ver|-rc1 was released on Mon 28 July 2025. .. * U-Boot |next_ver|-rc2 was released on Mon 11 August 2025. diff --git a/doc/develop/uefi/u-boot_on_efi.rst b/doc/develop/uefi/u-boot_on_efi.rst index 245b4af1fa3..177e887ebd9 100644 --- a/doc/develop/uefi/u-boot_on_efi.rst +++ b/doc/develop/uefi/u-boot_on_efi.rst @@ -45,15 +45,15 @@ First choose a board that has EFI support and obtain an EFI implementation for that board. It will be either 32-bit or 64-bit. Alternatively, you can opt for using QEMU [1] and the OVMF [2], as detailed below. -To build U-Boot as an EFI application, enable CONFIG_EFI and CONFIG_EFI_APP. -The efi-x86_app32 and efi-x86_app64 configs are set up for this. Just build -U-Boot as normal, e.g.:: +To build U-Boot as an EFI application, enable CONFIG_EFI_CLIENT and +CONFIG_EFI_APP. The efi-x86_app32 and efi-x86_app64 configs are set up for +this. Just build U-Boot as normal, e.g.:: make efi-x86_app32_defconfig make To build U-Boot as an EFI payload (32-bit or 64-bit EFI can be used), enable -CONFIG_EFI, CONFIG_EFI_STUB, and select either CONFIG_EFI_STUB_32BIT or +CONFIG_EFI_CLIENT, CONFIG_EFI_STUB, and select either CONFIG_EFI_STUB_32BIT or CONFIG_EFI_STUB_64BIT. The efi-x86_payload configs (efi-x86_payload32_defconfig and efi-x86_payload32_defconfig) are set up for this. Then build U-Boot as normal, e.g.:: @@ -113,7 +113,7 @@ implemented completely differently. EFI Application ~~~~~~~~~~~~~~~ For the application the whole of U-Boot is built as a shared library. The -efi_main() function is in lib/efi/efi_app.c. It sets up some basic EFI +efi_main() function is in lib/efi_client/efi_app.c. It sets up some basic EFI functions with efi_init(), sets up U-Boot global_data, allocates memory for U-Boot's malloc(), etc. and enters the normal init sequence (board_init_f() and board_init_r()). @@ -121,7 +121,7 @@ and board_init_r()). Since U-Boot limits its memory access to the allocated regions very little special code is needed. The CONFIG_EFI_APP option controls a few things that need to change so 'git grep CONFIG_EFI_APP' may be instructive. -The CONFIG_EFI option controls more general EFI adjustments. +The CONFIG_EFI_CLIENT option controls more general EFI adjustments. The only available driver is the serial driver. This calls back into EFI 'boot services' to send and receive characters. Although it is implemented @@ -149,7 +149,7 @@ image (including device tree) into a small EFI stub application responsible for booting it. The stub application is built as a normal EFI application except that it has a lot of data attached to it. -The stub application is implemented in lib/efi/efi_stub.c. The efi_main() +The stub application is implemented in lib/efi_client/efi_stub.c. The efi_main() function is called by EFI. It is responsible for copying U-Boot from its original location into memory, disabling EFI boot services and starting U-Boot. U-Boot then starts as normal, relocates, starts all drivers, etc. @@ -192,7 +192,7 @@ careful to build the correct one so that your UEFI firmware can start it. Most UEFI images are 64-bit at present. The payload stub can be build as either 32- or 64-bits. Only a small amount -of code is built this way (see the extra- line in lib/efi/Makefile). +of code is built this way (see the extra- line in lib/efi_client/Makefile). Everything else is built as a normal U-Boot, so is always 32-bit on x86 at present. @@ -353,7 +353,7 @@ This work could be extended in a number of ways: Where is the code? ------------------ -lib/efi +lib/efi_client payload stub, application, support code. Mostly arch-neutral arch/x86/cpu/efi diff --git a/doc/git-mailrc b/doc/git-mailrc index 1982785f60e..747ceda3307 100644 --- a/doc/git-mailrc +++ b/doc/git-mailrc @@ -13,7 +13,7 @@ alias u-boot uboot alias abiessmann Andreas Bießmann <andreas@biessmann.org> alias abrodkin Alexey Brodkin <alexey.brodkin@synopsys.com> alias afleming Andy Fleming <afleming@gmail.com> -alias ag Anatolij Gustschin <agust@denx.de> +alias ag Anatolij Gustschin <ag.dev.uboot@gmail.com> alias agraf Alexander Graf <agraf@csgraf.de> alias alexnemirovsky Alex Nemirovsky <alex.nemirovsky@cortina-access.com> alias alisonwang Alison Wang <alison.wang@nxp.com> diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 12c5772684d..8572c15ef68 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -10,7 +10,7 @@ MarkupSafe==3.0.2 packaging==24.1 pip==24.2 Pygments==2.18.0 -requests==2.32.3 +requests==2.32.4 six==1.16.0 snowballstemmer==2.2.0 Sphinx==8.1.3 @@ -24,4 +24,4 @@ sphinxcontrib-jquery==4.1 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==2.0.0 sphinxcontrib-serializinghtml==2.0.0 -urllib3==2.2.3 +urllib3==2.5.0 diff --git a/doc/usage/fit/signature.rst b/doc/usage/fit/signature.rst index b868dcbf9fd..e5b5a8432e9 100644 --- a/doc/usage/fit/signature.rst +++ b/doc/usage/fit/signature.rst @@ -433,16 +433,14 @@ CONFIG_LEGACY_IMAGE_FORMAT Testing ------- -An easy way to test signing and verification is to use the test script -provided in test/vboot/vboot_test.sh. This uses sandbox (a special version +An easy way to test signing and verification is to use the vboot tests +provided in the pytest suite. This uses sandbox (a special version of U-Boot which runs under Linux) to show the operation of a 'bootm' command loading and verifying images. A sample run is show below:: - $ make O=sandbox sandbox_config - $ make O=sandbox - $ O=sandbox ./test/vboot/vboot_test.sh + $ ./test/py/test.py --bd sandbox --build -k vboot Simple Verified Boot Test diff --git a/doc/usage/fit/x86-fit-boot.rst b/doc/usage/fit/x86-fit-boot.rst index 9e3e32204d5..18704af3bac 100644 --- a/doc/usage/fit/x86-fit-boot.rst +++ b/doc/usage/fit/x86-fit-boot.rst @@ -259,11 +259,12 @@ Why Bother? References ---------- -In the Linux kernel, Documentation/x86/boot.txt defines the boot protocol for +In the Linux kernel, `Documentation/arch/x86/boot.rst +<https://docs.kernel.org/arch/x86/boot.html>`_ defines the boot protocol for the kernel including the setup.bin format. This is handled in U-Boot in arch/x86/lib/zimage.c and arch/x86/lib/bootm.c. -Various files in the same directory as this file describe the FIT format. - +The FIT file format is described in the `Flattened Image Tree Specification +<https://fitspec.osfw.foundation/>`_. .. sectionauthor:: Simon Glass <sjg@chromium.org> 7-Oct-2014 diff --git a/doc/usage/index.rst b/doc/usage/index.rst index e9e0bd04e05..b9de87a6ed9 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -12,6 +12,7 @@ Use U-Boot fit/index netconsole partitions + pxe cmdline semihosting measured_boot diff --git a/doc/usage/pxe.rst b/doc/usage/pxe.rst new file mode 100644 index 00000000000..c2dc11f218d --- /dev/null +++ b/doc/usage/pxe.rst @@ -0,0 +1,346 @@ +.. SPDX-License-Identifier: GPL-2.0+ + Copyright 2010-2011 Calxeda, Inc. + +PXE Boot and extlinux.conf +========================== + +The ``pxe`` commands provide a near subset of the functionality +provided by the PXELINUX boot loader. This allows U-Boot based systems +to be controlled remotely using the same PXE based techniques that +many non U-Boot based servers use. + +The ``sysboot`` command and Extlinux boot method use the same file +format as PXE boot for ``extlinux.conf``. + +Commands +-------- + +``pxe get`` + **Syntax:** ``pxe get`` + + follows PXELINUX's rules for retrieving configuration files + from a tftp server, and supports a subset of PXELINUX's config + file syntax. It requires certain environment variables to be + set, see the Environment section below. + + **File Paths** + + ``pxe get`` repeatedly tries to download config files until it + either successfully downloads one or runs out of paths to + try. The order and contents of paths it tries mirrors exactly + that of PXELINUX - you can read in more detail about it at: + + http://syslinux.zytor.com/wiki/index.php/Doc/pxelinux + +``pxe boot`` + **Syntax:** ``pxe boot [pxefile_addr_r]`` + + Interprets a pxe file stored in memory. + + ``pxefile_addr_r`` is an optional argument giving the location + of the pxe file. The file must be terminated with a NUL byte. + + There are some environment variables that may need to be set, + depending on conditions, see the Environment section below. + +``sysboot`` + **Syntax:** ``sysboot [-p] <interface> <dev[:part]> <ext2|fat|any> [addr] [filename]`` + + Load and boot an ``extlinux.conf`` file from a local + filesystem. Paths in the ``extlinux.conf`` file (kernel, + initrd, FDT and overlays) will be interpreted within that + filesystem. + + Example: + + ``sysboot mmc 0.0:2 any ${pxefile_addr_r} /boot/extlinux.conf`` + +Environment +----------- + +``pxefile_addr_r`` + Should be set to a location in RAM large enough to hold pxe + files while they're being processed. Up to 16 config files may + be held in memory at once. The exact number and size of the + files varies with how the system is being used. A typical + config file is a few hundred bytes long. Required for ``pxe + get``, for ``pxe boot`` if the optional argument + ``pxefile_addr_r`` is not supplied. + +``bootfile`` + Typically set in the DHCP response handler, required for ``pxe + get``. For ``pxe boot``, this path is used to generate the + base directory that all other paths to files retrieved by + ``pxe boot`` will use. If no bootfile is specified, paths used + in pxe files will be used as is. + +``serverip`` + Typically set in the DHCP response handler, this is the IP + address of the tftp server from which other files will be + retrieved. Required for ``pxe get``. + +``kernel_addr_r``, ``initrd_addr_r`` + Locations in RAM to store the kernel (or FIT image) and + initrd. These locations will be passed to the ``bootm`` + command to boot the kernel. These environment variables are + required to be set. + +``fdt_addr_r`` + Location in RAM to store the retrieved fdt blob. Retrieval is + possible if ``fdt`` label is defined in pxe file and + ``fdt_addr_r`` is set. If retrieval is possible, + ``fdt_addr_r`` will be passed to ``bootm`` command to boot the + kernel. + +``fdt_addr`` + Location of a fdt blob. ``fdt_addr`` will be passed to + ``bootm`` command if it is set and ``fdt_addr_r`` is not + passed to bootm command. + +``fdtoverlay_addr_r`` + Location in RAM to temporarily store fdt overlay(s) before + applying them to the fdt blob stored at + ``fdt_addr_r``. Required to use the ``fdtoverlays`` command in + the PXE file. + +``pxe_label_override`` + Override label to be used, if exists, instead of the default + label. This will allow consumers to choose a pxe label at + runtime instead of having to prompt the user. If + ``pxe_label_override`` is set but does not exist in the pxe + menu, pxe would fallback to the default label if given, and no + failure is returned but rather a warning message. + +``ethaddr`` + This is the standard MAC address for the ethernet adapter in + use. ``pxe get`` uses it to look for a configuration file + specific to a system's MAC address. + +``pxeuuid`` + This is a UUID in standard form using lower case hexadecimal + digits, for example, + 550e8400-e29b-41d4-a716-446655440000. ``pxe get`` uses it to + look for a configuration file based on the system's UUID. + +pxe file format +--------------- + +The pxe file format is nearly a subset of the PXELINUX file format; +see http://syslinux.zytor.com/wiki/index.php/PXELINUX. It's composed +of one line commands - global commands, and commands specific to +labels. Lines beginning with # are treated as comments. White space +between and at the beginning of lines is ignored. + +The size of pxe files and the number of labels is only limited by the amount +of RAM available to U-Boot. Memory for labels is dynamically allocated as +they're parsed, and memory for pxe files is statically allocated, and its +location is given by the pxefile_addr_r environment variable. The pxe code is +not aware of the size of the pxefile memory and will outgrow it if pxe files +are too large. + +Supported global commands +^^^^^^^^^^^^^^^^^^^^^^^^^ +Unrecognized commands are ignored. + +``default <label>`` + The label named here is treated as the default and is the + first label 'pxe boot' attempts to boot. + +``fallback <label>`` + The label named here is treated as a fallback option that may + be attempted should it be detected that booting of the default + has failed to complete, for example via U-Boot's boot count + limit functionality. + +``menu title <string>`` + Sets a title for the menu of labels being displayed. + +``menu include <path>`` + Use tftp to retrieve the pxe file at ``<path>``, which is then + immediately parsed as if the start of its contents were the + next line in the current file. nesting of include up to 16 + files deep is supported. + +``prompt <flag>`` + If 1, always prompt the user to enter a label to boot from. If + 0, only prompt the user if timeout expires. + +``timeout <num>`` + Wait for user input for <num>/10 seconds before auto-booting a + node. + +``label <name>`` + Begin a label definition. Labels continue until a command not + recognized as a label command is seen, or EOF is reached. + +Supported label commands +^^^^^^^^^^^^^^^^^^^^^^^^ +Labels end when a command not recognized as a label command is reached, or EOF. + +``menu default`` + set this label as the default label to boot; this is the same + behavior as the global default command but specified in a + different way + +``kernel <path>`` + If this label is chosen, use tftp to retrieve the kernel (or + FIT image) at ``<path>``. it will be stored at the address + indicated in the ``kernel_addr_r`` environment variable, and + that address will be passed to ``bootm`` to boot this + kernel. For FIT image, the configuration specification can be + appended to the file name, with the format: + + ``<path>#<conf>[#<extra-conf[#...]]`` + + It will be passed to bootm with that address (see: + doc/uImage.FIT/command_syntax_extensions.txt). It is useful + for overlay selection in pxe file (see + :doc:`./fit/overlay-fdt-boot`). + +``fdtoverlays <path> [...]`` + If this label is chosen, use tftp to retrieve the DT + overlay(s) at ``<path>``. It will be temporarily stored at the + address indicated in the ``fdtoverlay_addr_r`` environment + variable, and then applied in the load order to the fdt blob + stored at the address indicated in the ``fdt_addr_r`` + environment variable. + +``devicetree-overlay <path> [...]`` + if this label is chosen, use tftp to retrieve the DT + overlay(s) at ``<path>``. It will be temporarily stored at the + address indicated in the ``fdtoverlay_addr_r`` environment + variable, and then applied in the load order to the fdt blob + stored at the address indicated in the ``fdt_addr_r`` + environment variable. Alias for fdtoverlays. + +``kaslrseed`` + set this label to request random number from hwrng as kaslr seed. + +``append <string>`` + Use ``<string>`` as the kernel command line when booting this + label. Environment variable references like ``${var}`` are + substituted before boot. + +``initrd <path>`` + If this label is chosen, use tftp to retrieve the initrd at + ``<path>``. it will be stored at the address indicated in the + ``initrd_addr_r`` environment variable, and that address will + be passed to ``bootm``. For FIT image, the initrd can be + provided with the same value than kernel, including + configuration: + + ``<path>#<conf>[#<extra-conf[#...]]`` + + In this case, ``kernel_addr_r`` is passed to ``bootm``. + +``fdt <path>`` + If this label is chosen, use tftp to retrieve the fdt blob at + ``<path>``. It will be stored at the address indicated in the + ``fdt_addr_r`` environment variable, and that address will be + passed to ``bootm``. For FIT image, the device tree can be + provided with the same value than kernel, including + configuration: + + ``<path>#<conf>[#<extra-conf[#...]]`` + + In this case, ``kernel_addr_r`` is passed to ``bootm``. + +``devicetree <path>`` + If this label is chosen, use tftp to retrieve the fdt blob at + ``<path>``. it will be stored at the address indicated in the + ``fdt_addr_r`` environment variable, and that address will be + passed to ``bootm``. Alias for fdt. + +``fdtdir <path>`` + If this label is chosen, use tftp to retrieve a fdt blob + relative to ``<path>``. If the ``fdtfile`` environment + variable is set, ``<path>/<fdtfile>`` is retrieved. Otherwise, + the filename is generated from the ``soc`` and ``board`` + environment variables, i.e. ``<path>/<soc>-<board>.dtb`` is + retrieved. If the ``fdt`` command is specified, ``fdtdir`` is + ignored. + +``localboot <flag>`` + Run the command defined by ``localcmd`` in the + environment. ``<flag>`` is ignored and is only here to match + the syntax of PXELINUX config files. + +Example +------- +Here's a couple of example files to show how this works. + +.. code-block:: + :caption: /tftpboot/pxelinux.cfg/menus/base.menu + + menu title Linux selections + + # This is the default label + label install + menu label Default Install Image + kernel kernels/install.bin + append console=ttyAMA0,38400 debug earlyprintk + initrd initrds/uzInitrdDebInstall + + # Just another label + label linux-2.6.38 + kernel kernels/linux-2.6.38.bin + append root=/dev/sdb1 + + # The locally installed kernel + label local + menu label Locally installed kernel + append root=/dev/sdb1 + localboot 1 + +.. code-block:: + :caption: /tftpboot/pxelinux.cfg/default + + menu include pxelinux.cfg/menus/base.menu + timeout 500 + + default linux-2.6.38 + +When a pxe client retrieves and boots the default pxe file, ``pxe +boot`` will wait for user input for 5 seconds before booting the +``linux-2.6.38`` label, which will cause +``/tftpboot/kernels/linux-2.6.38.bin`` to be downloaded, and boot with +the command line ``root=/dev/sdb1`` + +Differences with PXELINUX +------------------------- + +The biggest difference between U-Boot's pxe and PXELINUX is that since +U-Boot's pxe support is written entirely in C, it can run on any platform +with network support in U-Boot. Here are some other differences between +PXELINUX and U-Boot's pxe support. + +- U-Boot's pxe does not support the PXELINUX DHCP option codes specified + in RFC 5071, but could be extended to do so. + +- when U-Boot's pxe fails to boot, it will return control to U-Boot, + allowing another command to run, other U-Boot command, instead of resetting + the machine like PXELINUX. + +- U-Boot's pxe doesn't rely on or provide an UNDI/PXE stack in memory, it + only uses U-Boot. + +- U-Boot's pxe doesn't provide the full menu implementation that PXELINUX + does, only a simple text based menu using the commands described in + this README. With PXELINUX, it's possible to have a graphical boot + menu, submenus, passwords, etc. U-Boot's pxe could be extended to support + a more robust menuing system like that of PXELINUX's. + +- U-Boot's pxe expects U-Boot uimg's as kernels. Anything that would work + with the 'bootm' command in U-Boot could work with the 'pxe boot' command. + +- U-Boot's pxe only recognizes a single file on the initrd command line. It + could be extended to support multiple. + +- in U-Boot's pxe, the localboot command doesn't necessarily cause a local + disk boot - it will do whatever is defined in the 'localcmd' env + variable. And since it doesn't support a full UNDI/PXE stack, the + type field is ignored. + +- the interactive prompt in U-Boot's pxe only allows you to choose a label + from the menu. If you want to boot something not listed, you can ctrl+c + out of 'pxe boot' and use existing U-Boot commands to accomplish it. |