1 Binman Entry Documentation
2 ===========================
4 This file describes the entry types supported by binman. These entry types can
5 be placed in an image one by one to build up a final firmware image. It is
6 fairly easy to create new entry types. Just add a new file to the 'etype'
7 directory. You can use the existing entries as examples.
9 Note that some entries are subclasses of others, using and extending their
10 features to produce new behaviours.
16 Entry: atf-bl31: ARM Trusted Firmware (ATF) BL31 blob
17 -----------------------------------------------------
19 Properties / Entry arguments:
20 - atf-bl31-path: Filename of file to read into entry. This is typically
21 called bl31.bin or bl31.elf
23 This entry holds the run-time firmware, typically started by U-Boot SPL.
24 See the U-Boot README for your architecture or board for how to use it. See
25 https://github.com/ARM-software/arm-trusted-firmware for more information
32 Entry: atf-fip: ARM Trusted Firmware's Firmware Image Package (FIP)
33 -------------------------------------------------------------------
35 A FIP_ provides a way to group binaries in a firmware image, used by ARM's
36 Trusted Firmware A (TF-A) code. It is a simple format consisting of a
37 table of contents with information about the type, offset and size of the
38 binaries in the FIP. It is quite similar to FMAP, with the major difference
39 that it uses UUIDs to indicate the type of each entry.
41 Note: It is recommended to always add an fdtmap to every image, as well as
42 any FIPs so that binman and other tools can access the entire image
45 The UUIDs correspond to useful names in `fiptool`, provided by ATF to
46 operate on FIPs. Binman uses these names to make it easier to understand
47 what is going on, although it is possible to provide a UUID if needed.
49 The contents of the FIP are defined by subnodes of the atf-fip entry, e.g.::
53 filename = "bl31.bin";
57 filename = "bl2u.bin";
65 This describes a FIP with three entries: soc-fw, scp-fwu-cfg and nt-fw.
66 You can use normal (non-external) binaries like U-Boot simply by adding a
67 FIP type, with the `fip-type` property, as above.
69 Since FIP exists to bring blobs together, Binman assumes that all FIP
70 entries are external binaries. If a binary may not exist, you can use the
71 `--allow-missing` flag to Binman, in which case the image is still created,
72 even though it will not actually work.
74 The size of the FIP depends on the size of the binaries. There is currently
75 no way to specify a fixed size. If the `atf-fip` node has a `size` entry,
76 this affects the space taken up by the `atf-fip` entry, but the FIP itself
77 does not expand to use that space.
79 Some other FIP features are available with Binman. The header and the
80 entries have 64-bit flag works. The flag flags do not seem to be defined
81 anywhere, but you can use `fip-hdr-flags` and fip-flags` to set the values
82 of the header and entries respectively.
84 FIP entries can be aligned to a particular power-of-two boundary. Use
87 Binman only understands the entry types that are included in its
88 implementation. It is possible to specify a 16-byte UUID instead, using the
89 fip-uuid property. In this case Binman doesn't know what its type is, so
90 just uses the UUID. See the `u-boot` node in this example::
94 fip-hdr-flags = /bits/ 64 <0x123>;
97 fip-flags = /bits/ 64 <0x456>;
98 filename = "bl31.bin";
102 filename = "bl2u.bin";
106 fip-uuid = [fc 65 13 92 4a 5b 11 ec
107 94 35 ff 2d 1c fc 79 9c];
114 Binman allows reading and updating FIP entries after the image is created,
115 provided that an FDPMAP is present too. Updates which change the size of a
116 FIP entry will cause it to be expanded or contracted as needed.
118 Properties for top-level atf-fip node
119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
121 fip-hdr-flags (64 bits)
122 Sets the flags for the FIP header.
124 Properties for subnodes
125 ~~~~~~~~~~~~~~~~~~~~~~~
128 FIP type to use for this entry. This is needed if the entry
129 name is not a valid type. Value types are defined in `fip_util.py`.
130 The FIP type defines the UUID that is used (they map 1:1).
133 If there is no FIP-type name defined, or it is not supported by Binman,
134 this property sets the UUID. It should be a 16-byte value, following the
135 hex digits of the UUID.
138 Set the flags for a FIP entry. Use in one of the subnodes of the
142 Set the alignment for a FIP entry, FIP entries can be aligned to a
143 particular power-of-two boundary. The default is 1.
145 Adding new FIP-entry types
146 ~~~~~~~~~~~~~~~~~~~~~~~~~~
148 When new FIP entries are defined by TF-A they appear in the
149 `TF-A source tree`_. You can use `fip_util.py` to update Binman to support
150 new types, then `send a patch`_ to the U-Boot mailing list. There are two
151 source files that the tool examples:
153 - `include/tools_share/firmware_image_package.h` has the UUIDs
154 - `tools/fiptool/tbbr_config.c` has the name and descripion for each UUID
158 $ tools/binman/fip_util.py -s /path/to/arm-trusted-firmware
159 Warning: UUID 'UUID_NON_TRUSTED_WORLD_KEY_CERT' is not mentioned in tbbr_config.c file
160 Existing code in 'tools/binman/fip_util.py' is up-to-date
162 If it shows there is an update, it writes a new version of `fip_util.py`
163 to `fip_util.py.out`. You can change the output file using the `-i` flag.
164 If you have a problem, use `-D` to enable traceback debugging.
169 As a side effect of use of UUIDs, FIP does not support multiple
170 entries of the same type, such as might be used to store fonts or graphics
171 icons, for example. For verified boot it could be used for each part of the
172 image (e.g. separate FIPs for A and B) but cannot describe the whole
173 firmware image. As with FMAP there is no hierarchy defined, although FMAP
174 works around this by having 'section' areas which encompass others. A
175 similar workaround would be possible with FIP but is not currently defined.
177 It is recommended to always add an fdtmap to every image, as well as any
178 FIPs so that binman and other tools can access the entire image correctly.
180 .. _FIP: https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#firmware-image-package-fip
181 .. _`TF-A source tree`: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
182 .. _`send a patch`: https://www.denx.de/wiki/U-Boot/Patches
188 Entry: blob: Arbitrary binary blob
189 ----------------------------------
191 Note: This should not be used by itself. It is normally used as a parent
192 class by other entry types.
194 Properties / Entry arguments:
195 - filename: Filename of file to read into entry
196 - compress: Compression algorithm to use:
198 lz4: Use lz4 compression (via 'lz4' command-line utility)
200 This entry reads data from a file and places it in the entry. The
201 default filename is often specified specified by the subclass. See for
202 example the 'u-boot' entry which provides the filename 'u-boot.bin'.
204 If compression is enabled, an extra 'uncomp-size' property is written to
205 the node (if enabled with -u) which provides the uncompressed size of the
212 Entry: blob-dtb: A blob that holds a device tree
213 ------------------------------------------------
215 This is a blob containing a device tree. The contents of the blob are
216 obtained from the list of available device-tree files, managed by the
219 Additional attributes:
220 prepend: Header used (e.g. 'length')
226 Entry: blob-ext: Externally built binary blob
227 ---------------------------------------------
229 Note: This should not be used by itself. It is normally used as a parent
230 class by other entry types.
232 If the file providing this blob is missing, binman can optionally ignore it
233 and produce a broken image with a warning.
235 See 'blob' for Properties / Entry arguments.
239 .. _etype_blob_ext_list:
241 Entry: blob-ext-list: List of externally built binary blobs
242 -----------------------------------------------------------
244 This is like blob-ext except that a number of blobs can be provided,
245 typically with some sort of relationship, e.g. all are DDC parameters.
247 If any of the external files needed by this llist is missing, binman can
248 optionally ignore it and produce a broken image with a warning.
251 filenames: List of filenames to read and include
255 .. _etype_blob_named_by_arg:
257 Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass
258 -----------------------------------------------------------------------------------------
260 Properties / Entry arguments:
261 - <xxx>-path: Filename containing the contents of this entry (optional,
264 where <xxx> is the blob_fname argument to the constructor.
266 This entry cannot be used directly. Instead, it is used as a parent class
267 for another entry, which defined blob_fname. This parameter is used to
268 set the entry-arg or property containing the filename. The entry-arg or
269 property is in turn used to set the actual filename.
271 See cros_ec_rw for an example of this.
275 .. _etype_blob_phase:
277 Entry: blob-phase: Section that holds a phase binary
278 ----------------------------------------------------
280 This is a base class that should not normally be used directly. It is used
281 when converting a 'u-boot' entry automatically into a 'u-boot-expanded'
282 entry; similarly for SPL.
288 Entry: cbfs: Coreboot Filesystem (CBFS)
289 ---------------------------------------
291 A CBFS provides a way to group files into a group. It has a simple directory
292 structure and allows the position of individual files to be set, since it is
293 designed to support execute-in-place in an x86 SPI-flash device. Where XIP
294 is not used, it supports compression and storing ELF files.
296 CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
298 The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::
310 This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb.
311 Note that the size is required since binman does not support calculating it.
312 The contents of each entry is just what binman would normally provide if it
313 were not a CBFS node. A blob type can be used to import arbitrary files as
314 with the second subnode below::
325 filename = "u-boot.dtb";
327 cbfs-compress = "lz4";
328 cbfs-offset = <0x100000>;
332 This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and
333 u-boot.dtb (named "dtb") and compressed with the lz4 algorithm.
336 Properties supported in the top-level CBFS node:
339 Defaults to "x86", but you can specify the architecture if needed.
342 Properties supported in the CBFS entry subnodes:
345 This is the name of the file created in CBFS. It defaults to the entry
346 name (which is the node name), but you can override it with this
350 This is the CBFS file type. The following are supported:
353 This is a 'raw' file, although compression is supported. It can be
354 used to store any file in CBFS.
357 This is an ELF file that has been loaded (i.e. mapped to memory), so
358 appears in the CBFS as a flat binary. The input file must be an ELF
359 image, for example this puts "u-boot" (the ELF image) into a 'stage'
370 You can use your own ELF file with something like::
376 filename = "cbfs-stage.elf";
381 As mentioned, the file is converted to a flat binary, so it is
382 equivalent to adding "u-boot.bin", for example, but with the load and
383 start addresses specified by the ELF. At present there is no option
384 to add a flat binary with a load/start address, similar to the
385 'add-flat-binary' option in cbfstool.
388 This is the offset of the file's data within the CBFS. It is used to
389 specify where the file should be placed in cases where a fixed position
390 is needed. Typical uses are for code which is not relocatable and must
391 execute in-place from a particular address. This works because SPI flash
392 is generally mapped into memory on x86 devices. The file header is
393 placed before this offset so that the data start lines up exactly with
394 the chosen offset. If this property is not provided, then the file is
395 placed in the next available spot.
397 The current implementation supports only a subset of CBFS features. It does
398 not support other file types (e.g. payload), adding multiple files (like the
399 'files' entry with a pattern supported by binman), putting files at a
400 particular offset in the CBFS and a few other things.
402 Of course binman can create images containing multiple CBFSs, simply by
403 defining these in the binman config::
430 filename = "image.jpg";
435 This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB,
440 .. _etype_collection:
442 Entry: collection: An entry which contains a collection of other entries
443 ------------------------------------------------------------------------
445 Properties / Entry arguments:
446 - content: List of phandles to entries to include
448 This allows reusing the contents of other entries. The contents of the
449 listed entries are combined to form this entry. This serves as a useful
450 base class for entry types which need to process data from elsewhere in
451 the image, not necessarily child entries.
453 The entries can generally be anywhere in the same image, even if they are in
454 a different section from this entry.
458 .. _etype_cros_ec_rw:
460 Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image
461 --------------------------------------------------------------------------------
463 Properties / Entry arguments:
464 - cros-ec-rw-path: Filename containing the EC image
466 This entry holds a Chromium OS EC (embedded controller) image, for use in
467 updating the EC on startup via software sync.
473 Entry: fdtmap: An entry which contains an FDT map
474 -------------------------------------------------
476 Properties / Entry arguments:
479 An FDT map is just a header followed by an FDT containing a list of all the
480 entries in the image. The root node corresponds to the image node in the
481 original FDT, and an image-name property indicates the image name in that
484 The header is the string _FDTMAP_ followed by 8 unused bytes.
486 When used, this entry will be populated with an FDT map which reflects the
487 entries in the current image. Hierarchy is preserved, and all offsets and
490 Note that the -u option must be provided to ensure that binman updates the
491 FDT with the position of each entry.
493 Example output for a simple image with U-Boot and an FDT map::
496 image-name = "binman";
498 image-pos = <0x00000000>;
499 offset = <0x00000000>;
502 image-pos = <0x00000000>;
503 offset = <0x00000000>;
507 image-pos = <0x00000004>;
508 offset = <0x00000004>;
512 If allow-repack is used then 'orig-offset' and 'orig-size' properties are
513 added as necessary. See the binman README.
515 When extracting files, an alternative 'fdt' format is available for fdtmaps.
516 Use `binman extract -F fdt ...` to use this. It will export a devicetree,
517 without the fdtmap header, so it can be viewed with `fdtdump`.
523 Entry: files: A set of files arranged in a section
524 --------------------------------------------------
526 Properties / Entry arguments:
527 - pattern: Filename pattern to match the files to include
528 - files-compress: Compression algorithm to use:
530 lz4: Use lz4 compression (via 'lz4' command-line utility)
531 - files-align: Align each file to the given alignment
533 This entry reads a number of files and places each in a separate sub-entry
534 within this entry. To access these you need to enable device-tree updates
535 at run-time so you can obtain the file positions.
541 Entry: fill: An entry which is filled to a particular byte value
542 ----------------------------------------------------------------
544 Properties / Entry arguments:
545 - fill-byte: Byte to use to fill the entry
547 Note that the size property must be set since otherwise this entry does not
548 know how large it should be.
550 You can often achieve the same effect using the pad-byte property of the
551 overall image, in that the space between entries will then be padded with
552 that byte. But this entry is sometimes useful for explicitly setting the
553 byte value of a region.
559 Entry: fit: Flat Image Tree (FIT)
560 ---------------------------------
562 This calls mkimage to create a FIT (U-Boot Flat Image Tree) based on the
565 Nodes for the FIT should be written out in the binman configuration just as
566 they would be in a file passed to mkimage.
568 For example, this creates an image containing a FIT with U-Boot SPL::
572 description = "Test FIT";
573 fit,fdt-list = "of-list";
581 compression = "none";
592 More complex setups can be created, with generated nodes, as described
595 Properties (in the 'fit' node itself)
596 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
598 Special properties have a `fit,` prefix, indicating that they should be
599 processed but not included in the final FIT.
601 The top-level 'fit' node supports the following special properties:
604 Indicates that the contents of the FIT are external and provides the
605 external offset. This is passed to mkimage via the -E and -p flags.
608 Indicates what alignment to use for the FIT and its external data,
609 and provides the alignment to use. This is passed to mkimage via
613 Indicates the entry argument which provides the list of device tree
614 files for the gen-fdt-nodes operation (as below). This is often
615 `of-list` meaning that `-a of-list="dtb1 dtb2..."` should be passed
621 Node names and property values support a basic string-substitution feature.
622 Available substitutions for '@' nodes (and property values) are:
625 Sequence number of the generated fdt (1, 2, ...)
627 Name of the dtb as provided (i.e. without adding '.dtb')
629 The `default` property, if present, will be automatically set to the name
630 if of configuration whose devicetree matches the `default-dt` entry
631 argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.
633 Available substitutions for property values in these nodes are:
636 Sequence number of the default fdt, as provided by the 'default-dt'
642 You can add an operation to an '@' node to indicate which operation is
646 fit,operation = "gen-fdt-nodes";
650 Available operations are:
653 Generate FDT nodes as above. This is the default if there is no
654 `fit,operation` property.
657 Split an ELF file into a separate node for each segment.
659 Generating nodes from an FDT list (gen-fdt-nodes)
660 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
662 U-Boot supports creating fdt and config nodes automatically. To do this,
663 pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells
664 binman that you want to generates nodes for two files: `file1.dtb` and
665 `file2.dtb`. The `fit,fdt-list` property (see above) indicates that
666 `of-list` should be used. If the property is missing you will get an error.
668 Then add a 'generator node', a node with a name starting with '@'::
672 description = "fdt-NAME";
674 compression = "none";
678 This tells binman to create nodes `fdt-1` and `fdt-2` for each of your two
679 files. All the properties you specify will be included in the node. This
680 node acts like a template to generate the nodes. The generator node itself
681 does not appear in the output - it is replaced with what binman generates.
682 A 'data' property is created with the contents of the FDT file.
684 You can create config nodes in a similar way::
687 default = "@config-DEFAULT-SEQ";
689 description = "NAME";
696 This tells binman to create nodes `config-1` and `config-2`, i.e. a config
697 for each of your two files.
699 Note that if no devicetree files are provided (with '-a of-list' as above)
700 then no nodes will be generated.
702 Generating nodes from an ELF file (split-elf)
703 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
705 This uses the node as a template to generate multiple nodes. The following
706 special properties are available:
709 Split an ELF file into a separate node for each segment. This uses the
710 node as a template to generate multiple nodes. The following special
711 properties are available:
714 Generates a `load = <...>` property with the load address of the
718 Generates a `entry = <...>` property with the entry address of the
719 ELF. This is only produced for the first entry
722 Generates a `data = <...>` property with the contents of the segment
725 Generates a `firmware = <...>` property. Provides a list of possible
726 nodes to be used as the `firmware` property value. The first valid
727 node is picked as the firmware. Any remaining valid nodes is
728 prepended to the `loadable` property generated by `fit,loadables`
731 Generates a `loadable = <...>` property with a list of the generated
732 nodes (including all nodes if this operation is used multiple times)
735 Here is an example showing ATF, TEE and a device tree all combined::
738 description = "test-desc";
739 #address-cells = <1>;
740 fit,fdt-list = "of-list";
744 description = "U-Boot (64-bit)";
748 compression = "none";
749 load = <CONFIG_TEXT_BASE>;
754 description = "fdt-NAME.dtb";
756 compression = "none";
759 fit,operation = "split-elf";
760 description = "ARM Trusted Firmware";
763 os = "arm-trusted-firmware";
764 compression = "none";
777 fit,operation = "split-elf";
782 compression = "none";
796 default = "@config-DEFAULT-SEQ";
798 description = "conf-NAME.dtb";
800 fit,firmware = "atf-1", "u-boot";
806 If ATF-BL31 is available, this generates a node for each segment in the
807 ELF file, for example::
811 data = <...contents of first segment...>;
812 data-offset = <0x00000000>;
813 entry = <0x00040000>;
815 compression = "none";
816 os = "arm-trusted-firmware";
819 description = "ARM Trusted Firmware";
822 value = <...hash of first segment...>;
826 data = <...contents of second segment...>;
828 compression = "none";
829 os = "arm-trusted-firmware";
832 description = "ARM Trusted Firmware";
835 value = <...hash of second segment...>;
840 The same applies for OP-TEE if that is available.
842 If each binary is not available, the relevant template node (@atf-SEQ or
843 @tee-SEQ) is removed from the output.
845 This also generates a `config-xxx` node for each device tree in `of-list`.
846 Note that the U-Boot build system uses `-a of-list=$(CONFIG_OF_LIST)`
847 so you can use `CONFIG_OF_LIST` to define that list. In this example it is
848 set up for `firefly-rk3399` with a single device tree and the default set
849 with `-a default-dt=$(CONFIG_DEFAULT_DEVICE_TREE)`, so the resulting output
853 default = "config-1";
855 loadables = "u-boot", "atf-2", "atf-3", "tee-1", "tee-2";
856 description = "rk3399-firefly.dtb";
862 U-Boot SPL can then load the firmware (ATF) and all the loadables (U-Boot
863 proper, ATF and TEE), then proceed with the boot.
869 Entry: fmap: An entry which contains an Fmap section
870 ----------------------------------------------------
872 Properties / Entry arguments:
875 FMAP is a simple format used by flashrom, an open-source utility for
876 reading and writing the SPI flash, typically on x86 CPUs. The format
877 provides flashrom with a list of areas, so it knows what it in the flash.
878 It can then read or write just a single area, instead of the whole flash.
880 The format is defined by the flashrom project, in the file lib/fmap.h -
881 see www.flashrom.org/Flashrom for more information.
883 When used, this entry will be populated with an FMAP which reflects the
884 entries in the current image. Note that any hierarchy is squashed, since
885 FMAP does not support this. Sections are represented as an area appearing
886 before its contents, so that it is possible to reconstruct the hierarchy
887 from the FMAP by using the offset information. This convention does not
888 seem to be documented, but is used in Chromium OS.
890 To mark an area as preserved, use the normal 'preserved' flag in the entry.
891 This will result in the corresponding FMAP area having the
892 FMAP_AREA_PRESERVE flag. This flag does not automatically propagate down to
895 CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
901 Entry: gbb: An entry which contains a Chromium OS Google Binary Block
902 ---------------------------------------------------------------------
904 Properties / Entry arguments:
905 - hardware-id: Hardware ID to use for this build (a string)
906 - keydir: Directory containing the public keys to use
907 - bmpblk: Filename containing images used by recovery
909 Chromium OS uses a GBB to store various pieces of information, in particular
910 the root and recovery keys that are used to verify the boot process. Some
911 more details are here:
913 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
915 but note that the page dates from 2013 so is quite out of date. See
916 README.chromium for how to obtain the required keys and tools.
920 .. _etype_image_header:
922 Entry: image-header: An entry which contains a pointer to the FDT map
923 ---------------------------------------------------------------------
925 Properties / Entry arguments:
926 location: Location of header ("start" or "end" of image). This is
927 optional. If omitted then the entry must have an offset property.
929 This adds an 8-byte entry to the start or end of the image, pointing to the
930 location of the FDT map. The format is a magic number followed by an offset
931 from the start or end of the image, in twos-compliment format.
933 This entry must be in the top-level part of the image.
935 NOTE: If the location is at the start/end, you will probably need to specify
936 sort-by-offset for the image, unless you actually put the image header
937 first/last in the entry list.
943 Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
944 -----------------------------------------------------
946 Properties / Entry arguments:
947 - filename: Filename of file to read into entry
949 This file contains microcode for some devices in a special format. An
950 example filename is 'Microcode/C0_22211.BIN'.
952 See README.x86 for information about x86 binary blobs.
956 .. _etype_intel_descriptor:
958 Entry: intel-descriptor: Intel flash descriptor block (4KB)
959 -----------------------------------------------------------
961 Properties / Entry arguments:
962 filename: Filename of file containing the descriptor. This is typically
963 a 4KB binary file, sometimes called 'descriptor.bin'
965 This entry is placed at the start of flash and provides information about
966 the SPI flash regions. In particular it provides the base address and
967 size of the ME (Management Engine) region, allowing us to place the ME
968 binary in the right place.
970 With this entry in your image, the position of the 'intel-me' entry will be
971 fixed in the image, which avoids you needed to specify an offset for that
972 region. This is useful, because it is not possible to change the position
973 of the ME region without updating the descriptor.
975 See README.x86 for information about x86 binary blobs.
981 Entry: intel-fit: Intel Firmware Image Table (FIT)
982 --------------------------------------------------
984 This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
985 contains information about the firmware and microcode available in the
988 At present binman only supports a basic FIT with no microcode.
992 .. _etype_intel_fit_ptr:
994 Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
995 --------------------------------------------------------------
997 This entry contains a pointer to the FIT. It is required to be at address
998 0xffffffc0 in the image.
1002 .. _etype_intel_fsp:
1004 Entry: intel-fsp: Intel Firmware Support Package (FSP) file
1005 -----------------------------------------------------------
1007 Properties / Entry arguments:
1008 - filename: Filename of file to read into entry
1010 This file contains binary blobs which are used on some devices to make the
1011 platform work. U-Boot executes this code since it is not possible to set up
1012 the hardware using U-Boot open-source code. Documentation is typically not
1013 available in sufficient detail to allow this.
1015 An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
1017 See README.x86 for information about x86 binary blobs.
1021 .. _etype_intel_fsp_m:
1023 Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
1024 --------------------------------------------------------------------
1026 Properties / Entry arguments:
1027 - filename: Filename of file to read into entry
1029 This file contains a binary blob which is used on some devices to set up
1030 SDRAM. U-Boot executes this code in SPL so that it can make full use of
1031 memory. Documentation is typically not available in sufficient detail to
1032 allow U-Boot do this this itself..
1034 An example filename is 'fsp_m.bin'
1036 See README.x86 for information about x86 binary blobs.
1040 .. _etype_intel_fsp_s:
1042 Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
1043 ---------------------------------------------------------------------
1045 Properties / Entry arguments:
1046 - filename: Filename of file to read into entry
1048 This file contains a binary blob which is used on some devices to set up
1049 the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
1050 running, so that it can make full use of memory. Documentation is typically
1051 not available in sufficient detail to allow U-Boot do this this itself.
1053 An example filename is 'fsp_s.bin'
1055 See README.x86 for information about x86 binary blobs.
1059 .. _etype_intel_fsp_t:
1061 Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
1062 ----------------------------------------------------------------------
1064 Properties / Entry arguments:
1065 - filename: Filename of file to read into entry
1067 This file contains a binary blob which is used on some devices to set up
1068 temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
1069 that it has access to memory for its stack and initial storage.
1071 An example filename is 'fsp_t.bin'
1073 See README.x86 for information about x86 binary blobs.
1077 .. _etype_intel_ifwi:
1079 Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
1080 --------------------------------------------------------------
1082 Properties / Entry arguments:
1083 - filename: Filename of file to read into entry. This is either the
1084 IFWI file itself, or a file that can be converted into one using a
1086 - convert-fit: If present this indicates that the ifwitool should be
1087 used to convert the provided file into a IFWI.
1089 This file contains code and data used by the SoC that is required to make
1090 it work. It includes U-Boot TPL, microcode, things related to the CSE
1091 (Converged Security Engine, the microcontroller that loads all the firmware)
1092 and other items beyond the wit of man.
1094 A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
1095 file that will be converted to an IFWI.
1097 The position of this entry is generally set by the intel-descriptor entry.
1099 The contents of the IFWI are specified by the subnodes of the IFWI node.
1100 Each subnode describes an entry which is placed into the IFWFI with a given
1101 sub-partition (and optional entry name).
1103 Properties for subnodes:
1104 - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
1105 - ifwi-entry: entry name t use, e.g. "IBBL"
1106 - ifwi-replace: if present, indicates that the item should be replaced
1107 in the IFWI. Otherwise it is added.
1109 See README.x86 for information about x86 binary blobs.
1115 Entry: intel-me: Intel Management Engine (ME) file
1116 --------------------------------------------------
1118 Properties / Entry arguments:
1119 - filename: Filename of file to read into entry
1121 This file contains code used by the SoC that is required to make it work.
1122 The Management Engine is like a background task that runs things that are
1123 not clearly documented, but may include keyboard, display and network
1124 access. For platform that use ME it is not possible to disable it. U-Boot
1125 does not directly execute code in the ME binary.
1127 A typical filename is 'me.bin'.
1129 The position of this entry is generally set by the intel-descriptor entry.
1131 See README.x86 for information about x86 binary blobs.
1135 .. _etype_intel_mrc:
1137 Entry: intel-mrc: Intel Memory Reference Code (MRC) file
1138 --------------------------------------------------------
1140 Properties / Entry arguments:
1141 - filename: Filename of file to read into entry
1143 This file contains code for setting up the SDRAM on some Intel systems. This
1144 is executed by U-Boot when needed early during startup. A typical filename
1147 See README.x86 for information about x86 binary blobs.
1151 .. _etype_intel_refcode:
1153 Entry: intel-refcode: Intel Reference Code file
1154 -----------------------------------------------
1156 Properties / Entry arguments:
1157 - filename: Filename of file to read into entry
1159 This file contains code for setting up the platform on some Intel systems.
1160 This is executed by U-Boot when needed early during startup. A typical
1161 filename is 'refcode.bin'.
1163 See README.x86 for information about x86 binary blobs.
1167 .. _etype_intel_vbt:
1169 Entry: intel-vbt: Intel Video BIOS Table (VBT) file
1170 ---------------------------------------------------
1172 Properties / Entry arguments:
1173 - filename: Filename of file to read into entry
1175 This file contains code that sets up the integrated graphics subsystem on
1176 some Intel SoCs. U-Boot executes this when the display is started up.
1178 See README.x86 for information about Intel binary blobs.
1182 .. _etype_intel_vga:
1184 Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
1185 ---------------------------------------------------------
1187 Properties / Entry arguments:
1188 - filename: Filename of file to read into entry
1190 This file contains code that sets up the integrated graphics subsystem on
1191 some Intel SoCs. U-Boot executes this when the display is started up.
1193 This is similar to the VBT file but in a different format.
1195 See README.x86 for information about Intel binary blobs.
1201 Entry: mkimage: Binary produced by mkimage
1202 ------------------------------------------
1204 Properties / Entry arguments:
1205 - args: Arguments to pass
1206 - data-to-imagename: Indicates that the -d data should be passed in as
1207 the image name also (-n)
1208 - multiple-data-files: boolean to tell binman to pass all files as
1209 datafiles to mkimage instead of creating a temporary file the result
1210 of datafiles concatenation
1211 - filename: filename of output binary generated by mkimage
1213 The data passed to mkimage via the -d flag is collected from subnodes of the
1214 mkimage node, e.g.::
1217 filename = "imximage.bin";
1218 args = "-n test -T imximage";
1224 This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
1225 file, with mkimage being called like this::
1227 mkimage -d <data_file> -n test -T imximage <output_file>
1229 The output from mkimage then becomes part of the image produced by
1230 binman but also is written into `imximage.bin` file. If you need to put
1231 multiple things in the data file, you can use a section, or just multiple
1232 subnodes like this::
1235 args = "-n test -T imximage";
1244 Note that binman places the contents (here SPL and TPL) into a single file
1245 and passes that to mkimage using the -d option.
1247 To pass all datafiles untouched to mkimage::
1250 args = "-n rk3399 -T rkspi";
1251 multiple-data-files;
1260 This calls mkimage to create a Rockchip RK3399-specific first stage
1261 bootloader, made of TPL+SPL. Since this first stage bootloader requires to
1262 align the TPL and SPL but also some weird hacks that is handled by mkimage
1263 directly, binman is told to not perform the concatenation of datafiles prior
1264 to passing the data to mkimage.
1266 To use CONFIG options in the arguments, use a string list instead, as in
1267 this example which also produces four arguments::
1270 args = "-n", CONFIG_SYS_SOC, "-T imximage";
1276 If you need to pass the input data in with the -n argument as well, then use
1277 the 'data-to-imagename' property::
1280 args = "-T imximage";
1287 That will pass the data to mkimage both as the data file (with -d) and as
1288 the image name (with -n). In both cases, a filename is passed as the
1289 argument, with the actual data being in that file.
1291 If need to pass different data in with -n, then use an `imagename` subnode::
1294 args = "-T imximage";
1298 filename = "spl/u-boot-spl.cfgout"
1306 This will pass in u-boot-spl as the input data and the .cfgout file as the
1313 Entry: null: An entry which has no contents of its own
1314 ------------------------------------------------------
1316 Note that the size property must be set since otherwise this entry does not
1317 know how large it should be.
1319 The contents are set by the containing section, e.g. the section's pad
1326 Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
1327 ----------------------------------------------
1329 Properties / Entry arguments:
1330 - opensbi-path: Filename of file to read into entry. This is typically
1331 called fw_dynamic.bin
1333 This entry holds the run-time firmware, typically started by U-Boot SPL.
1334 See the U-Boot README for your architecture or board for how to use it. See
1335 https://github.com/riscv/opensbi for more information about OpenSBI.
1339 .. _etype_powerpc_mpc85xx_bootpg_resetvec:
1341 Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
1342 -----------------------------------------------------------------------------------------
1344 Properties / Entry arguments:
1345 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
1347 This entry is valid for PowerPC mpc85xx cpus. This entry holds
1348 'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
1349 placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
1355 Entry: pre-load: Pre load image header
1356 --------------------------------------
1358 Properties / Entry arguments:
1359 - pre-load-key-path: Path of the directory that store key (provided by
1360 the environment variable PRE_LOAD_KEY_PATH)
1361 - content: List of phandles to entries to sign
1362 - algo-name: Hash and signature algo to use for the signature
1363 - padding-name: Name of the padding (pkcs-1.5 or pss)
1364 - key-name: Filename of the private key to sign
1365 - header-size: Total size of the header
1366 - version: Version of the header
1368 This entry creates a pre-load header that contains a global
1371 For example, this creates an image with a pre-load header and a binary::
1375 filename = "sandbox.bin";
1379 algo-name = "sha256,rsa2048";
1380 padding-name = "pss";
1381 key-name = "private.pem";
1382 header-size = <4096>;
1387 filename = "sandbox.itb";
1394 .. _etype_rockchip_tpl:
1396 Entry: rockchip-tpl: Rockchip TPL binary
1397 ----------------------------------------
1399 Properties / Entry arguments:
1400 - rockchip-tpl-path: Filename of file to read into the entry,
1401 typically <soc>_ddr_<version>.bin
1403 This entry holds an external TPL binary used by some Rockchip SoCs
1404 instead of normal U-Boot TPL, typically to initialize DRAM.
1410 Entry: scp: System Control Processor (SCP) firmware blob
1411 --------------------------------------------------------
1413 Properties / Entry arguments:
1414 - scp-path: Filename of file to read into the entry, typically scp.bin
1416 This entry holds firmware for an external platform-specific coprocessor.
1422 Entry: section: Entry that contains other entries
1423 -------------------------------------------------
1425 A section is an entry which can contain other entries, thus allowing
1426 hierarchical images to be created. See 'Sections and hierarchical images'
1427 in the binman README for more information.
1429 The base implementation simply joins the various entries together, using
1430 various rules about alignment, etc.
1435 This class can be subclassed to support other file formats which hold
1436 multiple entries, such as CBFS. To do this, override the following
1437 functions. The documentation here describes what your function should do.
1438 For example code, see etypes which subclass `Entry_section`, or `cbfs.py`
1439 for a more involved example::
1441 $ grep -l \(Entry_section tools/binman/etype/*.py
1444 Call `super().ReadNode()`, then read any special properties for the
1445 section. Then call `self.ReadEntries()` to read the entries.
1447 Binman calls this at the start when reading the image description.
1450 Read in the subnodes of the section. This may involve creating entries
1451 of a particular etype automatically, as well as reading any special
1452 properties in the entries. For each entry, entry.ReadNode() should be
1453 called, to read the basic entry properties. The properties should be
1454 added to `self._entries[]`, in the correct order, with a suitable name.
1456 Binman calls this at the start when reading the image description.
1458 BuildSectionData(required)
1459 Create the custom file format that you want and return it as bytes.
1460 This likely sets up a file header, then loops through the entries,
1461 adding them to the file. For each entry, call `entry.GetData()` to
1462 obtain the data. If that returns None, and `required` is False, then
1463 this method must give up and return None. But if `required` is True then
1464 it should assume that all data is valid.
1466 Binman calls this when packing the image, to find out the size of
1467 everything. It is called again at the end when building the final image.
1469 SetImagePos(image_pos):
1470 Call `super().SetImagePos(image_pos)`, then set the `image_pos` values
1471 for each of the entries. This should use the custom file format to find
1472 the `start offset` (and `image_pos`) of each entry. If the file format
1473 uses compression in such a way that there is no offset available (other
1474 than reading the whole file and decompressing it), then the offsets for
1475 affected entries can remain unset (`None`). The size should also be set
1478 Binman calls this after the image has been packed, to update the
1479 location that all the entries ended up at.
1481 ReadChildData(child, decomp, alt_format):
1482 The default version of this may be good enough, if you are able to
1483 implement SetImagePos() correctly. But that is a bit of a bypass, so
1484 you can override this method to read from your custom file format. It
1485 should read the entire entry containing the custom file using
1486 `super().ReadData(True)`, then parse the file to get the data for the
1487 given child, then return that data.
1489 If your file format supports compression, the `decomp` argument tells
1490 you whether to return the compressed data (`decomp` is False) or to
1491 uncompress it first, then return the uncompressed data (`decomp` is
1492 True). This is used by the `binman extract -U` option.
1494 If your entry supports alternative formats, the alt_format provides the
1495 alternative format that the user has selected. Your function should
1496 return data in that format. This is used by the 'binman extract -l'
1499 Binman calls this when reading in an image, in order to populate all the
1500 entries with the data from that image (`binman ls`).
1502 WriteChildData(child):
1503 Binman calls this after `child.data` is updated, to inform the custom
1504 file format about this, in case it needs to do updates.
1506 The default version of this does nothing and probably needs to be
1507 overridden for the 'binman replace' command to work. Your version should
1508 use `child.data` to update the data for that child in the custom file
1511 Binman calls this when updating an image that has been read in and in
1512 particular to update the data for a particular entry (`binman replace`)
1514 Properties / Entry arguments
1515 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1517 See :ref:`develop/package/binman:Image description format` for more
1521 Default alignment for this section, if no alignment is given in the
1525 Pad byte to use when padding
1528 True if entries should be sorted by offset, False if they must be
1529 in-order in the device tree description
1532 Used to build an x86 ROM which ends at 4GB (2^32)
1535 Adds a prefix to the name of every entry in the section when writing out
1539 Number of bytes before the first entry starts. These effectively adjust
1540 the starting offset of entries. For example, if this is 16, then the
1541 first entry would start at 16. An entry with offset = 20 would in fact
1542 be written at offset 4 in the image file, since the first 16 bytes are
1543 skipped when writing.
1546 filename to write the unpadded section contents to within the output
1547 directory (None to skip this).
1549 Since a section is also an entry, it inherits all the properies of entries
1552 Note that the `allow_missing` member controls whether this section permits
1553 external blobs to be missing their contents. The option will produce an
1554 image but of course it will not work. It is useful to make sure that
1555 Continuous Integration systems can build without the binaries being
1556 available. This is set by the `SetAllowMissing()` method, if
1557 `--allow-missing` is passed to binman.
1563 Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
1564 ---------------------------------------------------------------
1566 Properties / Entry arguments:
1567 - tee-os-path: Filename of file to read into entry. This is typically
1568 called tee.bin or tee.elf
1570 This entry holds the run-time firmware, typically started by U-Boot SPL.
1571 See the U-Boot README for your architecture or board for how to use it. See
1572 https://github.com/OP-TEE/optee_os for more information about OP-TEE.
1574 Note that if the file is in ELF format, it must go in a FIT. In that case,
1575 this entry will mark itself as absent, providing the data only through the
1576 read_elf_segments() method.
1578 Marking this entry as absent means that it if is used in the wrong context
1579 it can be automatically dropped. Thus it is possible to add an OP-TEE entry
1587 and pass either an ELF or plain binary in with -a tee-os-path <filename>
1588 and have binman do the right thing:
1590 - include the entry if tee.bin is provided and it does NOT have the v1
1594 When used within a FIT, we can do::
1603 which will split the ELF into separate nodes for each segment, if an ELF
1604 file is provided (see :ref:`etype_fit`), or produce a single node if the
1605 OP-TEE binary v1 format is provided (see optee_doc_) .
1607 .. _optee_doc: https://optee.readthedocs.io/en/latest/architecture/core.html#partitioning-of-the-binary
1613 Entry: text: An entry which contains text
1614 -----------------------------------------
1616 The text can be provided either in the node itself or by a command-line
1617 argument. There is a level of indirection to allow multiple text strings
1618 and sharing of text.
1620 Properties / Entry arguments:
1621 text-label: The value of this string indicates the property / entry-arg
1622 that contains the string to place in the entry
1623 <xxx> (actual name is the value of text-label): contains the string to
1625 <text>: The text to place in the entry (overrides the above mechanism).
1626 This is useful when the text is constant.
1632 text-label = "message";
1637 binman -amessage="this is my message"
1639 and binman will insert that string into the entry.
1641 It is also possible to put the string directly in the node::
1645 text-label = "message";
1646 message = "a message directly in the node"
1653 text = "some text directly in the node"
1656 The text is not itself nul-terminated. This can be achieved, if required,
1657 by setting the size of the entry to something larger than the text.
1663 Entry: u-boot: U-Boot flat binary
1664 ---------------------------------
1666 Properties / Entry arguments:
1667 - filename: Filename of u-boot.bin (default 'u-boot.bin')
1669 This is the U-Boot binary, containing relocation information to allow it
1670 to relocate itself at runtime. The binary typically includes a device tree
1671 blob at the end of it.
1673 U-Boot can access binman symbols at runtime. See :ref:`binman_fdt`.
1675 Note that this entry is automatically replaced with u-boot-expanded unless
1676 --no-expanded is used or the node has a 'no-expanded' property.
1680 .. _etype_u_boot_dtb:
1682 Entry: u-boot-dtb: U-Boot device tree
1683 -------------------------------------
1685 Properties / Entry arguments:
1686 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1688 This is the U-Boot device tree, containing configuration information for
1689 U-Boot. U-Boot needs this to know what devices are present and which drivers
1692 Note: This is mostly an internal entry type, used by others. This allows
1693 binman to know which entries contain a device tree.
1697 .. _etype_u_boot_dtb_with_ucode:
1699 Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
1700 -----------------------------------------------------------------------------------
1702 Properties / Entry arguments:
1703 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1705 See Entry_u_boot_ucode for full details of the three entries involved in
1706 this process. This entry provides the U-Boot device-tree file, which
1707 contains the microcode. If the microcode is not being collated into one
1708 place then the offset and size of the microcode is recorded by this entry,
1709 for use by u-boot-with-ucode_ptr. If it is being collated, then this
1710 entry deletes the microcode from the device tree (to save space) and makes
1711 it available to u-boot-ucode.
1715 .. _etype_u_boot_elf:
1717 Entry: u-boot-elf: U-Boot ELF image
1718 -----------------------------------
1720 Properties / Entry arguments:
1721 - filename: Filename of u-boot (default 'u-boot')
1723 This is the U-Boot ELF image. It does not include a device tree but can be
1724 relocated to any address for execution.
1728 .. _etype_u_boot_env:
1730 Entry: u-boot-env: An entry which contains a U-Boot environment
1731 ---------------------------------------------------------------
1733 Properties / Entry arguments:
1734 - filename: File containing the environment text, with each line in the
1739 .. _etype_u_boot_expanded:
1741 Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
1742 ------------------------------------------------------------------------------
1744 This is a section containing the U-Boot binary and a devicetree. Using this
1745 entry type automatically creates this section, with the following entries
1751 Having the devicetree separate allows binman to update it in the final
1752 image, so that the entries positions are provided to the running U-Boot.
1756 .. _etype_u_boot_img:
1758 Entry: u-boot-img: U-Boot legacy image
1759 --------------------------------------
1761 Properties / Entry arguments:
1762 - filename: Filename of u-boot.img (default 'u-boot.img')
1764 This is the U-Boot binary as a packaged image, in legacy format. It has a
1765 header which allows it to be loaded at the correct address for execution.
1767 You should use FIT (Flat Image Tree) instead of the legacy image for new
1772 .. _etype_u_boot_nodtb:
1774 Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
1775 --------------------------------------------------------------------
1777 Properties / Entry arguments:
1778 - filename: Filename to include (default 'u-boot-nodtb.bin')
1780 This is the U-Boot binary, containing relocation information to allow it
1781 to relocate itself at runtime. It does not include a device tree blob at
1782 the end of it so normally cannot work without it. You can add a u-boot-dtb
1783 entry after this one, or use a u-boot entry instead, normally expands to a
1784 section containing u-boot and u-boot-dtb
1788 .. _etype_u_boot_spl:
1790 Entry: u-boot-spl: U-Boot SPL binary
1791 ------------------------------------
1793 Properties / Entry arguments:
1794 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
1796 This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
1797 binary which loads before U-Boot proper, typically into on-chip SRAM. It is
1798 responsible for locating, loading and jumping to U-Boot. Note that SPL is
1799 not relocatable so must be loaded to the correct address in SRAM, or written
1800 to run from the correct address if direct flash execution is possible (e.g.
1803 SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
1805 in the binman README for more information.
1807 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1808 binman uses that to look up symbols to write into the SPL binary.
1810 Note that this entry is automatically replaced with u-boot-spl-expanded
1811 unless --no-expanded is used or the node has a 'no-expanded' property.
1815 .. _etype_u_boot_spl_bss_pad:
1817 Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
1818 ---------------------------------------------------------------------
1820 Properties / Entry arguments:
1823 This holds the padding added after the SPL binary to cover the BSS (Block
1824 Started by Symbol) region. This region holds the various variables used by
1825 SPL. It is set to 0 by SPL when it starts up. If you want to append data to
1826 the SPL image (such as a device tree file), you must pad out the BSS region
1827 to avoid the data overlapping with U-Boot variables. This entry is useful in
1828 that case. It automatically pads out the entry size to cover both the code,
1831 The contents of this entry will a certain number of zero bytes, determined
1834 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1835 binman uses that to look up the BSS address.
1839 .. _etype_u_boot_spl_dtb:
1841 Entry: u-boot-spl-dtb: U-Boot SPL device tree
1842 ---------------------------------------------
1844 Properties / Entry arguments:
1845 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
1847 This is the SPL device tree, containing configuration information for
1848 SPL. SPL needs this to know what devices are present and which drivers
1853 .. _etype_u_boot_spl_elf:
1855 Entry: u-boot-spl-elf: U-Boot SPL ELF image
1856 -------------------------------------------
1858 Properties / Entry arguments:
1859 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
1861 This is the U-Boot SPL ELF image. It does not include a device tree but can
1862 be relocated to any address for execution.
1866 .. _etype_u_boot_spl_expanded:
1868 Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
1869 --------------------------------------------------------------------------------------
1871 Properties / Entry arguments:
1872 - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
1875 This is a section containing the U-Boot binary, BSS padding if needed and a
1876 devicetree. Using this entry type automatically creates this section, with
1877 the following entries in it:
1883 Having the devicetree separate allows binman to update it in the final
1884 image, so that the entries positions are provided to the running U-Boot.
1886 This entry is selected based on the value of the 'spl-dtb' entryarg. If
1887 this is non-empty (and not 'n' or '0') then this expanded entry is selected.
1891 .. _etype_u_boot_spl_nodtb:
1893 Entry: u-boot-spl-nodtb: SPL binary without device tree appended
1894 ----------------------------------------------------------------
1896 Properties / Entry arguments:
1897 - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin')
1899 This is the U-Boot SPL binary, It does not include a device tree blob at
1900 the end of it so may not be able to work without it, assuming SPL needs
1901 a device tree to operate on your platform. You can add a u-boot-spl-dtb
1902 entry after this one, or use a u-boot-spl entry instead' which normally
1903 expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
1906 SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
1908 in the binman README for more information.
1910 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1911 binman uses that to look up symbols to write into the SPL binary.
1915 .. _etype_u_boot_spl_with_ucode_ptr:
1917 Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
1918 ----------------------------------------------------------------------------
1920 This is used when SPL must set up the microcode for U-Boot.
1922 See Entry_u_boot_ucode for full details of the entries involved in this
1927 .. _etype_u_boot_tpl:
1929 Entry: u-boot-tpl: U-Boot TPL binary
1930 ------------------------------------
1932 Properties / Entry arguments:
1933 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
1935 This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
1936 binary which loads before SPL, typically into on-chip SRAM. It is
1937 responsible for locating, loading and jumping to SPL, the next-stage
1938 loader. Note that SPL is not relocatable so must be loaded to the correct
1939 address in SRAM, or written to run from the correct address if direct
1940 flash execution is possible (e.g. on x86 devices).
1942 SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
1944 in the binman README for more information.
1946 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1947 binman uses that to look up symbols to write into the TPL binary.
1949 Note that this entry is automatically replaced with u-boot-tpl-expanded
1950 unless --no-expanded is used or the node has a 'no-expanded' property.
1954 .. _etype_u_boot_tpl_bss_pad:
1956 Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
1957 ---------------------------------------------------------------------
1959 Properties / Entry arguments:
1962 This holds the padding added after the TPL binary to cover the BSS (Block
1963 Started by Symbol) region. This region holds the various variables used by
1964 TPL. It is set to 0 by TPL when it starts up. If you want to append data to
1965 the TPL image (such as a device tree file), you must pad out the BSS region
1966 to avoid the data overlapping with U-Boot variables. This entry is useful in
1967 that case. It automatically pads out the entry size to cover both the code,
1970 The contents of this entry will a certain number of zero bytes, determined
1973 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1974 binman uses that to look up the BSS address.
1978 .. _etype_u_boot_tpl_dtb:
1980 Entry: u-boot-tpl-dtb: U-Boot TPL device tree
1981 ---------------------------------------------
1983 Properties / Entry arguments:
1984 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
1986 This is the TPL device tree, containing configuration information for
1987 TPL. TPL needs this to know what devices are present and which drivers
1992 .. _etype_u_boot_tpl_dtb_with_ucode:
1994 Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
1995 ----------------------------------------------------------------------------
1997 This is used when TPL must set up the microcode for U-Boot.
1999 See Entry_u_boot_ucode for full details of the entries involved in this
2004 .. _etype_u_boot_tpl_elf:
2006 Entry: u-boot-tpl-elf: U-Boot TPL ELF image
2007 -------------------------------------------
2009 Properties / Entry arguments:
2010 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
2012 This is the U-Boot TPL ELF image. It does not include a device tree but can
2013 be relocated to any address for execution.
2017 .. _etype_u_boot_tpl_expanded:
2019 Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
2020 --------------------------------------------------------------------------------------
2022 Properties / Entry arguments:
2023 - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2026 This is a section containing the U-Boot binary, BSS padding if needed and a
2027 devicetree. Using this entry type automatically creates this section, with
2028 the following entries in it:
2034 Having the devicetree separate allows binman to update it in the final
2035 image, so that the entries positions are provided to the running U-Boot.
2037 This entry is selected based on the value of the 'tpl-dtb' entryarg. If
2038 this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2042 .. _etype_u_boot_tpl_nodtb:
2044 Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
2045 ----------------------------------------------------------------
2047 Properties / Entry arguments:
2048 - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin')
2050 This is the U-Boot TPL binary, It does not include a device tree blob at
2051 the end of it so may not be able to work without it, assuming TPL needs
2052 a device tree to operate on your platform. You can add a u-boot-tpl-dtb
2053 entry after this one, or use a u-boot-tpl entry instead, which normally
2054 expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
2057 TPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2059 in the binman README for more information.
2061 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2062 binman uses that to look up symbols to write into the TPL binary.
2066 .. _etype_u_boot_tpl_with_ucode_ptr:
2068 Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
2069 ----------------------------------------------------------------------------
2071 See Entry_u_boot_ucode for full details of the entries involved in this
2076 .. _etype_u_boot_ucode:
2078 Entry: u-boot-ucode: U-Boot microcode block
2079 -------------------------------------------
2081 Properties / Entry arguments:
2084 The contents of this entry are filled in automatically by other entries
2085 which must also be in the image.
2087 U-Boot on x86 needs a single block of microcode. This is collected from
2088 the various microcode update nodes in the device tree. It is also unable
2089 to read the microcode from the device tree on platforms that use FSP
2090 (Firmware Support Package) binaries, because the API requires that the
2091 microcode is supplied before there is any SRAM available to use (i.e.
2092 the FSP sets up the SRAM / cache-as-RAM but does so in the call that
2093 requires the microcode!). To keep things simple, all x86 platforms handle
2094 microcode the same way in U-Boot (even non-FSP platforms). This is that
2095 a table is placed at _dt_ucode_base_size containing the base address and
2096 size of the microcode. This is either passed to the FSP (for FSP
2097 platforms), or used to set up the microcode (for non-FSP platforms).
2098 This all happens in the build system since it is the only way to get
2099 the microcode into a single blob and accessible without SRAM.
2101 There are two cases to handle. If there is only one microcode blob in
2102 the device tree, then the ucode pointer it set to point to that. This
2103 entry (u-boot-ucode) is empty. If there is more than one update, then
2104 this entry holds the concatenation of all updates, and the device tree
2105 entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
2106 last step ensures that that the microcode appears in one contiguous
2107 block in the image and is not unnecessarily duplicated in the device
2108 tree. It is referred to as 'collation' here.
2110 Entry types that have a part to play in handling microcode:
2112 Entry_u_boot_with_ucode_ptr:
2113 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
2114 It updates it with the address and size of the microcode so that
2115 U-Boot can find it early on start-up.
2116 Entry_u_boot_dtb_with_ucode:
2117 Contains u-boot.dtb. It stores the microcode in a
2118 'self.ucode_data' property, which is then read by this class to
2119 obtain the microcode if needed. If collation is performed, it
2120 removes the microcode from the device tree.
2122 This class. If collation is enabled it reads the microcode from
2123 the Entry_u_boot_dtb_with_ucode entry, and uses it as the
2124 contents of this entry.
2128 .. _etype_u_boot_vpl:
2130 Entry: u-boot-vpl: U-Boot VPL binary
2131 ------------------------------------
2133 Properties / Entry arguments:
2134 - filename: Filename of u-boot-vpl.bin (default 'vpl/u-boot-vpl.bin')
2136 This is the U-Boot VPL (Verifying Program Loader) binary. This is a small
2137 binary which loads before SPL, typically into on-chip SRAM. It is
2138 responsible for locating, loading and jumping to SPL, the next-stage
2139 loader. Note that VPL is not relocatable so must be loaded to the correct
2140 address in SRAM, or written to run from the correct address if direct
2141 flash execution is possible (e.g. on x86 devices).
2143 SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2145 in the binman README for more information.
2147 The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2148 binman uses that to look up symbols to write into the VPL binary.
2152 .. _etype_u_boot_vpl_bss_pad:
2154 Entry: u-boot-vpl-bss-pad: U-Boot VPL binary padded with a BSS region
2155 ---------------------------------------------------------------------
2157 Properties / Entry arguments:
2160 This holds the padding added after the VPL binary to cover the BSS (Block
2161 Started by Symbol) region. This region holds the various variables used by
2162 VPL. It is set to 0 by VPL when it starts up. If you want to append data to
2163 the VPL image (such as a device tree file), you must pad out the BSS region
2164 to avoid the data overlapping with U-Boot variables. This entry is useful in
2165 that case. It automatically pads out the entry size to cover both the code,
2168 The contents of this entry will a certain number of zero bytes, determined
2171 The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2172 binman uses that to look up the BSS address.
2176 .. _etype_u_boot_vpl_dtb:
2178 Entry: u-boot-vpl-dtb: U-Boot VPL device tree
2179 ---------------------------------------------
2181 Properties / Entry arguments:
2182 - filename: Filename of u-boot.dtb (default 'vpl/u-boot-vpl.dtb')
2184 This is the VPL device tree, containing configuration information for
2185 VPL. VPL needs this to know what devices are present and which drivers
2190 .. _etype_u_boot_vpl_elf:
2192 Entry: u-boot-vpl-elf: U-Boot VPL ELF image
2193 -------------------------------------------
2195 Properties / Entry arguments:
2196 - filename: Filename of VPL u-boot (default 'vpl/u-boot-vpl')
2198 This is the U-Boot VPL ELF image. It does not include a device tree but can
2199 be relocated to any address for execution.
2203 .. _etype_u_boot_vpl_expanded:
2205 Entry: u-boot-vpl-expanded: U-Boot VPL flat binary broken out into its component parts
2206 --------------------------------------------------------------------------------------
2208 Properties / Entry arguments:
2209 - vpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2212 This is a section containing the U-Boot binary, BSS padding if needed and a
2213 devicetree. Using this entry type automatically creates this section, with
2214 the following entries in it:
2220 Having the devicetree separate allows binman to update it in the final
2221 image, so that the entries positions are provided to the running U-Boot.
2223 This entry is selected based on the value of the 'vpl-dtb' entryarg. If
2224 this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2228 .. _etype_u_boot_vpl_nodtb:
2230 Entry: u-boot-vpl-nodtb: VPL binary without device tree appended
2231 ----------------------------------------------------------------
2233 Properties / Entry arguments:
2234 - filename: Filename to include (default 'vpl/u-boot-vpl-nodtb.bin')
2236 This is the U-Boot VPL binary, It does not include a device tree blob at
2237 the end of it so may not be able to work without it, assuming VPL needs
2238 a device tree to operate on your platform. You can add a u_boot_vpl_dtb
2239 entry after this one, or use a u_boot_vpl entry instead, which normally
2240 expands to a section containing u-boot-vpl-dtb, u-boot-vpl-bss-pad and
2243 VPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2245 The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2246 binman uses that to look up symbols to write into the VPL binary.
2250 .. _etype_u_boot_with_ucode_ptr:
2252 Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
2253 --------------------------------------------------------------------
2255 Properties / Entry arguments:
2256 - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
2257 - optional-ucode: boolean property to make microcode optional. If the
2258 u-boot.bin image does not include microcode, no error will
2261 See Entry_u_boot_ucode for full details of the three entries involved in
2262 this process. This entry updates U-Boot with the offset and size of the
2263 microcode, to allow early x86 boot code to find it without doing anything
2264 complicated. Otherwise it is the same as the u-boot entry.
2270 Entry: vblock: An entry which contains a Chromium OS verified boot block
2271 ------------------------------------------------------------------------
2273 Properties / Entry arguments:
2274 - content: List of phandles to entries to sign
2275 - keydir: Directory containing the public keys to use
2276 - keyblock: Name of the key file to use (inside keydir)
2277 - signprivate: Name of provide key file to use (inside keydir)
2278 - version: Version number of the vblock (typically 1)
2279 - kernelkey: Name of the kernel key to use (inside keydir)
2280 - preamble-flags: Value of the vboot preamble flags (typically 0)
2283 - input.<unique_name> - input file passed to futility
2284 - vblock.<unique_name> - output file generated by futility (which is
2285 used as the entry contents)
2287 Chromium OS signs the read-write firmware and kernel, writing the signature
2288 in this block. This allows U-Boot to verify that the next firmware stage
2289 and kernel are genuine.
2293 .. _etype_x509_cert:
2295 Entry: x509-cert: An entry which contains an X509 certificate
2296 -------------------------------------------------------------
2298 Properties / Entry arguments:
2299 - content: List of phandles to entries to sign
2302 - input.<unique_name> - input file passed to openssl
2303 - cert.<unique_name> - output file generated by openssl (which is
2304 used as the entry contents)
2306 openssl signs the provided data, writing the signature in this entry. This
2307 allows verification that the data is genuine
2311 .. _etype_x86_reset16:
2313 Entry: x86-reset16: x86 16-bit reset code for U-Boot
2314 ----------------------------------------------------
2316 Properties / Entry arguments:
2317 - filename: Filename of u-boot-x86-reset16.bin (default
2318 'u-boot-x86-reset16.bin')
2320 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2321 must be placed at a particular address. This entry holds that code. It is
2322 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2323 for jumping to the x86-start16 code, which continues execution.
2325 For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
2329 .. _etype_x86_reset16_spl:
2331 Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
2332 --------------------------------------------------------
2334 Properties / Entry arguments:
2335 - filename: Filename of u-boot-x86-reset16.bin (default
2336 'u-boot-x86-reset16.bin')
2338 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2339 must be placed at a particular address. This entry holds that code. It is
2340 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2341 for jumping to the x86-start16 code, which continues execution.
2343 For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
2347 .. _etype_x86_reset16_tpl:
2349 Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
2350 --------------------------------------------------------
2352 Properties / Entry arguments:
2353 - filename: Filename of u-boot-x86-reset16.bin (default
2354 'u-boot-x86-reset16.bin')
2356 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2357 must be placed at a particular address. This entry holds that code. It is
2358 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2359 for jumping to the x86-start16 code, which continues execution.
2361 For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
2365 .. _etype_x86_start16:
2367 Entry: x86-start16: x86 16-bit start-up code for U-Boot
2368 -------------------------------------------------------
2370 Properties / Entry arguments:
2371 - filename: Filename of u-boot-x86-start16.bin (default
2372 'u-boot-x86-start16.bin')
2374 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2375 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2376 entry holds that code. It is typically placed at offset
2377 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2378 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2381 For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
2385 .. _etype_x86_start16_spl:
2387 Entry: x86-start16-spl: x86 16-bit start-up code for SPL
2388 --------------------------------------------------------
2390 Properties / Entry arguments:
2391 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
2392 'spl/u-boot-x86-start16-spl.bin')
2394 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2395 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2396 entry holds that code. It is typically placed at offset
2397 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2398 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2401 For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
2405 .. _etype_x86_start16_tpl:
2407 Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
2408 --------------------------------------------------------
2410 Properties / Entry arguments:
2411 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
2412 'tpl/u-boot-x86-start16-tpl.bin')
2414 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2415 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2416 entry holds that code. It is typically placed at offset
2417 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2418 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2421 If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
2422 may be used instead.