[PATCH v8 03/13] binman: Update entry docs
Simon Glass
sjg at chromium.org
Thu Dec 22 00:07:16 CET 2022
These have got out of data recently. Regenerate them.
Signed-off-by: Simon Glass <sjg at chromium.org>
---
(no changes since v7)
Changes in v7:
- Correct an rST formatting error
Changes in v6:
- Add new patch to update entry docs
tools/binman/entries.rst | 171 ++++++++++++++++++++++++++++++----
tools/binman/etype/mkimage.py | 28 +++---
2 files changed, 169 insertions(+), 30 deletions(-)
diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst
index 3dc32db8a54..b2ce7960d3b 100644
--- a/tools/binman/entries.rst
+++ b/tools/binman/entries.rst
@@ -216,9 +216,9 @@ 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 Properties / Entry arguments:
- - prepend: Header type to use:
- length: 32-bit length header
+Additional attributes:
+ prepend: Header used (e.g. 'length')
+
.. _etype_blob_ext:
@@ -1178,11 +1178,13 @@ Properties / Entry arguments:
- 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 {
@@ -1190,13 +1192,14 @@ mkimage node, e.g.::
};
This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
-file, which mkimage being called like this::
+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. If you need to put mulitple things in the data file, you can use
-a section, or just multiple subnodes like this::
+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";
@@ -1208,17 +1211,20 @@ a section, or just multiple subnodes like this::
};
};
+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;
+ args = "-n rk3399 -T rkspi";
+ multiple-data-files;
- u-boot-tpl {
- };
+ u-boot-tpl {
+ };
- u-boot-spl {
- };
+ u-boot-spl {
+ };
};
This calls mkimage to create a Rockchip RK3399-specific first stage
@@ -1242,17 +1248,17 @@ the 'data-to-imagename' property::
mkimage {
args = "-T imximage";
- data-to-imagename';
+ 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).
-
+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::
+If need to pass different data in with -n, then use an `imagename` subnode::
mkimage {
args = "-T imximage";
@@ -1271,6 +1277,7 @@ This will pass in u-boot-spl as the input data and the .cfgout file as the
-n data.
+
.. _etype_opensbi:
Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
@@ -1478,6 +1485,10 @@ skip-at-start
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.
@@ -2034,6 +2045,134 @@ Entry types that have a part to play in handling microcode:
+.. _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:
+
+ 'Access to binman entry offsets at run time (symbols)'
+
+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.
+
+
+
+.. _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:
+
+ 'Access to binman entry offsets at run time (symbols)'
+
+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.
+
+
+
.. _etype_u_boot_with_ucode_ptr:
Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
diff --git a/tools/binman/etype/mkimage.py b/tools/binman/etype/mkimage.py
index c2288c48eef..cb264c3cad0 100644
--- a/tools/binman/etype/mkimage.py
+++ b/tools/binman/etype/mkimage.py
@@ -57,24 +57,24 @@ class Entry_mkimage(Entry):
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::
+ To pass all datafiles untouched to mkimage::
- mkimage {
- args = "-n rk3399 -T rkspi";
- multiple-data-files;
+ mkimage {
+ args = "-n rk3399 -T rkspi";
+ multiple-data-files;
- u-boot-tpl {
- };
+ u-boot-tpl {
+ };
- u-boot-spl {
- };
- };
+ 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.
+ 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::
--
2.39.0.314.g84b9a713c41-goog
More information about the U-Boot
mailing list