colin/u-boot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge tag 'efi-2024-10-rc1-3' of https://source.denx.de/u-boot/custodians/u-boot-efi

Browse Source 
Pull request efi-2024-10-rc1-3

Documentation:

* Move out-of-tree building info to HTML
* Enable ReadTheDocs addon management
* Remove FIT documentation that is elsewhere
* Update table of contents for FIT images
* Add description for more boot methods

UEFI:

* Correct finding distro device-path for media devices
* Fix typo in EFI_RT_VOLATILE_STORE description

Other:

* MAINTAINERS: Rename BOOTDEVICE
This commit is contained in:
Tom Rini
2024-07-19 08:53:23 -06:00
parent 4595600007 38b000881e
commit cb0b7ab607
30 changed files with 353 additions and 773 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
MAINTAINERS
View File

@@ -918,7 +918,7 @@ F: drivers/block/blkmap.c
F: include/blkmap.h
F: test/dm/blkmap.c
BOOTDEVICE
BOOTSTD
M: Simon Glass <sjg@chromium.org>
S: Maintained
F: boot/bootdev*.c
@@ -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

20
README
View File

@@ -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:

3
boot/bootmeth_efi.c
View File

@@ -265,7 +265,7 @@ static int distro_efi_read_bootflow_net(struct bootflow *bflow)
return log_msg_ret("sz", -EINVAL);
bflow->size = size;
/* bootfile should be setup by dhcp*/
/* bootfile should be setup by dhcp */
bootfile_name = env_get("bootfile");
if (!bootfile_name)
return log_msg_ret("bootfile_name", ret);
@@ -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,

2
boot/bootmeth_extlinux.c
View File

@@ -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,

2
boot/bootmeth_qfw.c
View File

@@ -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" },
{ }
};

2
boot/bootmeth_sandbox.c
View File

@@ -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" },
{ }
};

17
boot/bootmeth_script.c
View File

