diff options
Diffstat (limited to 'tools/binman/entries.rst')
| -rw-r--r-- | tools/binman/entries.rst | 237 |
1 files changed, 203 insertions, 34 deletions
diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst index 3dc32db8a5..2b32c131ed 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,20 @@ 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_opensbi: Entry: opensbi: RISC-V OpenSBI fw_dynamic blob @@ -1478,6 +1498,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. @@ -1497,12 +1521,47 @@ 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-pager.bin + 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: @@ -1567,11 +1626,7 @@ 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: - - 'Access to binman entry offsets at run time (fdt)' - -in the binman README for more information. +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. @@ -1701,9 +1756,7 @@ 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)' +SPL can access binman symbols at runtime. See :ref:`binman_fdt`. in the binman README for more information. @@ -1806,9 +1859,7 @@ 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: - - 'Access to binman entry offsets at run time (symbols)' +SPL can access binman symbols at runtime. See :ref:`binman_fdt`. in the binman README for more information. @@ -1844,9 +1895,7 @@ 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: - - 'Access to binman entry offsets at run time (symbols)' +SPL can access binman symbols at runtime. See :ref:`binman_fdt`. in the binman README for more information. @@ -1961,9 +2010,7 @@ 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: - - 'Access to binman entry offsets at run time (symbols)' +TPL can access binman symbols at runtime. See :ref:`binman_fdt`. in the binman README for more information. @@ -2034,6 +2081,128 @@ 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 :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. + + + +.. _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 |