[PATCH 2/2] binman: Remove pre-generated entries.rst and bintools.rst
Simon Glass
sjg at chromium.org
Wed Mar 18 14:23:57 CET 2026
These files are now auto-generated by the binman_docs Sphinx extension
during the doc build, so the committed copies and their symlinks in
doc/develop/package/ are no longer needed.
Update binman.rst to reference the Sphinx extension instead of the
manual generation commands.
Signed-off-by: Simon Glass <sjg at chromium.org>
---
doc/develop/package/bintools.rst | 1 -
doc/develop/package/entries.rst | 1 -
tools/binman/binman.rst | 12 +-
tools/binman/bintools.rst | 249 ---
tools/binman/entries.rst | 3129 ------------------------------
5 files changed, 4 insertions(+), 3388 deletions(-)
delete mode 120000 doc/develop/package/bintools.rst
delete mode 120000 doc/develop/package/entries.rst
delete mode 100644 tools/binman/bintools.rst
delete mode 100644 tools/binman/entries.rst
diff --git a/doc/develop/package/bintools.rst b/doc/develop/package/bintools.rst
deleted file mode 120000
index 7ef3d75e935..00000000000
--- a/doc/develop/package/bintools.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../tools/binman/bintools.rst
\ No newline at end of file
diff --git a/doc/develop/package/entries.rst b/doc/develop/package/entries.rst
deleted file mode 120000
index ecedcebaad4..00000000000
--- a/doc/develop/package/entries.rst
+++ /dev/null
@@ -1 +0,0 @@
-../../../tools/binman/entries.rst
\ No newline at end of file
diff --git a/tools/binman/binman.rst b/tools/binman/binman.rst
index 3f725868c8b..366491089ad 100644
--- a/tools/binman/binman.rst
+++ b/tools/binman/binman.rst
@@ -1369,10 +1369,8 @@ the following is produced::
Entry Documentation
===================
-For details on the various entry types supported by binman and how to use them,
-see entries.rst which is generated from the source code using:
-
- binman entry-docs >tools/binman/entries.rst
+For details on the various entry types supported by binman and how to use
+them, see entries.rst (auto-generated from the source code).
.. toctree::
:maxdepth: 2
@@ -1638,10 +1636,8 @@ To select a custom directory, use the ``--tooldir`` option.
Bintool Documentation
=====================
-To provide details on the various bintools supported by binman, bintools.rst is
-generated from the source code using:
-
- binman bintool-docs >tools/binman/bintools.rst
+To provide details on the various bintools supported by binman, bintools.rst
+is auto-generated from the source code.
.. toctree::
:maxdepth: 2
diff --git a/tools/binman/bintools.rst b/tools/binman/bintools.rst
deleted file mode 100644
index 9f6cab544a5..00000000000
--- a/tools/binman/bintools.rst
+++ /dev/null
@@ -1,249 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0+
-
-Binman bintool Documentation
-============================
-
-This file describes the bintools (binary tools) supported by binman. Bintools
-are binman's name for external executables that it runs to generate or process
-binaries. It is fairly easy to create new bintools. Just add a new file to the
-'btool' directory. You can use existing bintools as examples.
-
-
-
-Bintool: bootgen: Generate bootable fsbl image for zynq/zynqmp
---------------------------------------------------------------
-
-This bintools supports running Xilinx "bootgen" in order
-to generate a bootable, authenticated image form an SPL.
-
-
-
-
-Bintool: bzip2: Compression/decompression using the bzip2 algorithm
--------------------------------------------------------------------
-
-This bintool supports running `bzip2` to compress and decompress data, as
-used by binman.
-
-It is also possible to fetch the tool, which uses `apt` to install it.
-
-Documentation is available via::
-
- man bzip2
-
-
-
-Bintool: cbfstool: Coreboot filesystem (CBFS) tool
---------------------------------------------------
-
-This bintool supports creating new CBFS images and adding files to an
-existing image, i.e. the features needed by binman.
-
-It also supports fetching a binary cbfstool, since building it from source
-is fairly slow.
-
-Documentation about CBFS is at https://www.coreboot.org/CBFS
-
-
-
-Bintool: cst: Image generation for U-Boot
------------------------------------------
-
-This bintool supports running `cst` with some basic parameters as
-needed by binman.
-
-cst (imx code signing tool) is used for sigining bootloader binaries for
-various i.MX SoCs.
-
-See `Code Signing Tool Users Guide`_ for more information.
-
-.. _`Code Signing Tool Users Guide`:
- https://community.nxp.com/pwmxy87654/attachments/pwmxy87654/imx-processors/202591/1/CST_UG.pdf
-
-
-
-Bintool: fdt_add_pubkey: Add public key to control dtb (spl or u-boot proper)
------------------------------------------------------------------------------
-
-This bintool supports running `fdt_add_pubkey`.
-
-Normally mkimage adds signature information to the control dtb. However
-binman images are built independent from each other. Thus it is required
-to add the public key separately from mkimage.
-
-
-
-Bintool: fdtgrep: Handles the 'fdtgrep' tool
---------------------------------------------
-
-This bintool supports running `fdtgrep` with parameters suitable for
-producing SPL devicetrees from the main one.
-
-
-
-Bintool: fiptool: Image generation for ARM Trusted Firmware
------------------------------------------------------------
-
-This bintool supports running `fiptool` with some basic parameters as
-neeed by binman.
-
-It also supports build fiptool from source.
-
-fiptool provides a way to package firmware in an ARM Trusted Firmware
-Firmware Image Package (ATF FIP) format. It is used with Trusted Firmware A,
-for example.
-
-See `TF-A FIP tool documentation`_ for more information.
-
-.. _`TF-A FIP tool documentation`:
- https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/tools-build.html?highlight=fiptool#building-and-using-the-fip-tool
-
-
-
-Bintool: futility: Handles the 'futility' tool
-----------------------------------------------
-
-futility (flash utility) is a tool for working with Chromium OS flash
-images. This Bintool implements just the features used by Binman, related to
-GBB creation and firmware signing.
-
-A binary version of the tool can be fetched.
-
-See `Chromium OS vboot documentation`_ for more information.
-
-.. _`Chromium OS vboot documentation`:
- https://chromium.googlesource.com/chromiumos/platform/vboot/+/refs/heads/main/_vboot_reference/README
-
-
-
-Bintool: gzip: Compression/decompression using the gzip algorithm
------------------------------------------------------------------
-
-This bintool supports running `gzip` to compress and decompress data, as
-used by binman.
-
-It is also possible to fetch the tool, which uses `apt` to install it.
-
-Documentation is available via::
-
- man gzip
-
-
-
-Bintool: ifwitool: Handles the 'ifwitool' tool
-----------------------------------------------
-
-This bintool supports running `ifwitool` with some basic parameters as
-neeed by binman. It includes creating a file from a FIT as well as adding,
-replacing, deleting and extracting subparts.
-
-The tool is built as part of U-Boot, but a binary version can be fetched if
-required.
-
-ifwitool provides a way to package firmware in an Intel Firmware Image
-(IFWI) file on some Intel SoCs, e.g. Apolo Lake.
-
-
-
-Bintool: lz4: Compression/decompression using the LZ4 algorithm
----------------------------------------------------------------
-
-This bintool supports running `lz4` to compress and decompress data, as
-used by binman.
-
-It is also possible to fetch the tool, which uses `apt` to install it.
-
-Documentation is available via::
-
- man lz4
-
-
-
-Bintool: lzma_alone: Compression/decompression using the LZMA algorithm
------------------------------------------------------------------------
-
-This bintool supports running `lzma_alone` to compress and decompress data,
-as used by binman.
-
-It is also possible to fetch the tool, which uses `apt` to install it.
-
-Documentation is available via::
-
- man lzma_alone
-
-
-
-Bintool: lzop: Compression/decompression using the lzop algorithm
------------------------------------------------------------------
-
-This bintool supports running `lzop` to compress and decompress data, as
-used by binman.
-
-It is also possible to fetch the tool, which uses `apt` to install it.
-
-Documentation is available via::
-
- man lzop
-
-
-
-Bintool: mkeficapsule: Handles the 'mkeficapsule' tool
-------------------------------------------------------
-
-This bintool is used for generating the EFI capsules. The
-capsule generation parameters can either be specified through
-commandline, or through a config file.
-
-
-
-Bintool: mkimage: Image generation for U-Boot
----------------------------------------------
-
-This bintool supports running `mkimage` with some basic parameters as
-needed by binman.
-
-Normally binman uses the mkimage built by U-Boot. But when run outside the
-U-Boot build system, binman can use the version installed in your system.
-Support is provided for fetching this on Debian-like systems, using apt.
-
-
-
-Bintool: openssl: openssl tool
-------------------------------
-
-This bintool supports creating new openssl certificates.
-
-It also supports fetching a binary openssl
-
-Documentation about openssl is at https://www.openssl.org/
-
-
-
-Bintool: xz: Compression/decompression using the xz algorithm
--------------------------------------------------------------
-
-This bintool supports running `xz` to compress and decompress data, as
-used by binman.
-
-It is also possible to fetch the tool, which uses `apt` to install it.
-
-Documentation is available via::
-
- man xz
-
-
-
-Bintool: zstd: Compression/decompression using the zstd algorithm
------------------------------------------------------------------
-
-This bintool supports running `zstd` to compress and decompress data, as
-used by binman.
-
-It is also possible to fetch the tool, which uses `apt` to install it.
-
-Documentation is available via::
-
- man zstd
-
-
-
diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst
deleted file mode 100644
index a81fcbd3891..00000000000
--- a/tools/binman/entries.rst
+++ /dev/null
@@ -1,3129 +0,0 @@
-Binman Entry Documentation
-==========================
-
-This file describes the entry types supported by binman. These entry types can
-be placed in an image one by one to build up a final firmware image. It is
-fairly easy to create new entry types. Just add a new file to the 'etype'
-directory. You can use the existing entries as examples.
-
-Note that some entries are subclasses of others, using and extending their
-features to produce new behaviours.
-
-
-
-.. _etype_alternates_fdt:
-
-Entry: alternates-fdt: Entry that generates alternative sections for each devicetree provided
----------------------------------------------------------------------------------------------
-
-When creating an image designed to boot on multiple models, each model
-requires its own devicetree. This entry deals with selecting the correct
-devicetree from a directory containing them. Each one is read in turn, then
-used to produce section contents which are written to a file. This results
-in a number of images, one for each model.
-
-For example this produces images for each .dtb file in the 'dtb' directory::
-
- alternates-fdt {
- fdt-list-dir = "dtb";
- filename-pattern = "NAME.bin";
- fdt-phase = "tpl";
-
- section {
- u-boot-tpl {
- };
- };
- };
-
-Each output file is named based on its input file, so an input file of
-`model1.dtb` results in an output file of `model1.bin` (i.e. the `NAME` in
-the `filename-pattern` property is replaced with the .dtb basename).
-
-Note that this entry type still produces contents for the 'main' image, in
-that case using the normal dtb provided to Binman, e.g. `u-boot-tpl.dtb`.
-But that image is unlikely to be useful, since it relates to whatever dtb
-happened to be the default when U-Boot builds
-(i.e. `CONFIG_DEFAULT_DEVICE_TREE`). However, Binman ensures that the size
-of each of the alternates is the same as the 'default' one, so they can in
-principle be 'slotted in' to the appropriate place in the main image.
-
-The optional `fdt-phase` property indicates the phase to build. In this
-case, it etype runs fdtgrep to obtain the devicetree subset for that phase,
-respecting the `bootph-xxx` tags in the devicetree.
-
-
-
-.. _etype_atf_bl1:
-
-Entry: atf-bl1: AP Trusted ROM (TF-A) BL1 blob
------------------------------------------------------
-
-Properties / Entry arguments:
- - atf-bl1-path: Filename of file to read into entry. This is typically
- called bl1.bin
-
-This entry holds the AP Trusted ROM firmware typically used by an SoC to
-help initialize the SoC before the SPL or U-Boot is started. See
-https://github.com/TrustedFirmware-A/trusted-firmware-a for more information
-about Boot Loader stage 1 (BL1) or about Trusted Firmware (TF-A)
-
-
-
-.. _etype_atf_bl31:
-
-Entry: atf-bl31: ARM Trusted Firmware (ATF) BL31 blob
------------------------------------------------------
-
-Properties / Entry arguments:
- - atf-bl31-path: Filename of file to read into entry. This is typically
- called bl31.bin or bl31.elf
-
-This entry holds the run-time firmware, typically started by U-Boot SPL.
-See the U-Boot README for your architecture or board for how to use it. See
-https://github.com/TrustedFirmware-A/trusted-firmware-a for more information
-about ATF.
-
-
-
-.. _etype_atf_fip:
-
-Entry: atf-fip: ARM Trusted Firmware's Firmware Image Package (FIP)
--------------------------------------------------------------------
-
-A FIP_ provides a way to group binaries in a firmware image, used by ARM's
-Trusted Firmware A (TF-A) code. It is a simple format consisting of a
-table of contents with information about the type, offset and size of the
-binaries in the FIP. It is quite similar to FMAP, with the major difference
-that it uses UUIDs to indicate the type of each entry.
-
-Note: It is recommended to always add an fdtmap to every image, as well as
-any FIPs so that binman and other tools can access the entire image
-correctly.
-
-The UUIDs correspond to useful names in `fiptool`, provided by ATF to
-operate on FIPs. Binman uses these names to make it easier to understand
-what is going on, although it is possible to provide a UUID if needed.
-
-The contents of the FIP are defined by subnodes of the atf-fip entry, e.g.::
-
- atf-fip {
- soc-fw {
- filename = "bl31.bin";
- };
-
- scp-fwu-cfg {
- filename = "bl2u.bin";
- };
-
- u-boot {
- fip-type = "nt-fw";
- };
- };
-
-This describes a FIP with three entries: soc-fw, scp-fwu-cfg and nt-fw.
-You can use normal (non-external) binaries like U-Boot simply by adding a
-FIP type, with the `fip-type` property, as above.
-
-Since FIP exists to bring blobs together, Binman assumes that all FIP
-entries are external binaries. If a binary may not exist, you can use the
-`--allow-missing` flag to Binman, in which case the image is still created,
-even though it will not actually work.
-
-The size of the FIP depends on the size of the binaries. There is currently
-no way to specify a fixed size. If the `atf-fip` node has a `size` entry,
-this affects the space taken up by the `atf-fip` entry, but the FIP itself
-does not expand to use that space.
-
-Some other FIP features are available with Binman. The header and the
-entries have 64-bit flag works. The flag flags do not seem to be defined
-anywhere, but you can use `fip-hdr-flags` and fip-flags` to set the values
-of the header and entries respectively.
-
-FIP entries can be aligned to a particular power-of-two boundary. Use
-fip-align for this.
-
-Binman only understands the entry types that are included in its
-implementation. It is possible to specify a 16-byte UUID instead, using the
-fip-uuid property. In this case Binman doesn't know what its type is, so
-just uses the UUID. See the `u-boot` node in this example::
-
- binman {
- atf-fip {
- fip-hdr-flags = /bits/ 64 <0x123>;
- fip-align = <16>;
- soc-fw {
- fip-flags = /bits/ 64 <0x456>;
- filename = "bl31.bin";
- };
-
- scp-fwu-cfg {
- filename = "bl2u.bin";
- };
-
- u-boot {
- fip-uuid = [fc 65 13 92 4a 5b 11 ec
- 94 35 ff 2d 1c fc 79 9c];
- };
- };
- fdtmap {
- };
- };
-
-Binman allows reading and updating FIP entries after the image is created,
-provided that an FDPMAP is present too. Updates which change the size of a
-FIP entry will cause it to be expanded or contracted as needed.
-
-Properties for top-level atf-fip node
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-fip-hdr-flags (64 bits)
- Sets the flags for the FIP header.
-
-Properties for subnodes
-~~~~~~~~~~~~~~~~~~~~~~~
-
-fip-type (str)
- FIP type to use for this entry. This is needed if the entry
- name is not a valid type. Value types are defined in `fip_util.py`.
- The FIP type defines the UUID that is used (they map 1:1).
-
-fip-uuid (16 bytes)
- If there is no FIP-type name defined, or it is not supported by Binman,
- this property sets the UUID. It should be a 16-byte value, following the
- hex digits of the UUID.
-
-fip-flags (64 bits)
- Set the flags for a FIP entry. Use in one of the subnodes of the
- 7atf-fip entry.
-
-fip-align
- Set the alignment for a FIP entry, FIP entries can be aligned to a
- particular power-of-two boundary. The default is 1.
-
-Adding new FIP-entry types
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When new FIP entries are defined by TF-A they appear in the
-`TF-A source tree`_. You can use `fip_util.py` to update Binman to support
-new types, then `send a patch`_ to the U-Boot mailing list. There are two
-source files that the tool examples:
-
-- `include/tools_share/firmware_image_package.h` has the UUIDs
-- `tools/fiptool/tbbr_config.c` has the name and descripion for each UUID
-
-To run the tool::
-
- $ tools/binman/fip_util.py -s /path/to/arm-trusted-firmware
- Warning: UUID 'UUID_NON_TRUSTED_WORLD_KEY_CERT' is not mentioned in tbbr_config.c file
- Existing code in 'tools/binman/fip_util.py' is up-to-date
-
-If it shows there is an update, it writes a new version of `fip_util.py`
-to `fip_util.py.out`. You can change the output file using the `-i` flag.
-If you have a problem, use `-D` to enable traceback debugging.
-
-FIP commentary
-~~~~~~~~~~~~~~
-
-As a side effect of use of UUIDs, FIP does not support multiple
-entries of the same type, such as might be used to store fonts or graphics
-icons, for example. For verified boot it could be used for each part of the
-image (e.g. separate FIPs for A and B) but cannot describe the whole
-firmware image. As with FMAP there is no hierarchy defined, although FMAP
-works around this by having 'section' areas which encompass others. A
-similar workaround would be possible with FIP but is not currently defined.
-
-It is recommended to always add an fdtmap to every image, as well as any
-FIPs so that binman and other tools can access the entire image correctly.
-
-.. _FIP: https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#firmware-image-package-fip
-.. _`TF-A source tree`: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
-.. _`send a patch`: https://docs.u-boot.org/en/latest/develop/sending_patches.html
-
-
-
-.. _etype_blob:
-
-Entry: blob: Arbitrary binary blob
-----------------------------------
-
-Note: This should not be used by itself. It is normally used as a parent
-class by other entry types.
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
- - compress: Compression algorithm to use:
- none: No compression
- lz4: Use lz4 compression (via 'lz4' command-line utility)
-
-This entry reads data from a file and places it in the entry. The
-default filename is often specified specified by the subclass. See for
-example the 'u-boot' entry which provides the filename 'u-boot.bin'.
-
-If compression is enabled, an extra 'uncomp-size' property is written to
-the node (if enabled with -u) which provides the uncompressed size of the
-data.
-
-
-
-.. _etype_blob_dtb:
-
-Entry: blob-dtb: A blob that holds a device tree
-------------------------------------------------
-
-This is a blob containing a device tree. The contents of the blob are
-obtained from the list of available device-tree files, managed by the
-'state' module.
-
-Additional attributes:
- prepend: Header used (e.g. 'length')
-
-
-
-.. _etype_blob_ext:
-
-Entry: blob-ext: Externally built binary blob
----------------------------------------------
-
-Note: This should not be used by itself. It is normally used as a parent
-class by other entry types.
-
-If the file providing this blob is missing, binman can optionally ignore it
-and produce a broken image with a warning.
-
-See 'blob' for Properties / Entry arguments.
-
-
-
-.. _etype_blob_ext_list:
-
-Entry: blob-ext-list: List of externally built binary blobs
------------------------------------------------------------
-
-This is like blob-ext except that a number of blobs can be provided,
-typically with some sort of relationship, e.g. all are DDC parameters.
-
-If any of the external files needed by this llist is missing, binman can
-optionally ignore it and produce a broken image with a warning.
-
-Args:
- filenames: List of filenames to read and include
-
-
-
-.. _etype_blob_named_by_arg:
-
-Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass
------------------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - <xxx>-path: Filename containing the contents of this entry (optional,
- defaults to None)
-
-where <xxx> is the blob_fname argument to the constructor.
-
-This entry cannot be used directly. Instead, it is used as a parent class
-for another entry, which defined blob_fname. This parameter is used to
-set the entry-arg or property containing the filename. The entry-arg or
-property is in turn used to set the actual filename.
-
-See cros_ec_rw for an example of this.
-
-
-
-.. _etype_blob_phase:
-
-Entry: blob-phase: Section that holds a phase binary
-----------------------------------------------------
-
-This is a base class that should not normally be used directly. It is used
-when converting a 'u-boot' entry automatically into a 'u-boot-expanded'
-entry; similarly for SPL.
-
-
-
-.. _etype_cbfs:
-
-Entry: cbfs: Coreboot Filesystem (CBFS)
----------------------------------------
-
-A CBFS provides a way to group files into a group. It has a simple directory
-structure and allows the position of individual files to be set, since it is
-designed to support execute-in-place in an x86 SPI-flash device. Where XIP
-is not used, it supports compression and storing ELF files.
-
-CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
-
-The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::
-
- cbfs {
- size = <0x100000>;
- u-boot {
- cbfs-type = "raw";
- };
- u-boot-dtb {
- cbfs-type = "raw";
- };
- };
-
-This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb.
-Note that the size is required since binman does not support calculating it.
-The contents of each entry is just what binman would normally provide if it
-were not a CBFS node. A blob type can be used to import arbitrary files as
-with the second subnode below::
-
- cbfs {
- size = <0x100000>;
- u-boot {
- cbfs-name = "BOOT";
- cbfs-type = "raw";
- };
-
- dtb {
- type = "blob";
- filename = "u-boot.dtb";
- cbfs-type = "raw";
- cbfs-compress = "lz4";
- cbfs-offset = <0x100000>;
- };
- };
-
-This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and
-u-boot.dtb (named "dtb") and compressed with the lz4 algorithm.
-
-
-Properties supported in the top-level CBFS node:
-
-cbfs-arch:
- Defaults to "x86", but you can specify the architecture if needed.
-
-
-Properties supported in the CBFS entry subnodes:
-
-cbfs-name:
- This is the name of the file created in CBFS. It defaults to the entry
- name (which is the node name), but you can override it with this
- property.
-
-cbfs-type:
- This is the CBFS file type. The following are supported:
-
- raw:
- This is a 'raw' file, although compression is supported. It can be
- used to store any file in CBFS.
-
- stage:
- This is an ELF file that has been loaded (i.e. mapped to memory), so
- appears in the CBFS as a flat binary. The input file must be an ELF
- image, for example this puts "u-boot" (the ELF image) into a 'stage'
- entry::
-
- cbfs {
- size = <0x100000>;
- u-boot-elf {
- cbfs-name = "BOOT";
- cbfs-type = "stage";
- };
- };
-
- You can use your own ELF file with something like::
-
- cbfs {
- size = <0x100000>;
- something {
- type = "blob";
- filename = "cbfs-stage.elf";
- cbfs-type = "stage";
- };
- };
-
- As mentioned, the file is converted to a flat binary, so it is
- equivalent to adding "u-boot.bin", for example, but with the load and
- start addresses specified by the ELF. At present there is no option
- to add a flat binary with a load/start address, similar to the
- 'add-flat-binary' option in cbfstool.
-
-cbfs-offset:
- This is the offset of the file's data within the CBFS. It is used to
- specify where the file should be placed in cases where a fixed position
- is needed. Typical uses are for code which is not relocatable and must
- execute in-place from a particular address. This works because SPI flash
- is generally mapped into memory on x86 devices. The file header is
- placed before this offset so that the data start lines up exactly with
- the chosen offset. If this property is not provided, then the file is
- placed in the next available spot.
-
-The current implementation supports only a subset of CBFS features. It does
-not support other file types (e.g. payload), adding multiple files (like the
-'files' entry with a pattern supported by binman), putting files at a
-particular offset in the CBFS and a few other things.
-
-Of course binman can create images containing multiple CBFSs, simply by
-defining these in the binman config::
-
-
- binman {
- size = <0x800000>;
- cbfs {
- offset = <0x100000>;
- size = <0x100000>;
- u-boot {
- cbfs-type = "raw";
- };
- u-boot-dtb {
- cbfs-type = "raw";
- };
- };
-
- cbfs2 {
- offset = <0x700000>;
- size = <0x100000>;
- u-boot {
- cbfs-type = "raw";
- };
- u-boot-dtb {
- cbfs-type = "raw";
- };
- image {
- type = "blob";
- filename = "image.jpg";
- };
- };
- };
-
-This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB,
-both of size 1MB.
-
-
-
-.. _etype_collection:
-
-Entry: collection: An entry which contains a collection of other entries
-------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - content: List of phandles to entries to include
-
-This allows reusing the contents of other entries. The contents of the
-listed entries are combined to form this entry. This serves as a useful
-base class for entry types which need to process data from elsewhere in
-the image, not necessarily child entries.
-
-The entries can generally be anywhere in the same image, even if they are in
-a different section from this entry.
-
-
-
-.. _etype_cros_ec_rw:
-
-Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image
---------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - cros-ec-rw-path: Filename containing the EC image
-
-This entry holds a Chromium OS EC (embedded controller) image, for use in
-updating the EC on startup via software sync.
-
-
-
-.. _etype_efi_capsule:
-
-Entry: efi-capsule: Generate EFI capsules
------------------------------------------
-
-The parameters needed for generation of the capsules can
-be provided as properties in the entry.
-
-Properties / Entry arguments:
- - image-index: Unique number for identifying corresponding
- payload image. Number between 1 and descriptor count, i.e.
- the total number of firmware images that can be updated. Mandatory
- property.
- - image-guid: Image GUID which will be used for identifying the
- updatable image on the board. Mandatory property.
- - hardware-instance: Optional number for identifying unique
- hardware instance of a device in the system. Default value of 0
- for images where value is not to be used.
- - fw-version: Value of image version that can be put on the capsule
- through the Firmware Management Protocol(FMP) header.
- - monotonic-count: Count used when signing an image.
- - private-key: Path to PEM formatted .key private key file. Mandatory
- property for generating signed capsules.
- - public-key-cert: Path to PEM formatted .crt public key certificate
- file. Mandatory property for generating signed capsules.
- - oem-flags - OEM flags to be passed through capsule header.
-
-Since this is a subclass of Entry_section, all properties of the parent
-class also apply here. Except for the properties stated as mandatory, the
-rest of the properties are optional.
-
-For more details on the description of the capsule format, and the capsule
-update functionality, refer Section 8.5 and Chapter 23 in the `UEFI
-specification`_.
-
-The capsule parameters like image index and image GUID are passed as
-properties in the entry. The payload to be used in the capsule is to be
-provided as a subnode of the capsule entry.
-
-A typical capsule entry node would then look something like this::
-
- capsule {
- type = "efi-capsule";
- image-index = <0x1>;
- /* Image GUID for testing capsule update */
- image-guid = SANDBOX_UBOOT_IMAGE_GUID;
- hardware-instance = <0x0>;
- private-key = "path/to/the/private/key";
- public-key-cert = "path/to/the/public-key-cert";
- oem-flags = <0x8000>;
-
- u-boot {
- };
- };
-
-In the above example, the capsule payload is the U-Boot image. The
-capsule entry would read the contents of the payload and put them
-into the capsule. Any external file can also be specified as the
-payload using the blob-ext subnode.
-
-.. _`UEFI specification`: https://uefi.org/sites/default/files/resources/UEFI_Spec_2_10_Aug29.pdf
-
-
-
-.. _etype_efi_empty_capsule:
-
-Entry: efi-empty-capsule: Generate EFI empty capsules
------------------------------------------------------
-
-The parameters needed for generation of the empty capsules can
-be provided as properties in the entry.
-
-Properties / Entry arguments:
- - image-guid: Image GUID which will be used for identifying the
- updatable image on the board. Mandatory for accept capsule.
- - capsule-type - String to indicate type of capsule to generate. Valid
- values are 'accept' and 'revert'.
-
-For more details on the description of the capsule format, and the capsule
-update functionality, refer Section 8.5 and Chapter 23 in the `UEFI
-specification`_. For more information on the empty capsule, refer the
-sections 2.3.2 and 2.3.3 in the `Dependable Boot specification`_.
-
-A typical accept empty capsule entry node would then look something like
-this::
-
- empty-capsule {
- type = "efi-empty-capsule";
- /* GUID of image being accepted */
- image-type-id = SANDBOX_UBOOT_IMAGE_GUID;
- capsule-type = "accept";
- };
-
-A typical revert empty capsule entry node would then look something like
-this::
-
- empty-capsule {
- type = "efi-empty-capsule";
- capsule-type = "revert";
- };
-
-The empty capsules do not have any input payload image.
-
-.. _`UEFI specification`: https://uefi.org/sites/default/files/resources/UEFI_Spec_2_10_Aug29.pdf
-.. _`Dependable Boot specification`: https://git.codelinaro.org/linaro/dependable-boot/mbfw/uploads/6f7ddfe3be24e18d4319e108a758d02e/mbfw.pdf
-
-
-
-.. _etype_encrypted:
-
-Entry: encrypted: Externally built encrypted binary blob
---------------------------------------------------------
-
-This entry provides the functionality to include information about how to
-decrypt an encrypted binary. This information is added to the
-resulting device tree by adding a new cipher node in the entry's parent
-node (i.e. the binary).
-
-The key that must be used to decrypt the binary is either directly embedded
-in the device tree or indirectly by specifying a key source. The key source
-can be used as an id of a key that is stored in an external device.
-
-Using an embedded key
-~~~~~~~~~~~~~~~~~~~~~
-
-This is an example using an embedded key::
-
- blob-ext {
- filename = "encrypted-blob.bin";
- };
-
- encrypted {
- algo = "aes256-gcm";
- iv-filename = "encrypted-blob.bin.iv";
- key-filename = "encrypted-blob.bin.key";
- };
-
-This entry generates the following device tree structure form the example
-above::
-
- data = [...]
- cipher {
- algo = "aes256-gcm";
- key = <0x...>;
- iv = <0x...>;
- };
-
-The data property is generated by the blob-ext etype, the cipher node and
-its content is generated by this etype.
-
-Using an external key
-~~~~~~~~~~~~~~~~~~~~~
-
-Instead of embedding the key itself into the device tree, it is also
-possible to address an externally stored key by specifying a 'key-source'
-instead of the 'key'::
-
- blob-ext {
- filename = "encrypted-blob.bin";
- };
-
- encrypted {
- algo = "aes256-gcm";
- iv-filename = "encrypted-blob.bin.iv";
- key-source = "external-key-id";
- };
-
-This entry generates the following device tree structure form the example
-above::
-
- data = [...]
- cipher {
- algo = "aes256-gcm";
- key-source = "external-key-id";
- iv = <0x...>;
- };
-
-Properties
-~~~~~~~~~~
-
-Properties / Entry arguments:
- - algo: The encryption algorithm. Currently no algorithm is supported
- out-of-the-box. Certain algorithms will be added in future
- patches.
- - iv-filename: The name of the file containing the initialization
- vector (in short iv). See
- https://en.wikipedia.org/wiki/Initialization_vector
- - key-filename: The name of the file containing the key. Either
- key-filename or key-source must be provided.
- - key-source: The key that should be used. Either key-filename or
- key-source must be provided.
-
-
-
-.. _etype_fdtmap:
-
-Entry: fdtmap: An entry which contains an FDT map
--------------------------------------------------
-
-Properties / Entry arguments:
- None
-
-An FDT map is just a header followed by an FDT containing a list of all the
-entries in the image. The root node corresponds to the image node in the
-original FDT, and an image-name property indicates the image name in that
-original tree.
-
-The header is the string _FDTMAP_ followed by 8 unused bytes.
-
-When used, this entry will be populated with an FDT map which reflects the
-entries in the current image. Hierarchy is preserved, and all offsets and
-sizes are included.
-
-Note that the -u option must be provided to ensure that binman updates the
-FDT with the position of each entry.
-
-Example output for a simple image with U-Boot and an FDT map::
-
- / {
- image-name = "binman";
- size = <0x00000112>;
- image-pos = <0x00000000>;
- offset = <0x00000000>;
- u-boot {
- size = <0x00000004>;
- image-pos = <0x00000000>;
- offset = <0x00000000>;
- };
- fdtmap {
- size = <0x0000010e>;
- image-pos = <0x00000004>;
- offset = <0x00000004>;
- };
- };
-
-If allow-repack is used then 'orig-offset' and 'orig-size' properties are
-added as necessary. See the binman README.
-
-When extracting files, an alternative 'fdt' format is available for fdtmaps.
-Use `binman extract -F fdt ...` to use this. It will export a devicetree,
-without the fdtmap header, so it can be viewed with `fdtdump`.
-
-
-
-.. _etype_files:
-
-Entry: files: A set of files arranged in a section
---------------------------------------------------
-
-Properties / Entry arguments:
- - pattern: Filename pattern to match the files to include
- - files-compress: Compression algorithm to use:
- none: No compression
- lz4: Use lz4 compression (via 'lz4' command-line utility)
- - files-align: Align each file to the given alignment
-
-This entry reads a number of files and places each in a separate sub-entry
-within this entry. To access these you need to enable device-tree updates
-at run-time so you can obtain the file positions.
-
-
-
-.. _etype_fill:
-
-Entry: fill: An entry which is filled to a particular byte value
-----------------------------------------------------------------
-
-Properties / Entry arguments:
- - fill-byte: Byte to use to fill the entry
-
-Note that the size property must be set since otherwise this entry does not
-know how large it should be.
-
-You can often achieve the same effect using the pad-byte property of the
-overall image, in that the space between entries will then be padded with
-that byte. But this entry is sometimes useful for explicitly setting the
-byte value of a region.
-
-
-
-.. _etype_fit:
-
-Entry: fit: Flat Image Tree (FIT)
----------------------------------
-
-This calls mkimage to create a FIT (U-Boot Flat Image Tree) based on the
-input provided.
-
-Nodes for the FIT should be written out in the binman configuration just as
-they would be in a file passed to mkimage.
-
-For example, this creates an image containing a FIT with U-Boot SPL::
-
- binman {
- fit {
- description = "Test FIT";
- fit,fdt-list = "of-list";
-
- images {
- kernel at 1 {
- description = "SPL";
- os = "u-boot";
- type = "rkspi";
- arch = "arm";
- compression = "none";
- load = <0>;
- entry = <0>;
-
- u-boot-spl {
- };
- };
- };
- };
- };
-
-More complex setups can be created, with generated nodes, as described
-below.
-
-Properties (in the 'fit' node itself)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Special properties have a `fit,` prefix, indicating that they should be
-processed but not included in the final FIT.
-
-The top-level 'fit' node supports the following special properties:
-
- fit,external-offset
- Indicates that the contents of the FIT are external and provides the
- external offset. This is passed to mkimage via the -E and -p flags.
-
- fit,align
- Indicates what alignment to use for the FIT and its external data,
- and provides the alignment to use. This is passed to mkimage via
- the -B flag.
-
- fit,fdt-list
- Indicates the entry argument which provides the list of device tree
- files for the gen-fdt-nodes operation (as below). This is often
- `of-list` meaning that `-a of-list="dtb1 dtb2..."` should be passed
- to binman.
-
- fit,fdt-list-val
- As an alternative to fit,fdt-list the list of device tree files
- can be provided in this property as a string list, e.g.::
-
- fit,fdt-list-val = "dtb1", "dtb2";
-
- fit,fdt-list-dir
- As an alternative to fit,fdt-list the list of device tree files
- can be provided as a directory. Each .dtb file in the directory is
- processed, , e.g.::
-
- fit,fdt-list-dir = "arch/arm/dts";
-
- In this case the input directories are ignored and all devicetree
- files must be in that directory.
-
- fit,sign
- Enable signing FIT images via mkimage as described in
- verified-boot.rst.
- If the property is found and fit,engine is not set, the private
- keys path is detected among binman include directories and passed to
- mkimage via -k flag. All the keys required for signing FIT must be
- available at time of signing and must be located in single include
- directory.
-
- fit,encrypt
- Enable data encryption in FIT images via mkimage. If the property
- is found, the keys path is detected among binman include
- directories and passed to mkimage via -k flag. All the keys
- required for encrypting the FIT must be available at the time of
- encrypting and must be located in a single include directory.
-
- Incompatible with fit,engine.
-
- fit,engine
- Indicates the OpenSSL engine to use for signing the FIT image. This
- is passed to mkimage via the `-N` flag. Example::
-
- fit,engine = "my-engine";
-
- A `-k` argument for mkimage may be passed via `fit,engine-keydir`.
-
- When `fit,engine` is set to `pkcs11`, the following applies:
-
- - If `fit,engine-keydir` is absent, the value of `key-name-hint` is
- prefixed with `pkcs11:object=` before being passed to the OpenSSL
- engine API::
-
- pkcs11:object=<key-name-hint>
-
- - If `fit,engine-keydir` contains either `object=` or `id=`, its
- value is passed verbatim to the OpenSSL engine API,
-
- - Otherwise, the value of `fit,engine-keydir` is followed by
- `;object=` and the value of `key-name-hint` before being passed
- to the OpenSSL engine API::
-
- <fit,engine-keydir>;object=<key-name-hint>
-
- If `fit,engine` is set to something different than `pkcs11`, the
- value of `key-name-hint` (prefixed with the value of
- `fit,engine-keydir` if present) and passed verbatim to the OpenSSL
- engine API.
-
- Depends on fit,sign.
-
- Incompatible with fit,encrypt.
-
- fit,engine-keydir
- Indicates the `-k` argument to pass to mkimage if an OpenSSL engine
- is to be used for signing the FIT image. Example::
-
- fit,engine-keydir = "pkcs11:model=xxx;manufacturer=xxx";
-
- Read `fit,engine` documentation for more info on special cases when
- using `pkcs11` as engine.
-
- Depends on fit,engine.
-
-Substitutions
-~~~~~~~~~~~~~
-
-Node names and property values support a basic string-substitution feature.
-Available substitutions for '@' nodes (and property values) are:
-
-SEQ:
- Sequence number of the generated fdt (1, 2, ...)
-NAME
- Name of the dtb as provided (i.e. without adding '.dtb')
-
-The `default` property, if present, will be automatically set to the name
-if of configuration whose devicetree matches the `default-dt` entry
-argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.
-
-Available substitutions for property values in these nodes are:
-
-DEFAULT-SEQ:
- Sequence number of the default fdt, as provided by the 'default-dt'
- entry argument
-
-DEFAULT-NAME:
- Name of the default fdt, as provided by the 'default-dt' entry argument
-
-Available operations
-~~~~~~~~~~~~~~~~~~~~
-
-You can add an operation to an '@' node to indicate which operation is
-required::
-
- @fdt-SEQ {
- fit,operation = "gen-fdt-nodes";
- ...
- };
-
-Available operations are:
-
-gen-fdt-nodes
- Generate FDT nodes as above. This is the default if there is no
- `fit,operation` property.
-
-split-elf
- Split an ELF file into a separate node for each segment.
-
-Generating nodes from an FDT list (gen-fdt-nodes)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-U-Boot supports creating fdt and config nodes automatically. To do this,
-pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells
-binman that you want to generates nodes for two files: `file1.dtb` and
-`file2.dtb`. The `fit,fdt-list` property (see above) indicates that
-`of-list` should be used. If the property is missing you will get an error.
-
-Then add a 'generator node', a node with a name starting with '@'::
-
- images {
- @fdt-SEQ {
- description = "fdt-NAME";
- type = "flat_dt";
- compression = "none";
- };
- };
-
-This tells binman to create nodes `fdt-1` and `fdt-2` for each of your two
-files. All the properties you specify will be included in the node. This
-node acts like a template to generate the nodes. The generator node itself
-does not appear in the output - it is replaced with what binman generates.
-A 'data' property is created with the contents of the FDT file.
-
-You can create config nodes in a similar way::
-
- configurations {
- default = "@config-DEFAULT-SEQ";
- @config-SEQ {
- description = "NAME";
- firmware = "atf";
- loadables = "uboot";
- fdt = "fdt-SEQ";
- fit,compatible; // optional
- };
- };
-
-This tells binman to create nodes `config-1` and `config-2`, i.e. a config
-for each of your two files.
-
-It is also possible to use NAME in the node names so that the FDT files name
-will be used instead of the sequence number. This can be useful to identify
-easily at runtime in U-Boot, the config to be used::
-
- configurations {
- default = "@config-DEFAULT-NAME";
- @config-NAME {
- description = "NAME";
- firmware = "atf";
- loadables = "uboot";
- fdt = "fdt-NAME";
- fit,compatible; // optional
- };
- };
-
-Note that if no devicetree files are provided (with '-a of-list' as above)
-then no nodes will be generated.
-
-The 'fit,compatible' property (if present) is replaced with the compatible
-string from the root node of the devicetree, so that things work correctly
-with FIT's configuration-matching algortihm.
-
-Dealing with phases
-~~~~~~~~~~~~~~~~~~~
-
-FIT can be used to load firmware. In this case it may be necessary to run
-the devicetree for each model through fdtgrep to remove unwanted properties.
-The 'fit,fdt-phase' property can be provided to indicate the phase for which
-the devicetree is intended.
-
-For example this indicates that the FDT should be processed for VPL::
-
- images {
- @fdt-SEQ {
- description = "fdt-NAME";
- type = "flat_dt";
- compression = "none";
- fit,fdt-phase = "vpl";
- };
- };
-
-Using this mechanism, it is possible to generate a FIT which can provide VPL
-images for multiple models, with TPL selecting the correct model to use. The
-same approach can of course be used for SPL images.
-
-Note that the `of-spl-remove-props` entryarg can be used to indicate
-additional properties to remove. It is often used to remove properties like
-`clock-names` and `pinctrl-names` which are not needed in SPL builds. This
-value is automatically passed to binman by the U-Boot build.
-
-See :ref:`fdtgrep_filter` for more information.
-
-Generating nodes from an ELF file (split-elf)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This uses the node as a template to generate multiple nodes. The following
-special properties are available:
-
-split-elf
- Split an ELF file into a separate node for each segment. This uses the
- node as a template to generate multiple nodes. The following special
- properties are available:
-
- fit,load
- Generates a `load = <...>` property with the load address of the
- segment
-
- fit,entry
- Generates a `entry = <...>` property with the entry address of the
- ELF. This is only produced for the first entry
-
- fit,data
- Generates a `data = <...>` property with the contents of the segment
-
- fit,firmware
- Generates a `firmware = <...>` property. Provides a list of possible
- nodes to be used as the `firmware` property value. The first valid
- node is picked as the firmware. Any remaining valid nodes is
- prepended to the `loadable` property generated by `fit,loadables`
-
- fit,loadables
- Generates a `loadable = <...>` property with a list of the generated
- nodes (including all nodes if this operation is used multiple times)
-
-
-Here is an example showing ATF, TEE and a device tree all combined::
-
- fit {
- description = "test-desc";
- #address-cells = <1>;
- fit,fdt-list = "of-list";
-
- images {
- u-boot {
- description = "U-Boot (64-bit)";
- type = "standalone";
- os = "U-Boot";
- arch = "arm64";
- compression = "none";
- load = <CONFIG_TEXT_BASE>;
- u-boot-nodtb {
- };
- };
- @fdt-SEQ {
- description = "fdt-NAME.dtb";
- type = "flat_dt";
- compression = "none";
- };
- @atf-SEQ {
- fit,operation = "split-elf";
- description = "ARM Trusted Firmware";
- type = "firmware";
- arch = "arm64";
- os = "arm-trusted-firmware";
- compression = "none";
- fit,load;
- fit,entry;
- fit,data;
-
- atf-bl31 {
- };
- hash {
- algo = "sha256";
- };
- };
-
- @tee-SEQ {
- fit,operation = "split-elf";
- description = "TEE";
- type = "tee";
- arch = "arm64";
- os = "tee";
- compression = "none";
- fit,load;
- fit,entry;
- fit,data;
-
- tee-os {
- };
- hash {
- algo = "sha256";
- };
- };
- };
-
- configurations {
- default = "@config-DEFAULT-SEQ";
- @config-SEQ {
- description = "conf-NAME.dtb";
- fdt = "fdt-SEQ";
- fit,firmware = "atf-1", "u-boot";
- fit,loadables;
- };
- };
- };
-
-If ATF-BL31 is available, this generates a node for each segment in the
-ELF file, for example::
-
- images {
- atf-1 {
- data = <...contents of first segment...>;
- data-offset = <0x00000000>;
- entry = <0x00040000>;
- load = <0x00040000>;
- compression = "none";
- os = "arm-trusted-firmware";
- arch = "arm64";
- type = "firmware";
- description = "ARM Trusted Firmware";
- hash {
- algo = "sha256";
- value = <...hash of first segment...>;
- };
- };
- atf-2 {
- data = <...contents of second segment...>;
- load = <0xff3b0000>;
- compression = "none";
- os = "arm-trusted-firmware";
- arch = "arm64";
- type = "firmware";
- description = "ARM Trusted Firmware";
- hash {
- algo = "sha256";
- value = <...hash of second segment...>;
- };
- };
- };
-
-The same applies for OP-TEE if that is available.
-
-If each binary is not available, the relevant template node (@atf-SEQ or
- at tee-SEQ) is removed from the output.
-
-This also generates a `config-xxx` node for each device tree in `of-list`.
-Note that the U-Boot build system uses `-a of-list=$(CONFIG_OF_LIST)`
-so you can use `CONFIG_OF_LIST` to define that list. In this example it is
-set up for `firefly-rk3399` with a single device tree and the default set
-with `-a default-dt=$(CONFIG_DEFAULT_DEVICE_TREE)`, so the resulting output
-is::
-
- configurations {
- default = "config-1";
- config-1 {
- loadables = "u-boot", "atf-2", "atf-3", "tee-1", "tee-2";
- description = "rk3399-firefly.dtb";
- fdt = "fdt-1";
- firmware = "atf-1";
- };
- };
-
-U-Boot SPL can then load the firmware (ATF) and all the loadables (U-Boot
-proper, ATF and TEE), then proceed with the boot.
-
-
-
-.. _etype_fmap:
-
-Entry: fmap: An entry which contains an Fmap section
-----------------------------------------------------
-
-Properties / Entry arguments:
- None
-
-FMAP is a simple format used by flashrom, an open-source utility for
-reading and writing the SPI flash, typically on x86 CPUs. The format
-provides flashrom with a list of areas, so it knows what it in the flash.
-It can then read or write just a single area, instead of the whole flash.
-
-The format is defined by the flashrom project, in the file lib/fmap.h -
-see www.flashrom.org/Flashrom for more information.
-
-When used, this entry will be populated with an FMAP which reflects the
-entries in the current image. Note that any hierarchy is squashed, since
-FMAP does not support this. Sections are represented as an area appearing
-before its contents, so that it is possible to reconstruct the hierarchy
-from the FMAP by using the offset information. This convention does not
-seem to be documented, but is used in Chromium OS.
-
-To mark an area as preserved, use the normal 'preserved' flag in the entry.
-This will result in the corresponding FMAP area having the
-FMAP_AREA_PRESERVE flag. This flag does not automatically propagate down to
-child entries.
-
-CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
-
-
-
-.. _etype_gbb:
-
-Entry: gbb: An entry which contains a Chromium OS Google Binary Block
----------------------------------------------------------------------
-
-Properties / Entry arguments:
- - hardware-id: Hardware ID to use for this build (a string)
- - keydir: Directory containing the public keys to use
- - bmpblk: Filename containing images used by recovery
-
-Chromium OS uses a GBB to store various pieces of information, in particular
-the root and recovery keys that are used to verify the boot process. Some
-more details are here:
-
- https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
-
-but note that the page dates from 2013 so is quite out of date. See
-README.chromium for how to obtain the required keys and tools.
-
-
-
-.. _etype_image_header:
-
-Entry: image-header: An entry which contains a pointer to the FDT map
----------------------------------------------------------------------
-
-Properties / Entry arguments:
- location: Location of header ("start" or "end" of image). This is
- optional. If omitted then the entry must have an offset property.
-
-This adds an 8-byte entry to the start or end of the image, pointing to the
-location of the FDT map. The format is a magic number followed by an offset
-from the start or end of the image, in twos-compliment format.
-
-This entry must be in the top-level part of the image.
-
-NOTE: If the location is at the start/end, you will probably need to specify
-sort-by-offset for the image, unless you actually put the image header
-first/last in the entry list.
-
-
-
-.. _etype_intel_cmc:
-
-Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains microcode for some devices in a special format. An
-example filename is 'Microcode/C0_22211.BIN'.
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_descriptor:
-
-Entry: intel-descriptor: Intel flash descriptor block (4KB)
------------------------------------------------------------
-
-Properties / Entry arguments:
- filename: Filename of file containing the descriptor. This is typically
- a 4KB binary file, sometimes called 'descriptor.bin'
-
-This entry is placed at the start of flash and provides information about
-the SPI flash regions. In particular it provides the base address and
-size of the ME (Management Engine) region, allowing us to place the ME
-binary in the right place.
-
-With this entry in your image, the position of the 'intel-me' entry will be
-fixed in the image, which avoids you needed to specify an offset for that
-region. This is useful, because it is not possible to change the position
-of the ME region without updating the descriptor.
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_fit:
-
-Entry: intel-fit: Intel Firmware Image Table (FIT)
---------------------------------------------------
-
-This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
-contains information about the firmware and microcode available in the
-image.
-
-At present binman only supports a basic FIT with no microcode.
-
-
-
-.. _etype_intel_fit_ptr:
-
-Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
---------------------------------------------------------------
-
-This entry contains a pointer to the FIT. It is required to be at address
-0xffffffc0 in the image.
-
-
-
-.. _etype_intel_fsp:
-
-Entry: intel-fsp: Intel Firmware Support Package (FSP) file
------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains binary blobs which are used on some devices to make the
-platform work. U-Boot executes this code since it is not possible to set up
-the hardware using U-Boot open-source code. Documentation is typically not
-available in sufficient detail to allow this.
-
-An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_fsp_m:
-
-Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
---------------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains a binary blob which is used on some devices to set up
-SDRAM. U-Boot executes this code in SPL so that it can make full use of
-memory. Documentation is typically not available in sufficient detail to
-allow U-Boot do this this itself..
-
-An example filename is 'fsp_m.bin'
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_fsp_s:
-
-Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
----------------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains a binary blob which is used on some devices to set up
-the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
-running, so that it can make full use of memory. Documentation is typically
-not available in sufficient detail to allow U-Boot do this this itself.
-
-An example filename is 'fsp_s.bin'
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_fsp_t:
-
-Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
-----------------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains a binary blob which is used on some devices to set up
-temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
-that it has access to memory for its stack and initial storage.
-
-An example filename is 'fsp_t.bin'
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_ifwi:
-
-Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
---------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry. This is either the
- IFWI file itself, or a file that can be converted into one using a
- tool
- - convert-fit: If present this indicates that the ifwitool should be
- used to convert the provided file into a IFWI.
-
-This file contains code and data used by the SoC that is required to make
-it work. It includes U-Boot TPL, microcode, things related to the CSE
-(Converged Security Engine, the microcontroller that loads all the firmware)
-and other items beyond the wit of man.
-
-A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
-file that will be converted to an IFWI.
-
-The position of this entry is generally set by the intel-descriptor entry.
-
-The contents of the IFWI are specified by the subnodes of the IFWI node.
-Each subnode describes an entry which is placed into the IFWFI with a given
-sub-partition (and optional entry name).
-
-Properties for subnodes:
- - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
- - ifwi-entry: entry name t use, e.g. "IBBL"
- - ifwi-replace: if present, indicates that the item should be replaced
- in the IFWI. Otherwise it is added.
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_me:
-
-Entry: intel-me: Intel Management Engine (ME) file
---------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains code used by the SoC that is required to make it work.
-The Management Engine is like a background task that runs things that are
-not clearly documented, but may include keyboard, display and network
-access. For platform that use ME it is not possible to disable it. U-Boot
-does not directly execute code in the ME binary.
-
-A typical filename is 'me.bin'.
-
-The position of this entry is generally set by the intel-descriptor entry.
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_mrc:
-
-Entry: intel-mrc: Intel Memory Reference Code (MRC) file
---------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains code for setting up the SDRAM on some Intel systems. This
-is executed by U-Boot when needed early during startup. A typical filename
-is 'mrc.bin'.
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_refcode:
-
-Entry: intel-refcode: Intel Reference Code file
------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains code for setting up the platform on some Intel systems.
-This is executed by U-Boot when needed early during startup. A typical
-filename is 'refcode.bin'.
-
-See README.x86 for information about x86 binary blobs.
-
-
-
-.. _etype_intel_vbt:
-
-Entry: intel-vbt: Intel Video BIOS Table (VBT) file
----------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains code that sets up the integrated graphics subsystem on
-some Intel SoCs. U-Boot executes this when the display is started up.
-
-See README.x86 for information about Intel binary blobs.
-
-
-
-.. _etype_intel_vga:
-
-Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
----------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of file to read into entry
-
-This file contains code that sets up the integrated graphics subsystem on
-some Intel SoCs. U-Boot executes this when the display is started up.
-
-This is similar to the VBT file but in a different format.
-
-See README.x86 for information about Intel binary blobs.
-
-
-
-.. _etype_mkimage:
-
-Entry: mkimage: Binary produced by mkimage
-------------------------------------------
-
-Properties / Entry arguments:
- - args: Arguments to pass
- - data-to-imagename: Indicates that the -d data should be passed in as
- the image name also (-n)
- - multiple-data-files: boolean to tell binman to pass all files as
- datafiles to mkimage instead of creating a temporary file the result
- of datafiles concatenation
- - filename: filename of output binary generated by mkimage
-
-The data passed to mkimage via the -d flag is collected from subnodes of the
-mkimage node, e.g.::
-
- mkimage {
- filename = "imximage.bin";
- args = "-n test -T imximage";
-
- u-boot-spl {
- };
- };
-
-This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
-file, with mkimage being called like this::
-
- mkimage -d <data_file> -n test -T imximage <output_file>
-
-The output from mkimage then becomes part of the image produced by
-binman but also is written into `imximage.bin` file. If you need to put
-multiple things in the data file, you can use a section, or just multiple
-subnodes like this::
-
- mkimage {
- args = "-n test -T imximage";
-
- u-boot-spl {
- };
-
- u-boot-tpl {
- };
- };
-
-Note that binman places the contents (here SPL and TPL) into a single file
-and passes that to mkimage using the -d option.
-
-To pass all datafiles untouched to mkimage::
-
- mkimage {
- args = "-n rk3399 -T rkspi";
- multiple-data-files;
-
- u-boot-tpl {
- };
-
- u-boot-spl {
- };
- };
-
-This calls mkimage to create a Rockchip RK3399-specific first stage
-bootloader, made of TPL+SPL. Since this first stage bootloader requires to
-align the TPL and SPL but also some weird hacks that is handled by mkimage
-directly, binman is told to not perform the concatenation of datafiles prior
-to passing the data to mkimage.
-
-To use CONFIG options in the arguments, use a string list instead, as in
-this example which also produces four arguments::
-
- mkimage {
- args = "-n", CONFIG_SYS_SOC, "-T imximage";
-
- u-boot-spl {
- };
- };
-
-If you need to pass the input data in with the -n argument as well, then use
-the 'data-to-imagename' property::
-
- mkimage {
- args = "-T imximage";
- data-to-imagename;
-
- u-boot-spl {
- };
- };
-
-That will pass the data to mkimage both as the data file (with -d) and as
-the image name (with -n). In both cases, a filename is passed as the
-argument, with the actual data being in that file.
-
-If need to pass different data in with -n, then use an `imagename` subnode::
-
- mkimage {
- args = "-T imximage";
-
- imagename {
- blob {
- filename = "spl/u-boot-spl.cfgout"
- };
- };
-
- u-boot-spl {
- };
- };
-
-This will pass in u-boot-spl as the input data and the .cfgout file as the
--n data.
-
-
-
-.. _etype_null:
-
-Entry: null: An entry which has no contents of its own
-------------------------------------------------------
-
-Note that the size property must be set since otherwise this entry does not
-know how large it should be.
-
-The contents are set by the containing section, e.g. the section's pad
-byte.
-
-
-
-.. _etype_nxp_imx8mcst:
-
-Entry: nxp-imx8mcst: NXP i.MX8M CST .cfg file generator and cst invoker
------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - nxp,loader-address - loader address (SPL text base)
-
-
-
-.. _etype_nxp_imx8mimage:
-
-Entry: nxp-imx8mimage: NXP i.MX8M imx8mimage .cfg file generator and mkimage invoker
-------------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - nxp,boot-from - device to boot from (e.g. 'sd')
- - nxp,loader-address - loader address (SPL text base)
- - nxp,rom-version - BootROM version ('2' for i.MX8M Nano and Plus)
-
-
-
-.. _etype_nxp_header_ddrfw:
-
-Entry: nxp-header-ddrfw: add a header to DDR PHY firmware images
-----------------------------------------------------------------
-
-This entry is used to combine DDR PHY firmware images and their byte counts
-together. See imx95_evk.rst for how to get DDR PHY Firmware Images.
-
-
-
-.. _etype_nxp_imx9image:
-
-Entry: nxp_imx9image: data file generator and mkimage invocation
------------------------------------------------------------------------------
-
-This entry is used to generate a data file that is passed to mkimage with the -n
-option. Each line in this data file represents a command defined in the enum
-imx8image_cmd. The imx8image_copy_image() function parses all commands and
-constructs a .bin file accordingly.
-
-
-
-.. _etype_opensbi:
-
-Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
-----------------------------------------------
-
-Properties / Entry arguments:
- - opensbi-path: Filename of file to read into entry. This is typically
- called fw_dynamic.bin
-
-This entry holds the run-time firmware, typically started by U-Boot SPL.
-See the U-Boot README for your architecture or board for how to use it. See
-https://github.com/riscv/opensbi for more information about OpenSBI.
-
-
-
-.. _etype_powerpc_mpc85xx_bootpg_resetvec:
-
-Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
------------------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
-
-This entry is valid for PowerPC mpc85xx cpus. This entry holds
-'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
-placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
-
-
-
-.. _etype_pre_load:
-
-Entry: pre-load: Pre load image header
---------------------------------------
-
-Properties / Entry arguments:
- - pre-load-key-path: Path of the directory that store key (provided by
- the environment variable PRE_LOAD_KEY_PATH)
- - content: List of phandles to entries to sign
- - algo-name: Hash and signature algo to use for the signature
- - padding-name: Name of the padding (pkcs-1.5 or pss)
- - key-name: Filename of the private key to sign
- - header-size: Total size of the header
- - version: Version of the header
-
-This entry creates a pre-load header that contains a global
-image signature.
-
-For example, this creates an image with a pre-load header and a binary::
-
- binman {
- image2 {
- filename = "sandbox.bin";
-
- pre-load {
- content = <&image>;
- algo-name = "sha256,rsa2048";
- padding-name = "pss";
- key-name = "private.pem";
- header-size = <4096>;
- version = <1>;
- };
-
- image: blob-ext {
- filename = "sandbox.itb";
- };
- };
- };
-
-
-
-.. _etype_rockchip_tpl:
-
-Entry: rockchip-tpl: Rockchip TPL binary
-----------------------------------------
-
-Properties / Entry arguments:
- - rockchip-tpl-path: Filename of file to read into the entry,
- typically <soc>_ddr_<version>.bin
-
-This entry holds an external TPL binary used by some Rockchip SoCs
-instead of normal U-Boot TPL, typically to initialize DRAM.
-
-
-
-.. _etype_scp:
-
-Entry: scp: System Control Processor (SCP) firmware blob
---------------------------------------------------------
-
-Properties / Entry arguments:
- - scp-path: Filename of file to read into the entry, typically scp.bin
-
-This entry holds firmware for an external platform-specific coprocessor.
-
-
-
-.. _etype_section:
-
-Entry: section: Entry that contains other entries
--------------------------------------------------
-
-A section is an entry which can contain other entries, thus allowing
-hierarchical images to be created. See 'Sections and hierarchical images'
-in the binman README for more information.
-
-The base implementation simply joins the various entries together, using
-various rules about alignment, etc.
-
-Subclassing
-~~~~~~~~~~~
-
-This class can be subclassed to support other file formats which hold
-multiple entries, such as CBFS. To do this, override the following
-functions. The documentation here describes what your function should do.
-For example code, see etypes which subclass `Entry_section`, or `cbfs.py`
-for a more involved example::
-
- $ grep -l \(Entry_section tools/binman/etype/*.py
-
-ReadNode()
- Call `super().ReadNode()`, then read any special properties for the
- section. Then call `self.ReadEntries()` to read the entries.
-
- Binman calls this at the start when reading the image description.
-
-ReadEntries()
- Read in the subnodes of the section. This may involve creating entries
- of a particular etype automatically, as well as reading any special
- properties in the entries. For each entry, entry.ReadNode() should be
- called, to read the basic entry properties. The properties should be
- added to `self._entries[]`, in the correct order, with a suitable name.
-
- Binman calls this at the start when reading the image description.
-
-BuildSectionData(required)
- Create the custom file format that you want and return it as bytes.
- This likely sets up a file header, then loops through the entries,
- adding them to the file. For each entry, call `entry.GetData()` to
- obtain the data. If that returns None, and `required` is False, then
- this method must give up and return None. But if `required` is True then
- it should assume that all data is valid.
-
- Binman calls this when packing the image, to find out the size of
- everything. It is called again at the end when building the final image.
-
-SetImagePos(image_pos):
- Call `super().SetImagePos(image_pos)`, then set the `image_pos` values
- for each of the entries. This should use the custom file format to find
- the `start offset` (and `image_pos`) of each entry. If the file format
- uses compression in such a way that there is no offset available (other
- than reading the whole file and decompressing it), then the offsets for
- affected entries can remain unset (`None`). The size should also be set
- if possible.
-
- Binman calls this after the image has been packed, to update the
- location that all the entries ended up at.
-
-ReadChildData(child, decomp, alt_format):
- The default version of this may be good enough, if you are able to
- implement SetImagePos() correctly. But that is a bit of a bypass, so
- you can override this method to read from your custom file format. It
- should read the entire entry containing the custom file using
- `super().ReadData(True)`, then parse the file to get the data for the
- given child, then return that data.
-
- If your file format supports compression, the `decomp` argument tells
- you whether to return the compressed data (`decomp` is False) or to
- uncompress it first, then return the uncompressed data (`decomp` is
- True). This is used by the `binman extract -U` option.
-
- If your entry supports alternative formats, the alt_format provides the
- alternative format that the user has selected. Your function should
- return data in that format. This is used by the 'binman extract -l'
- option.
-
- Binman calls this when reading in an image, in order to populate all the
- entries with the data from that image (`binman ls`).
-
-WriteChildData(child):
- Binman calls this after `child.data` is updated, to inform the custom
- file format about this, in case it needs to do updates.
-
- The default version of this does nothing and probably needs to be
- overridden for the 'binman replace' command to work. Your version should
- use `child.data` to update the data for that child in the custom file
- format.
-
- Binman calls this when updating an image that has been read in and in
- particular to update the data for a particular entry (`binman replace`)
-
-Properties / Entry arguments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-See :ref:`develop/package/binman:Image description format` for more
-information.
-
-align-default
- Default alignment for this section, if no alignment is given in the
- entry
-
-pad-byte
- Pad byte to use when padding
-
-sort-by-offset
- True if entries should be sorted by offset, False if they must be
- in-order in the device tree description
-
-end-at-4gb
- Used to build an x86 ROM which ends at 4GB (2^32)
-
-name-prefix
- Adds a prefix to the name of every entry in the section when writing out
- the map
-
-skip-at-start
- Number of bytes before the first entry starts. These effectively adjust
- the starting offset of entries. For example, if this is 16, then the
- first entry would start at 16. An entry with offset = 20 would in fact
- be written at offset 4 in the image file, since the first 16 bytes are
- skipped when writing.
-
-filename
- filename to write the unpadded section contents to within the output
- directory (None to skip this).
-
-Since a section is also an entry, it inherits all the properies of entries
-too.
-
-Note that the `allow_missing` member controls whether this section permits
-external blobs to be missing their contents. The option will produce an
-image but of course it will not work. It is useful to make sure that
-Continuous Integration systems can build without the binaries being
-available. This is set by the `SetAllowMissing()` method, if
-`--allow-missing` is passed to binman.
-
-
-
-.. _etype_tee_os:
-
-Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
----------------------------------------------------------------
-
-Properties / Entry arguments:
- - tee-os-path: Filename of file to read into entry. This is typically
- called tee.bin or tee.elf
-
-This entry holds the run-time firmware, typically started by U-Boot SPL.
-See the U-Boot README for your architecture or board for how to use it. See
-https://github.com/OP-TEE/optee_os for more information about OP-TEE.
-
-Note that if the file is in ELF format, it must go in a FIT. In that case,
-this entry will mark itself as absent, providing the data only through the
-read_elf_segments() method.
-
-Marking this entry as absent means that it if is used in the wrong context
-it can be automatically dropped. Thus it is possible to add an OP-TEE entry
-like this::
-
- binman {
- tee-os {
- };
- };
-
-and pass either an ELF or plain binary in with -a tee-os-path <filename>
-and have binman do the right thing:
-
- - include the entry if tee.bin is provided and it does NOT have the v1
- header
- - drop it otherwise
-
-When used within a FIT, we can do::
-
- binman {
- fit {
- tee-os {
- };
- };
- };
-
-which will split the ELF into separate nodes for each segment, if an ELF
-file is provided (see :ref:`etype_fit`), or produce a single node if the
-OP-TEE binary v1 format is provided (see optee_doc_) .
-
-.. _optee_doc: https://optee.readthedocs.io/en/latest/architecture/core.html#partitioning-of-the-binary
-
-
-
-.. _etype_text:
-
-Entry: text: An entry which contains text
------------------------------------------
-
-The text can be provided either in the node itself or by a command-line
-argument. There is a level of indirection to allow multiple text strings
-and sharing of text.
-
-Properties / Entry arguments:
- text-label: The value of this string indicates the property / entry-arg
- that contains the string to place in the entry
- <xxx> (actual name is the value of text-label): contains the string to
- place in the entry.
- <text>: The text to place in the entry (overrides the above mechanism).
- This is useful when the text is constant.
-
-Example node::
-
- text {
- size = <50>;
- text-label = "message";
- };
-
-You can then use:
-
- binman -amessage="this is my message"
-
-and binman will insert that string into the entry.
-
-It is also possible to put the string directly in the node::
-
- text {
- size = <8>;
- text-label = "message";
- message = "a message directly in the node"
- };
-
-or just::
-
- text {
- size = <8>;
- text = "some text directly in the node"
- };
-
-The text is not itself nul-terminated. This can be achieved, if required,
-by setting the size of the entry to something larger than the text.
-
-
-
-.. _etype_ti_board_config:
-
-Entry: ti-board-config: An entry containing a TI schema validated board config binary
--------------------------------------------------------------------------------------
-
-This etype supports generation of two kinds of board configuration
-binaries: singular board config binary as well as combined board config
-binary.
-
-Properties / Entry arguments:
- - config-file: File containing board configuration data in YAML
- - schema-file: File containing board configuration YAML schema against
- which the config file is validated
-
-Output files:
- - board config binary: File containing board configuration binary
-
-These above parameters are used only when the generated binary is
-intended to be a single board configuration binary. Example::
-
- my-ti-board-config {
- ti-board-config {
- config = "board-config.yaml";
- schema = "schema.yaml";
- };
- };
-
-To generate a combined board configuration binary, we pack the
-needed individual binaries into a ti-board-config binary. In this case,
-the available supported subnode names are board-cfg, pm-cfg, sec-cfg and
-rm-cfg. The final binary is prepended with a header containing details about
-the included board config binaries. Example::
-
- my-combined-ti-board-config {
- ti-board-config {
- board-cfg {
- config = "board-cfg.yaml";
- schema = "schema.yaml";
- };
- sec-cfg {
- config = "sec-cfg.yaml";
- schema = "schema.yaml";
- };
- }
- }
-
-
-
-.. _etype_ti_dm:
-
-Entry: ti-dm: TI Device Manager (DM) blob
------------------------------------------
-
-Properties / Entry arguments:
- - ti-dm-path: Filename of file to read into the entry, typically ti-dm.bin
-
-This entry holds the device manager responsible for resource and power management
-in K3 devices. See https://software-dl.ti.com/tisci/esd/latest/ for more information
-about TI DM.
-
-
-
-.. _etype_ti_secure:
-
-Entry: ti-secure: Entry containing a TI x509 certificate binary
----------------------------------------------------------------
-
-Properties / Entry arguments:
- - content: List of phandles to entries to sign
- - keyfile: Filename of file containing key to sign binary with
- - sha: Hash function to be used for signing
- - auth-in-place: This is an integer field that contains two pieces
- of information:
-
- - Lower Byte - Remains 0x02 as per our use case
- ( 0x02: Move the authenticated binary back to the header )
- - Upper Byte - The Host ID of the core owning the firewall
-
-Output files:
- - input.<unique_name> - input file passed to openssl
- - config.<unique_name> - input file generated for openssl (which is
- used as the config file)
- - cert.<unique_name> - output file generated by openssl (which is
- used as the entry contents)
-
-Depending on auth-in-place information in the inputs, we read the
-firewall nodes that describe the configurations of firewall that TIFS
-will be doing after reading the certificate.
-
-The syntax of the firewall nodes are as such::
-
- firewall-257-0 {
- id = <257>; /* The ID of the firewall being configured */
- region = <0>; /* Region number to configure */
-
- control = /* The control register */
- <(FWCTRL_EN | FWCTRL_LOCK | FWCTRL_BG | FWCTRL_CACHE)>;
-
- permissions = /* The permission registers */
- <((FWPRIVID_ALL << FWPRIVID_SHIFT) |
- FWPERM_SECURE_PRIV_RWCD |
- FWPERM_SECURE_USER_RWCD |
- FWPERM_NON_SECURE_PRIV_RWCD |
- FWPERM_NON_SECURE_USER_RWCD)>;
-
- /* More defines can be found in k3-security.h */
-
- start_address = /* The Start Address of the firewall */
- <0x0 0x0>;
- end_address = /* The End Address of the firewall */
- <0xff 0xffffffff>;
- };
-
-
-openssl signs the provided data, using the TI templated config file and
-writes the signature in this entry. This allows verification that the
-data is genuine.
-
-
-
-.. _etype_ti_secure_rom:
-
-Entry: ti-secure-rom: Entry containing a TI x509 certificate binary for images booted by ROM
---------------------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - keyfile: Filename of file containing key to sign binary with
- - combined: boolean if device follows combined boot flow
- - countersign: boolean if device contains countersigned system firmware
- - load: load address of SPL
- - sw-rev: software revision
- - sha: Hash function to be used for signing
- - core: core on which bootloader runs, valid cores are 'secure' and 'public'
- - content: phandle of SPL in case of legacy bootflow or phandles of component binaries
- in case of combined bootflow
- - core-opts (optional): lockstep (0) or split (2) mode set to 0 by default
-
-The following properties are only for generating a combined bootflow binary:
- - sysfw-inner-cert: boolean if binary contains sysfw inner certificate
- - dm-data: boolean if binary contains dm-data binary
- - content-sbl: phandle of SPL binary
- - content-sysfw: phandle of sysfw binary
- - content-sysfw-data: phandle of sysfw-data or tifs-data binary
- - content-sysfw-inner-cert (optional): phandle of sysfw inner certificate binary
- - content-dm-data (optional): phandle of dm-data binary
- - load-sysfw: load address of sysfw binary
- - load-sysfw-data: load address of sysfw-data or tifs-data binary
- - load-sysfw-inner-cert (optional): load address of sysfw inner certificate binary
- - load-dm-data (optional): load address of dm-data binary
-
-Output files:
- - input.<unique_name> - input file passed to openssl
- - config.<unique_name> - input file generated for openssl (which is
- used as the config file)
- - cert.<unique_name> - output file generated by openssl (which is
- used as the entry contents)
-
-openssl signs the provided data, using the TI templated config file and
-writes the signature in this entry. This allows verification that the
-data is genuine.
-
-
-
-.. _etype_u_boot:
-
-Entry: u-boot: U-Boot flat binary
----------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot.bin (default 'u-boot.bin')
-
-This is the U-Boot binary, containing relocation information to allow it
-to relocate itself at runtime. The binary typically includes a device tree
-blob at the end of it.
-
-U-Boot can access binman symbols at runtime. See :ref:`binman_fdt`.
-
-Note that this entry is automatically replaced with u-boot-expanded unless
---no-expanded is used or the node has a 'no-expanded' property.
-
-
-
-.. _etype_u_boot_dtb:
-
-Entry: u-boot-dtb: U-Boot device tree
--------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
-
-This is the U-Boot device tree, containing configuration information for
-U-Boot. U-Boot needs this to know what devices are present and which drivers
-to activate.
-
-Note: This is mostly an internal entry type, used by others. This allows
-binman to know which entries contain a device tree.
-
-
-
-.. _etype_u_boot_dtb_with_ucode:
-
-Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
------------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
-
-See Entry_u_boot_ucode for full details of the three entries involved in
-this process. This entry provides the U-Boot device-tree file, which
-contains the microcode. If the microcode is not being collated into one
-place then the offset and size of the microcode is recorded by this entry,
-for use by u-boot-with-ucode_ptr. If it is being collated, then this
-entry deletes the microcode from the device tree (to save space) and makes
-it available to u-boot-ucode.
-
-
-
-.. _etype_u_boot_elf:
-
-Entry: u-boot-elf: U-Boot ELF image
------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot (default 'u-boot')
-
-This is the U-Boot ELF image. It does not include a device tree but can be
-relocated to any address for execution.
-
-
-
-.. _etype_u_boot_env:
-
-Entry: u-boot-env: An entry which contains a U-Boot environment
----------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: File containing the environment text, with each line in the
- form var=value
-
-
-
-.. _etype_u_boot_expanded:
-
-Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
-------------------------------------------------------------------------------
-
-This is a section containing the U-Boot binary and a devicetree. Using this
-entry type automatically creates this section, with the following entries
-in it:
-
- u-boot-nodtb
- u-boot-dtb
-
-Having the devicetree separate allows binman to update it in the final
-image, so that the entries positions are provided to the running U-Boot.
-
-
-
-.. _etype_u_boot_img:
-
-Entry: u-boot-img: U-Boot legacy image
---------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot.img (default 'u-boot.img')
-
-This is the U-Boot binary as a packaged image, in legacy format. It has a
-header which allows it to be loaded at the correct address for execution.
-
-You should use FIT (Flat Image Tree) instead of the legacy image for new
-applications.
-
-
-
-.. _etype_u_boot_nodtb:
-
-Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
---------------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename to include (default 'u-boot-nodtb.bin')
-
-This is the U-Boot binary, containing relocation information to allow it
-to relocate itself at runtime. It does not include a device tree blob at
-the end of it so normally cannot work without it. You can add a u-boot-dtb
-entry after this one, or use a u-boot entry instead, normally expands to a
-section containing u-boot and u-boot-dtb
-
-
-
-.. _etype_u_boot_spl:
-
-Entry: u-boot-spl: U-Boot SPL binary
-------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
-
-This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
-binary which loads before U-Boot proper, typically into on-chip SRAM. It is
-responsible for locating, loading and jumping to U-Boot. Note that SPL is
-not relocatable so must be loaded to the correct address in SRAM, or written
-to run from the correct address if direct flash execution is possible (e.g.
-on x86 devices).
-
-SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
-
-in the binman README for more information.
-
-The ELF file 'spl/u-boot-spl' must also be available for this to work, since
-binman uses that to look up symbols to write into the SPL binary.
-
-Note that this entry is automatically replaced with u-boot-spl-expanded
-unless --no-expanded is used or the node has a 'no-expanded' property.
-
-
-
-.. _etype_u_boot_spl_bss_pad:
-
-Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
----------------------------------------------------------------------
-
-Properties / Entry arguments:
- None
-
-This holds the padding added after the SPL binary to cover the BSS (Block
-Started by Symbol) region. This region holds the various variables used by
-SPL. It is set to 0 by SPL when it starts up. If you want to append data to
-the SPL image (such as a device tree file), you must pad out the BSS region
-to avoid the data overlapping with U-Boot variables. This entry is useful in
-that case. It automatically pads out the entry size to cover both the code,
-data and BSS.
-
-The contents of this entry will a certain number of zero bytes, determined
-by __bss_size
-
-The ELF file 'spl/u-boot-spl' must also be available for this to work, since
-binman uses that to look up the BSS address.
-
-
-
-.. _etype_u_boot_spl_dtb:
-
-Entry: u-boot-spl-dtb: U-Boot SPL device tree
----------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
-
-This is the SPL device tree, containing configuration information for
-SPL. SPL needs this to know what devices are present and which drivers
-to activate.
-
-
-
-.. _etype_u_boot_spl_elf:
-
-Entry: u-boot-spl-elf: U-Boot SPL ELF image
--------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
-
-This is the U-Boot SPL ELF image. It does not include a device tree but can
-be relocated to any address for execution.
-
-
-
-.. _etype_u_boot_spl_expanded:
-
-Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
---------------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
- select)
-
-This is a section containing the U-Boot binary, BSS padding if needed and a
-devicetree. Using this entry type automatically creates this section, with
-the following entries in it:
-
- u-boot-spl-nodtb
- u-boot-spl-bss-pad
- u-boot-dtb
-
-Having the devicetree separate allows binman to update it in the final
-image, so that the entries positions are provided to the running U-Boot.
-
-This entry is selected based on the value of the 'spl-dtb' entryarg. If
-this is non-empty (and not 'n' or '0') then this expanded entry is selected.
-
-
-
-.. _etype_u_boot_spl_nodtb:
-
-Entry: u-boot-spl-nodtb: SPL binary without device tree appended
-----------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin')
-
-This is the U-Boot SPL binary, It does not include a device tree blob at
-the end of it so may not be able to work without it, assuming SPL needs
-a device tree to operate on your platform. You can add a u-boot-spl-dtb
-entry after this one, or use a u-boot-spl entry instead' which normally
-expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
-u-boot-spl-dtb
-
-SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
-
-The ELF file 'spl/u-boot-spl' must also be available for this to work, since
-binman uses that to look up symbols to write into the SPL binary.
-
-
-
-.. _etype_u_boot_spl_pubkey_dtb:
-
-Entry: u-boot-spl-pubkey-dtb: U-Boot SPL device tree including public key
--------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - key-name-hint: Public key name without extension (.crt).
- Default is determined by underlying
- bintool (fdt_add_pubkey), usually 'key'.
- - algo: (Optional) Algorithm used for signing. Default is determined by
- underlying bintool (fdt_add_pubkey), usually 'sha1,rsa2048'
- - required: (Optional) If present this indicates that the key must be
- verified for the image / configuration to be
- considered valid
-
-The following example shows an image containing an SPL which
-is packed together with the dtb. Binman will add a signature
-node to the dtb.
-
-Example node::
-
- image {
- ...
- spl {
- filename = "spl.bin"
-
- u-boot-spl-nodtb {
- };
- u-boot-spl-pubkey-dtb {
- algo = "sha384,rsa4096";
- required = "conf";
- key-name-hint = "dev";
- };
- };
- ...
- }
-
-
-
-.. _etype_u_boot_spl_with_ucode_ptr:
-
-Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
-----------------------------------------------------------------------------
-
-This is used when SPL must set up the microcode for U-Boot.
-
-See Entry_u_boot_ucode for full details of the entries involved in this
-process.
-
-
-
-.. _etype_u_boot_tpl:
-
-Entry: u-boot-tpl: U-Boot TPL binary
-------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
-
-This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
-binary which loads before SPL, typically into on-chip SRAM. It is
-responsible for locating, loading and jumping to SPL, the next-stage
-loader. Note that SPL is not relocatable so must be loaded to the correct
-address in SRAM, or written to run from the correct address if direct
-flash execution is possible (e.g. on x86 devices).
-
-SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
-
-in the binman README for more information.
-
-The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
-binman uses that to look up symbols to write into the TPL binary.
-
-Note that this entry is automatically replaced with u-boot-tpl-expanded
-unless --no-expanded is used or the node has a 'no-expanded' property.
-
-
-
-.. _etype_u_boot_tpl_bss_pad:
-
-Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
----------------------------------------------------------------------
-
-Properties / Entry arguments:
- None
-
-This holds the padding added after the TPL binary to cover the BSS (Block
-Started by Symbol) region. This region holds the various variables used by
-TPL. It is set to 0 by TPL when it starts up. If you want to append data to
-the TPL image (such as a device tree file), you must pad out the BSS region
-to avoid the data overlapping with U-Boot variables. This entry is useful in
-that case. It automatically pads out the entry size to cover both the code,
-data and BSS.
-
-The contents of this entry will a certain number of zero bytes, determined
-by __bss_size
-
-The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
-binman uses that to look up the BSS address.
-
-
-
-.. _etype_u_boot_tpl_dtb:
-
-Entry: u-boot-tpl-dtb: U-Boot TPL device tree
----------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
-
-This is the TPL device tree, containing configuration information for
-TPL. TPL needs this to know what devices are present and which drivers
-to activate.
-
-
-
-.. _etype_u_boot_tpl_dtb_with_ucode:
-
-Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
-----------------------------------------------------------------------------
-
-This is used when TPL must set up the microcode for U-Boot.
-
-See Entry_u_boot_ucode for full details of the entries involved in this
-process.
-
-
-
-.. _etype_u_boot_tpl_elf:
-
-Entry: u-boot-tpl-elf: U-Boot TPL ELF image
--------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
-
-This is the U-Boot TPL ELF image. It does not include a device tree but can
-be relocated to any address for execution.
-
-
-
-.. _etype_u_boot_tpl_expanded:
-
-Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
---------------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
- select)
-
-This is a section containing the U-Boot binary, BSS padding if needed and a
-devicetree. Using this entry type automatically creates this section, with
-the following entries in it:
-
- u-boot-tpl-nodtb
- u-boot-tpl-bss-pad
- u-boot-dtb
-
-Having the devicetree separate allows binman to update it in the final
-image, so that the entries positions are provided to the running U-Boot.
-
-This entry is selected based on the value of the 'tpl-dtb' entryarg. If
-this is non-empty (and not 'n' or '0') then this expanded entry is selected.
-
-
-
-.. _etype_u_boot_tpl_nodtb:
-
-Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
-----------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin')
-
-This is the U-Boot TPL binary, It does not include a device tree blob at
-the end of it so may not be able to work without it, assuming TPL needs
-a device tree to operate on your platform. You can add a u-boot-tpl-dtb
-entry after this one, or use a u-boot-tpl entry instead, which normally
-expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
-u-boot-tpl-dtb
-
-TPL can access binman symbols at runtime. See :ref:`binman_fdt`.
-
-The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
-binman uses that to look up symbols to write into the TPL binary.
-
-
-
-.. _etype_u_boot_tpl_with_ucode_ptr:
-
-Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
-----------------------------------------------------------------------------
-
-See Entry_u_boot_ucode for full details of the entries involved in this
-process.
-
-
-
-.. _etype_u_boot_ucode:
-
-Entry: u-boot-ucode: U-Boot microcode block
--------------------------------------------
-
-Properties / Entry arguments:
- None
-
-The contents of this entry are filled in automatically by other entries
-which must also be in the image.
-
-U-Boot on x86 needs a single block of microcode. This is collected from
-the various microcode update nodes in the device tree. It is also unable
-to read the microcode from the device tree on platforms that use FSP
-(Firmware Support Package) binaries, because the API requires that the
-microcode is supplied before there is any SRAM available to use (i.e.
-the FSP sets up the SRAM / cache-as-RAM but does so in the call that
-requires the microcode!). To keep things simple, all x86 platforms handle
-microcode the same way in U-Boot (even non-FSP platforms). This is that
-a table is placed at _dt_ucode_base_size containing the base address and
-size of the microcode. This is either passed to the FSP (for FSP
-platforms), or used to set up the microcode (for non-FSP platforms).
-This all happens in the build system since it is the only way to get
-the microcode into a single blob and accessible without SRAM.
-
-There are two cases to handle. If there is only one microcode blob in
-the device tree, then the ucode pointer it set to point to that. This
-entry (u-boot-ucode) is empty. If there is more than one update, then
-this entry holds the concatenation of all updates, and the device tree
-entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
-last step ensures that that the microcode appears in one contiguous
-block in the image and is not unnecessarily duplicated in the device
-tree. It is referred to as 'collation' here.
-
-Entry types that have a part to play in handling microcode:
-
- Entry_u_boot_with_ucode_ptr:
- Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
- It updates it with the address and size of the microcode so that
- U-Boot can find it early on start-up.
- Entry_u_boot_dtb_with_ucode:
- Contains u-boot.dtb. It stores the microcode in a
- 'self.ucode_data' property, which is then read by this class to
- obtain the microcode if needed. If collation is performed, it
- removes the microcode from the device tree.
- Entry_u_boot_ucode:
- This class. If collation is enabled it reads the microcode from
- the Entry_u_boot_dtb_with_ucode entry, and uses it as the
- contents of this entry.
-
-
-
-.. _etype_u_boot_vpl:
-
-Entry: u-boot-vpl: U-Boot VPL binary
-------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-vpl.bin (default 'vpl/u-boot-vpl.bin')
-
-This is the U-Boot VPL (Verifying Program Loader) binary. This is a small
-binary which loads before SPL, typically into on-chip SRAM. It is
-responsible for locating, loading and jumping to SPL, the next-stage
-loader. Note that VPL is not relocatable so must be loaded to the correct
-address in SRAM, or written to run from the correct address if direct
-flash execution is possible (e.g. on x86 devices).
-
-SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
-
-in the binman README for more information.
-
-The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
-binman uses that to look up symbols to write into the VPL binary.
-
-Note that this entry is automatically replaced with u-boot-vpl-expanded
-unless --no-expanded is used or the node has a 'no-expanded' property.
-
-
-
-.. _etype_u_boot_vpl_bss_pad:
-
-Entry: u-boot-vpl-bss-pad: U-Boot VPL binary padded with a BSS region
----------------------------------------------------------------------
-
-Properties / Entry arguments:
- None
-
-This holds the padding added after the VPL binary to cover the BSS (Block
-Started by Symbol) region. This region holds the various variables used by
-VPL. It is set to 0 by VPL when it starts up. If you want to append data to
-the VPL image (such as a device tree file), you must pad out the BSS region
-to avoid the data overlapping with U-Boot variables. This entry is useful in
-that case. It automatically pads out the entry size to cover both the code,
-data and BSS.
-
-The contents of this entry will a certain number of zero bytes, determined
-by __bss_size
-
-The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
-binman uses that to look up the BSS address.
-
-
-
-.. _etype_u_boot_vpl_dtb:
-
-Entry: u-boot-vpl-dtb: U-Boot VPL device tree
----------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot.dtb (default 'vpl/u-boot-vpl.dtb')
-
-This is the VPL device tree, containing configuration information for
-VPL. VPL needs this to know what devices are present and which drivers
-to activate.
-
-
-
-.. _etype_u_boot_vpl_elf:
-
-Entry: u-boot-vpl-elf: U-Boot VPL ELF image
--------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of VPL u-boot (default 'vpl/u-boot-vpl')
-
-This is the U-Boot VPL ELF image. It does not include a device tree but can
-be relocated to any address for execution.
-
-
-
-.. _etype_u_boot_vpl_expanded:
-
-Entry: u-boot-vpl-expanded: U-Boot VPL flat binary broken out into its component parts
---------------------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - vpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
- select)
-
-This is a section containing the U-Boot binary, BSS padding if needed and a
-devicetree. Using this entry type automatically creates this section, with
-the following entries in it:
-
- u-boot-vpl-nodtb
- u-boot-vpl-bss-pad
- u-boot-dtb
-
-Having the devicetree separate allows binman to update it in the final
-image, so that the entries positions are provided to the running U-Boot.
-
-This entry is selected based on the value of the 'vpl-dtb' entryarg. If
-this is non-empty (and not 'n' or '0') then this expanded entry is selected.
-
-
-
-.. _etype_u_boot_vpl_nodtb:
-
-Entry: u-boot-vpl-nodtb: VPL binary without device tree appended
-----------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename to include (default 'vpl/u-boot-vpl-nodtb.bin')
-
-This is the U-Boot VPL binary, It does not include a device tree blob at
-the end of it so may not be able to work without it, assuming VPL needs
-a device tree to operate on your platform. You can add a u-boot-vpl-dtb
-entry after this one, or use a u-boot-vpl entry instead, which normally
-expands to a section containing u-boot-vpl-dtb, u-boot-vpl-bss-pad and
-u-boot-vpl-dtb
-
-VPL can access binman symbols at runtime. See :ref:`binman_fdt`.
-
-The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
-binman uses that to look up symbols to write into the VPL binary.
-
-
-
-.. _etype_u_boot_with_ucode_ptr:
-
-Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
---------------------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
- - optional-ucode: boolean property to make microcode optional. If the
- u-boot.bin image does not include microcode, no error will
- be generated.
-
-See Entry_u_boot_ucode for full details of the three entries involved in
-this process. This entry updates U-Boot with the offset and size of the
-microcode, to allow early x86 boot code to find it without doing anything
-complicated. Otherwise it is the same as the u-boot entry.
-
-
-
-.. _etype_vblock:
-
-Entry: vblock: An entry which contains a Chromium OS verified boot block
-------------------------------------------------------------------------
-
-Properties / Entry arguments:
- - content: List of phandles to entries to sign
- - keydir: Directory containing the public keys to use
- - keyblock: Name of the key file to use (inside keydir)
- - signprivate: Name of provide key file to use (inside keydir)
- - version: Version number of the vblock (typically 1)
- - kernelkey: Name of the kernel key to use (inside keydir)
- - preamble-flags: Value of the vboot preamble flags (typically 0)
-
-Output files:
- - input.<unique_name> - input file passed to futility
- - vblock.<unique_name> - output file generated by futility (which is
- used as the entry contents)
-
-Chromium OS signs the read-write firmware and kernel, writing the signature
-in this block. This allows U-Boot to verify that the next firmware stage
-and kernel are genuine.
-
-
-
-.. _etype_x509_cert:
-
-Entry: x509-cert: An entry which contains an X509 certificate
--------------------------------------------------------------
-
-Properties / Entry arguments:
- - content: List of phandles to entries to sign
-
-Output files:
- - input.<unique_name> - input file passed to openssl
- - cert.<unique_name> - output file generated by openssl (which is
- used as the entry contents)
-
-openssl signs the provided data, writing the signature in this entry. This
-allows verification that the data is genuine
-
-
-
-.. _etype_x86_reset16:
-
-Entry: x86-reset16: x86 16-bit reset code for U-Boot
-----------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-x86-reset16.bin (default
- 'u-boot-x86-reset16.bin')
-
-x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
-must be placed at a particular address. This entry holds that code. It is
-typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
-for jumping to the x86-start16 code, which continues execution.
-
-For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
-
-
-
-.. _etype_x86_reset16_spl:
-
-Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
---------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-x86-reset16.bin (default
- 'u-boot-x86-reset16.bin')
-
-x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
-must be placed at a particular address. This entry holds that code. It is
-typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
-for jumping to the x86-start16 code, which continues execution.
-
-For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
-
-
-
-.. _etype_x86_reset16_tpl:
-
-Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
---------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-x86-reset16.bin (default
- 'u-boot-x86-reset16.bin')
-
-x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
-must be placed at a particular address. This entry holds that code. It is
-typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
-for jumping to the x86-start16 code, which continues execution.
-
-For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
-
-
-
-.. _etype_x86_start16:
-
-Entry: x86-start16: x86 16-bit start-up code for U-Boot
--------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of u-boot-x86-start16.bin (default
- 'u-boot-x86-start16.bin')
-
-x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
-must be placed in the top 64KB of the ROM. The reset code jumps to it. This
-entry holds that code. It is typically placed at offset
-CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
-and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
-U-Boot).
-
-For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
-
-
-
-.. _etype_x86_start16_spl:
-
-Entry: x86-start16-spl: x86 16-bit start-up code for SPL
---------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
- 'spl/u-boot-x86-start16-spl.bin')
-
-x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
-must be placed in the top 64KB of the ROM. The reset code jumps to it. This
-entry holds that code. It is typically placed at offset
-CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
-and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
-U-Boot).
-
-For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
-
-
-
-.. _etype_x86_start16_tpl:
-
-Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
---------------------------------------------------------
-
-Properties / Entry arguments:
- - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
- 'tpl/u-boot-x86-start16-tpl.bin')
-
-x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
-must be placed in the top 64KB of the ROM. The reset code jumps to it. This
-entry holds that code. It is typically placed at offset
-CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
-and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
-U-Boot).
-
-If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
-may be used instead.
-
-
-
-.. _etype_xilinx_bootgen:
-
-Entry: xilinx-bootgen: Signed SPL boot image for Xilinx ZynqMP devices
-----------------------------------------------------------------------
-
-Properties / Entry arguments:
- - auth-params: (Optional) Authentication parameters passed to bootgen
- - fsbl-config: (Optional) FSBL parameters passed to bootgen
- - keysrc-enc: (Optional) Key source when using decryption engine
- - pmufw-filename: Filename of PMU firmware. Default: pmu-firmware.elf
- - psk-key-name-hint: Name of primary secret key to use for signing the
- secondardy public key. Format: .pem file
- - ssk-key-name-hint: Name of secondardy secret key to use for signing
- the boot image. Format: .pem file
-
-The etype is used to create a boot image for Xilinx ZynqMP
-devices.
-
-Information for signed images:
-
-In AMD/Xilinx SoCs, two pairs of public and secret keys are used
-- primary and secondary. The function of the primary public/secret key pair
-is to authenticate the secondary public/secret key pair.
-The function of the secondary key is to sign/verify the boot image. [1]
-
-AMD/Xilinx uses the following terms for private/public keys [1]:
-
- PSK = Primary Secret Key (Used to sign Secondary Public Key)
- PPK = Primary Public Key (Used to verify Secondary Public Key)
- SSK = Secondary Secret Key (Used to sign the boot image/partitions)
- SPK = Used to verify the actual boot image
-
-The following example builds a signed boot image. The fuses of
-the primary public key (ppk) should be fused together with the RSA_EN flag.
-
-Example node::
-
- spl {
- filename = "boot.signed.bin";
-
- xilinx-bootgen {
- psk-key-name-hint = "psk0";
- ssk-key-name-hint = "ssk0";
- auth-params = "ppk_select=0", "spk_id=0x00000000";
-
- u-boot-spl-nodtb {
- };
- u-boot-spl-pubkey-dtb {
- algo = "sha384,rsa4096";
- required = "conf";
- key-name-hint = "dev";
- };
- };
- };
-
-For testing purposes, e.g. if no RSA_EN should be fused, one could add
-the "bh_auth_enable" flag in the fsbl-config field. This will skip the
-verification of the ppk fuses and boot the image, even if ppk hash is
-invalid.
-
-Example node::
-
- xilinx-bootgen {
- psk-key-name-hint = "psk0";
- psk-key-name-hint = "ssk0";
- ...
- fsbl-config = "bh_auth_enable";
- ...
- };
-
-[1] https://docs.xilinx.com/r/en-US/ug1283-bootgen-user-guide/Using-Authentication
-
-
-
-
--
2.43.0
More information about the U-Boot
mailing list