From: Simon Glass Date: Sat, 7 Jan 2023 21:07:10 +0000 (-0700) Subject: binman: Update entry docs X-Git-Url: http://git.dujemihanovic.xyz/?a=commitdiff_plain;h=237ac96a7033d991763c7f3398c93f8ba769707a;p=u-boot.git binman: Update entry docs These have got out of data recently. Regenerate them. Signed-off-by: Simon Glass --- diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst index 3dc32db8a5..b2ce7960d3 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 -n test -T imximage 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 c2288c48ee..cb264c3cad 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::