@@ -185,14 +185,17 @@ 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 (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
/*
* If the uclass is AHCI, but the driver is ATA
* (not scsi), set devtype to sata
*/
if (IS_ENABLED(CONFIG_SATA) &&
@@ -210,6 +213,14 @@ static int script_boot(struct udevice *dev, struct bootflow *bflow)
if (!ret && IS_ENABLED(CONFIG_ARCH_SUNXI) &&
!strcmp("mmc", blk_get_devtype(bflow->blk)))
ret = env_set_hex("mmc_bootdev", desc->devnum);
} else {
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)
return log_msg_ret("env", ret);
@@ -250,7 +261,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,

2
doc/board/starfive/milk-v_mars_cm.rst
View File

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

28
doc/build/gcc.rst vendored
View File

@@ -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
~~~~~~~~~~~~~~~~

6
doc/conf.py
View File

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

2
doc/develop/board_best_practices.rst
View File

@@ -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`.

33
doc/develop/bootstd/cros.rst Normal file
View File

@@ -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 <https://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot/>`_.
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.

29
doc/develop/bootstd/extlinux.rst Normal file
View File

@@ -0,0 +1,29 @@
.. SPDX-License-Identifier: GPL-2.0+:
Extlinux Bootmeth
=================
`Extlinux <https://uapi-group.org/specifications/specs/boot_loader_specification>`_
(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 :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.
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.

15
doc/develop/bootstd/index.rst Normal file
View File

@@ -0,0 +1,15 @@
.. SPDX-License-Identifier: GPL-2.0+:
Standard Boot
=============
.. toctree::
:maxdepth: 2
overview
extlinux
pxelinux
qfw
cros
script
sandbox

47
doc/develop/bootstd.rst → doc/develop/bootstd/overview.rst
View File

@@ -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
--------
@@ -410,20 +410,39 @@ You should probably also enable `CONFIG_BOOTSTD_DEFAULTS`, which provides
several filesystem and network features (if `CONFIG_NET` is enabled) so that
a good selection of boot options is available.
Some devicetree properties are supported in the bootstd node when
`CONFIG_BOOTSTD_FULL` is enabled:
filename-prefixes
List of prefixes to use when searching for files on block devices. This
defaults to {"/", "/boot/"} if not provided.
bootdev-order
Lists the bootdev ordering to use. Note that the deprecated
`boot_targets` environment variable overrides this, if present.
theme (subnode)
Sets the theme to use for menus. See :doc:`/develop/expo`.
Available bootmeth drivers
--------------------------
Bootmeth drivers are provided for:
Bootmeth drivers are provided for booting from various media:
- extlinux / syslinux boot from a disk
- extlinux boot from a network (PXE)
- U-Boot scripts from disk, network or SPI flash
- EFI boot using bootefi from disk
- VBE
- EFI boot using boot manager
- Android bootflow (boot image v4)
- :doc:`ChromiumOS <cros>` ChromiumOS boot from a disk
- EFI boot using bootefi from disk
- EFI boot using boot manager
- :doc:`extlinux / syslinux <extlinux>` boot from a storage device
- :doc:`extlinux / syslinux <extlinux>` boot from a network (PXE)
- :doc:`sandbox <sandbox>` used only for testing
- :doc:`U-Boot scripts <script>` from disk, network or SPI flash
- :doc:`QFW <qfw>`: QEMU firmware interface
- :doc:`VBE </develop/vbe>`: Verified Boot for Embedded
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
-----------------
@@ -432,16 +451,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:

27
doc/develop/bootstd/pxelinux.rst Normal file
View File

@@ -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 <https://uapi-group.org/specifications/specs/boot_loader_specification>`_.
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 <https://wiki.syslinux.org/wiki/index.php?title=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.

20
doc/develop/bootstd/qfw.rst Normal file
View File

@@ -0,0 +1,20 @@
.. SPDX-License-Identifier: GPL-2.0+:
QFW Bootmeth
============
`QEMU <hhttps://www.qemu.org/>`_ 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.

17
doc/develop/bootstd/sandbox.rst Normal file
View File

@@ -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.

52
doc/develop/bootstd/script.rst Normal file
View File

@@ -0,0 +1,52 @@
.. SPDX-License-Identifier: GPL-2.0+:
Script Bootmeth
===============
This bootmeth provides a way to locate and run a script on a block or network
device. It can also support SPI flash.
For a block device the file is read from the selected partition, which must use
a supported filesystem. The subdirectory to search in is defined by the bootstd
list of prefixes (``{"/", "/boot"}`` by default) and can be adjust with the
`filename-prefixes` property in the bootstd device.
For a network device, the filename is obtained from the `boot_script_dhcp`
environment variable and the file is read using tftp. It must be in the
top-level directory of the tftp server.
In either case (file or network), the bootmeth searches for the file and creates
a bootflow if found. The bootmeth searches for "boot.scr.uimg" first, then
"boot.scr" if not found.
For SPI flash, a script is read from flash using the offset provided by the
"script_offset_f" environment variable.
Some attempt is made to identify the Operating System: so far this only detects
an `Armbian <https://www.armbian.com>`_
distro. For block devices, if a file called "boot.bmp" exists in the same
directory then it is used as the bootflow logo.
When the bootflow is booted, the bootmeth sets these environment variables:
devtype
device type (e.g. "usb", "mmc", "ethernet" or "spi_flash")
devnum
device number, corresponding to the device 'sequence' number
``dev_seq(dev)``
distro_bootpart
(block devices only) partition number on the device (numbered from 1)
prefix
prefix used to find the file
mmc_bootdev
device number (same as `devnum`), set for sunxi mmc devices only
The script file must be a FIT or a legacy uImage. It is loaded into memory and
executed.
The compatible string "u-boot,script" is used for the driver. It is present
if `CONFIG_BOOTMETH_SCRIPT` is enabled.

2
doc/develop/index.rst
View File

@@ -29,7 +29,7 @@ Implementation
directories
bloblist
bootstd
bootstd/index
ci_testing
commands
config_binding

2
doc/usage/cmd/bootdev.rst
View File

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

2
doc/usage/cmd/bootflow.rst
View File

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

2
doc/usage/cmd/bootmeth.rst
View File

@@ -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:

2
doc/usage/environment.rst
View File

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

27
doc/usage/fit/index.rst
View File

@@ -4,16 +4,29 @@ 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 <https://fitspec.osfw.foundation/>`_.
.. 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

684
doc/usage/fit/source_file_format.rst
View File

@@ -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 <name>, its
private key is stored in <name>.key and the certificate is stored in
<name>.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 <name>, its
private key is stored in <name>.key and the certificate is stored in
<name>.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 <m8@semihalf.com>
.. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
FIT format documentation has been moved to
`a separate project <https://fitspec.osfw.foundation/>`_. Updates to the
format/specification should be submitted there.

2
include/efi_loader.h
View File

@@ -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 */

2
lib/efi_loader/Kconfig
View File

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

2
lib/efi_loader/efi_bootmgr.c
View File

@@ -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;
}
}

35
lib/efi_loader/efi_fdt.c
View File

@@ -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);
}
}