These have got out of data recently. Regenerate them.
Signed-off-by: Simon Glass sjg@chromium.org ---
Changes in v6: - Add new patch to update entry docs
tools/binman/entries.rst | 187 ++++++++++++++++++++++++++++++++++----- 1 file changed, 163 insertions(+), 24 deletions(-)
diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst index 3dc32db8a54..ec7465d0127 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,24 +1211,27 @@ a section, or just multiple subnodes like this:: }; };
-To pass all datafiles untouched to mkimage:: +Note that binman places the contents (here SPL and TPL) into a single file +and passes that to mkimage using the -d option.
- mkimage { - args = "-n rk3399 -T rkspi"; - multiple-data-files; +pass all datafiles untouched to mkimage::
- u-boot-tpl { - }; +image { +rgs = "-n rk3399 -T rkspi"; +ultiple-data-files;
- u-boot-spl { - }; - }; +-boot-tpl { +;
-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. +-boot-spl { +; + + +s calls mkimage to create a Rockchip RK3399-specific first stage +tloader, made of TPL+SPL. Since this first stage bootloader requires to +gn the TPL and SPL but also some weird hacks that is handled by mkimage +ectly, binman is told to not perform the concatenation of datafiles prior +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:: @@ -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