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 Properties / Entry arguments:
220 - prepend: Header type to use:
221 length: 32-bit length header
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 the entry argument which provides the list of device tree
609 files for the gen-fdt-nodes operation (as below). This is often
610 `of-list` meaning that `-a of-list="dtb1 dtb2..."` should be passed
616 Node names and property values support a basic string-substitution feature.
617 Available substitutions for '@' nodes (and property values) are:
620 Sequence number of the generated fdt (1, 2, ...)
622 Name of the dtb as provided (i.e. without adding '.dtb')
624 The `default` property, if present, will be automatically set to the name
625 if of configuration whose devicetree matches the `default-dt` entry
626 argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.
628 Available substitutions for property values in these nodes are:
631 Sequence number of the default fdt, as provided by the 'default-dt'
637 You can add an operation to an '@' node to indicate which operation is
641 fit,operation = "gen-fdt-nodes";
645 Available operations are:
648 Generate FDT nodes as above. This is the default if there is no
649 `fit,operation` property.
652 Split an ELF file into a separate node for each segment.
654 Generating nodes from an FDT list (gen-fdt-nodes)
655 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
657 U-Boot supports creating fdt and config nodes automatically. To do this,
658 pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells
659 binman that you want to generates nodes for two files: `file1.dtb` and
660 `file2.dtb`. The `fit,fdt-list` property (see above) indicates that
661 `of-list` should be used. If the property is missing you will get an error.
663 Then add a 'generator node', a node with a name starting with '@'::
667 description = "fdt-NAME";
669 compression = "none";
673 This tells binman to create nodes `fdt-1` and `fdt-2` for each of your two
674 files. All the properties you specify will be included in the node. This
675 node acts like a template to generate the nodes. The generator node itself
676 does not appear in the output - it is replaced with what binman generates.
677 A 'data' property is created with the contents of the FDT file.
679 You can create config nodes in a similar way::
682 default = "@config-DEFAULT-SEQ";
684 description = "NAME";
691 This tells binman to create nodes `config-1` and `config-2`, i.e. a config
692 for each of your two files.
694 Note that if no devicetree files are provided (with '-a of-list' as above)
695 then no nodes will be generated.
697 Generating nodes from an ELF file (split-elf)
698 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
700 This uses the node as a template to generate multiple nodes. The following
701 special properties are available:
704 Split an ELF file into a separate node for each segment. This uses the
705 node as a template to generate multiple nodes. The following special
706 properties are available:
709 Generates a `load = <...>` property with the load address of the
713 Generates a `entry = <...>` property with the entry address of the
714 ELF. This is only produced for the first entry
717 Generates a `data = <...>` property with the contents of the segment
720 Generates a `loadable = <...>` property with a list of the generated
721 nodes (including all nodes if this operation is used multiple times)
724 Here is an example showing ATF, TEE and a device tree all combined::
727 description = "test-desc";
728 #address-cells = <1>;
729 fit,fdt-list = "of-list";
733 description = "U-Boot (64-bit)";
737 compression = "none";
738 load = <CONFIG_TEXT_BASE>;
743 description = "fdt-NAME.dtb";
745 compression = "none";
748 fit,operation = "split-elf";
749 description = "ARM Trusted Firmware";
752 os = "arm-trusted-firmware";
753 compression = "none";
763 fit,operation = "split-elf";
768 compression = "none";
779 default = "@config-DEFAULT-SEQ";
781 description = "conf-NAME.dtb";
789 If ATF-BL31 is available, this generates a node for each segment in the
790 ELF file, for example::
794 data = <...contents of first segment...>;
795 data-offset = <0x00000000>;
796 entry = <0x00040000>;
798 compression = "none";
799 os = "arm-trusted-firmware";
802 description = "ARM Trusted Firmware";
805 data = <...contents of second segment...>;
807 compression = "none";
808 os = "arm-trusted-firmware";
811 description = "ARM Trusted Firmware";
815 The same applies for OP-TEE if that is available.
817 If each binary is not available, the relevant template node (@atf-SEQ or
818 @tee-SEQ) is removed from the output.
820 This also generates a `config-xxx` node for each device tree in `of-list`.
821 Note that the U-Boot build system uses `-a of-list=$(CONFIG_OF_LIST)`
822 so you can use `CONFIG_OF_LIST` to define that list. In this example it is
823 set up for `firefly-rk3399` with a single device tree and the default set
824 with `-a default-dt=$(CONFIG_DEFAULT_DEVICE_TREE)`, so the resulting output
828 default = "config-1";
830 loadables = "atf-1", "atf-2", "atf-3", "tee-1", "tee-2";
831 description = "rk3399-firefly.dtb";
837 U-Boot SPL can then load the firmware (U-Boot proper) and all the loadables
838 (ATF and TEE), then proceed with the boot.
844 Entry: fmap: An entry which contains an Fmap section
845 ----------------------------------------------------
847 Properties / Entry arguments:
850 FMAP is a simple format used by flashrom, an open-source utility for
851 reading and writing the SPI flash, typically on x86 CPUs. The format
852 provides flashrom with a list of areas, so it knows what it in the flash.
853 It can then read or write just a single area, instead of the whole flash.
855 The format is defined by the flashrom project, in the file lib/fmap.h -
856 see www.flashrom.org/Flashrom for more information.
858 When used, this entry will be populated with an FMAP which reflects the
859 entries in the current image. Note that any hierarchy is squashed, since
860 FMAP does not support this. Sections are represented as an area appearing
861 before its contents, so that it is possible to reconstruct the hierarchy
862 from the FMAP by using the offset information. This convention does not
863 seem to be documented, but is used in Chromium OS.
865 CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
871 Entry: gbb: An entry which contains a Chromium OS Google Binary Block
872 ---------------------------------------------------------------------
874 Properties / Entry arguments:
875 - hardware-id: Hardware ID to use for this build (a string)
876 - keydir: Directory containing the public keys to use
877 - bmpblk: Filename containing images used by recovery
879 Chromium OS uses a GBB to store various pieces of information, in particular
880 the root and recovery keys that are used to verify the boot process. Some
881 more details are here:
883 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
885 but note that the page dates from 2013 so is quite out of date. See
886 README.chromium for how to obtain the required keys and tools.
890 .. _etype_image_header:
892 Entry: image-header: An entry which contains a pointer to the FDT map
893 ---------------------------------------------------------------------
895 Properties / Entry arguments:
896 location: Location of header ("start" or "end" of image). This is
897 optional. If omitted then the entry must have an offset property.
899 This adds an 8-byte entry to the start or end of the image, pointing to the
900 location of the FDT map. The format is a magic number followed by an offset
901 from the start or end of the image, in twos-compliment format.
903 This entry must be in the top-level part of the image.
905 NOTE: If the location is at the start/end, you will probably need to specify
906 sort-by-offset for the image, unless you actually put the image header
907 first/last in the entry list.
913 Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
914 -----------------------------------------------------
916 Properties / Entry arguments:
917 - filename: Filename of file to read into entry
919 This file contains microcode for some devices in a special format. An
920 example filename is 'Microcode/C0_22211.BIN'.
922 See README.x86 for information about x86 binary blobs.
926 .. _etype_intel_descriptor:
928 Entry: intel-descriptor: Intel flash descriptor block (4KB)
929 -----------------------------------------------------------
931 Properties / Entry arguments:
932 filename: Filename of file containing the descriptor. This is typically
933 a 4KB binary file, sometimes called 'descriptor.bin'
935 This entry is placed at the start of flash and provides information about
936 the SPI flash regions. In particular it provides the base address and
937 size of the ME (Management Engine) region, allowing us to place the ME
938 binary in the right place.
940 With this entry in your image, the position of the 'intel-me' entry will be
941 fixed in the image, which avoids you needed to specify an offset for that
942 region. This is useful, because it is not possible to change the position
943 of the ME region without updating the descriptor.
945 See README.x86 for information about x86 binary blobs.
951 Entry: intel-fit: Intel Firmware Image Table (FIT)
952 --------------------------------------------------
954 This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
955 contains information about the firmware and microcode available in the
958 At present binman only supports a basic FIT with no microcode.
962 .. _etype_intel_fit_ptr:
964 Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
965 --------------------------------------------------------------
967 This entry contains a pointer to the FIT. It is required to be at address
968 0xffffffc0 in the image.
974 Entry: intel-fsp: Intel Firmware Support Package (FSP) file
975 -----------------------------------------------------------
977 Properties / Entry arguments:
978 - filename: Filename of file to read into entry
980 This file contains binary blobs which are used on some devices to make the
981 platform work. U-Boot executes this code since it is not possible to set up
982 the hardware using U-Boot open-source code. Documentation is typically not
983 available in sufficient detail to allow this.
985 An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
987 See README.x86 for information about x86 binary blobs.
991 .. _etype_intel_fsp_m:
993 Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
994 --------------------------------------------------------------------
996 Properties / Entry arguments:
997 - filename: Filename of file to read into entry
999 This file contains a binary blob which is used on some devices to set up
1000 SDRAM. U-Boot executes this code in SPL so that it can make full use of
1001 memory. Documentation is typically not available in sufficient detail to
1002 allow U-Boot do this this itself..
1004 An example filename is 'fsp_m.bin'
1006 See README.x86 for information about x86 binary blobs.
1010 .. _etype_intel_fsp_s:
1012 Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
1013 ---------------------------------------------------------------------
1015 Properties / Entry arguments:
1016 - filename: Filename of file to read into entry
1018 This file contains a binary blob which is used on some devices to set up
1019 the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
1020 running, so that it can make full use of memory. Documentation is typically
1021 not available in sufficient detail to allow U-Boot do this this itself.
1023 An example filename is 'fsp_s.bin'
1025 See README.x86 for information about x86 binary blobs.
1029 .. _etype_intel_fsp_t:
1031 Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
1032 ----------------------------------------------------------------------
1034 Properties / Entry arguments:
1035 - filename: Filename of file to read into entry
1037 This file contains a binary blob which is used on some devices to set up
1038 temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
1039 that it has access to memory for its stack and initial storage.
1041 An example filename is 'fsp_t.bin'
1043 See README.x86 for information about x86 binary blobs.
1047 .. _etype_intel_ifwi:
1049 Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
1050 --------------------------------------------------------------
1052 Properties / Entry arguments:
1053 - filename: Filename of file to read into entry. This is either the
1054 IFWI file itself, or a file that can be converted into one using a
1056 - convert-fit: If present this indicates that the ifwitool should be
1057 used to convert the provided file into a IFWI.
1059 This file contains code and data used by the SoC that is required to make
1060 it work. It includes U-Boot TPL, microcode, things related to the CSE
1061 (Converged Security Engine, the microcontroller that loads all the firmware)
1062 and other items beyond the wit of man.
1064 A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
1065 file that will be converted to an IFWI.
1067 The position of this entry is generally set by the intel-descriptor entry.
1069 The contents of the IFWI are specified by the subnodes of the IFWI node.
1070 Each subnode describes an entry which is placed into the IFWFI with a given
1071 sub-partition (and optional entry name).
1073 Properties for subnodes:
1074 - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
1075 - ifwi-entry: entry name t use, e.g. "IBBL"
1076 - ifwi-replace: if present, indicates that the item should be replaced
1077 in the IFWI. Otherwise it is added.
1079 See README.x86 for information about x86 binary blobs.
1085 Entry: intel-me: Intel Management Engine (ME) file
1086 --------------------------------------------------
1088 Properties / Entry arguments:
1089 - filename: Filename of file to read into entry
1091 This file contains code used by the SoC that is required to make it work.
1092 The Management Engine is like a background task that runs things that are
1093 not clearly documented, but may include keyboard, display and network
1094 access. For platform that use ME it is not possible to disable it. U-Boot
1095 does not directly execute code in the ME binary.
1097 A typical filename is 'me.bin'.
1099 The position of this entry is generally set by the intel-descriptor entry.
1101 See README.x86 for information about x86 binary blobs.
1105 .. _etype_intel_mrc:
1107 Entry: intel-mrc: Intel Memory Reference Code (MRC) file
1108 --------------------------------------------------------
1110 Properties / Entry arguments:
1111 - filename: Filename of file to read into entry
1113 This file contains code for setting up the SDRAM on some Intel systems. This
1114 is executed by U-Boot when needed early during startup. A typical filename
1117 See README.x86 for information about x86 binary blobs.
1121 .. _etype_intel_refcode:
1123 Entry: intel-refcode: Intel Reference Code file
1124 -----------------------------------------------
1126 Properties / Entry arguments:
1127 - filename: Filename of file to read into entry
1129 This file contains code for setting up the platform on some Intel systems.
1130 This is executed by U-Boot when needed early during startup. A typical
1131 filename is 'refcode.bin'.
1133 See README.x86 for information about x86 binary blobs.
1137 .. _etype_intel_vbt:
1139 Entry: intel-vbt: Intel Video BIOS Table (VBT) file
1140 ---------------------------------------------------
1142 Properties / Entry arguments:
1143 - filename: Filename of file to read into entry
1145 This file contains code that sets up the integrated graphics subsystem on
1146 some Intel SoCs. U-Boot executes this when the display is started up.
1148 See README.x86 for information about Intel binary blobs.
1152 .. _etype_intel_vga:
1154 Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
1155 ---------------------------------------------------------
1157 Properties / Entry arguments:
1158 - filename: Filename of file to read into entry
1160 This file contains code that sets up the integrated graphics subsystem on
1161 some Intel SoCs. U-Boot executes this when the display is started up.
1163 This is similar to the VBT file but in a different format.
1165 See README.x86 for information about Intel binary blobs.
1171 Entry: mkimage: Binary produced by mkimage
1172 ------------------------------------------
1174 Properties / Entry arguments:
1175 - args: Arguments to pass
1176 - data-to-imagename: Indicates that the -d data should be passed in as
1177 the image name also (-n)
1178 - multiple-data-files: boolean to tell binman to pass all files as
1179 datafiles to mkimage instead of creating a temporary file the result
1180 of datafiles concatenation
1182 The data passed to mkimage via the -d flag is collected from subnodes of the
1183 mkimage node, e.g.::
1186 args = "-n test -T imximage";
1192 This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
1193 file, which mkimage being called like this::
1195 mkimage -d <data_file> -n test -T imximage <output_file>
1197 The output from mkimage then becomes part of the image produced by
1198 binman. If you need to put mulitple things in the data file, you can use
1199 a section, or just multiple subnodes like this::
1202 args = "-n test -T imximage";
1211 To pass all datafiles untouched to mkimage::
1214 args = "-n rk3399 -T rkspi";
1215 multiple-data-files;
1224 This calls mkimage to create a Rockchip RK3399-specific first stage
1225 bootloader, made of TPL+SPL. Since this first stage bootloader requires to
1226 align the TPL and SPL but also some weird hacks that is handled by mkimage
1227 directly, binman is told to not perform the concatenation of datafiles prior
1228 to passing the data to mkimage.
1230 To use CONFIG options in the arguments, use a string list instead, as in
1231 this example which also produces four arguments::
1234 args = "-n", CONFIG_SYS_SOC, "-T imximage";
1240 If you need to pass the input data in with the -n argument as well, then use
1241 the 'data-to-imagename' property::
1244 args = "-T imximage";
1251 That will pass the data to mkimage both as the data file (with -d) and as
1252 the image name (with -n).
1255 If need to pass different data in with -n, then use an imagename subnode::
1258 args = "-T imximage";
1262 filename = "spl/u-boot-spl.cfgout"
1270 This will pass in u-boot-spl as the input data and the .cfgout file as the
1276 Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
1277 ----------------------------------------------
1279 Properties / Entry arguments:
1280 - opensbi-path: Filename of file to read into entry. This is typically
1281 called fw_dynamic.bin
1283 This entry holds the run-time firmware, typically started by U-Boot SPL.
1284 See the U-Boot README for your architecture or board for how to use it. See
1285 https://github.com/riscv/opensbi for more information about OpenSBI.
1289 .. _etype_powerpc_mpc85xx_bootpg_resetvec:
1291 Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
1292 -----------------------------------------------------------------------------------------
1294 Properties / Entry arguments:
1295 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
1297 This entry is valid for PowerPC mpc85xx cpus. This entry holds
1298 'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
1299 placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
1305 Entry: pre-load: Pre load image header
1306 --------------------------------------
1308 Properties / Entry arguments:
1309 - pre-load-key-path: Path of the directory that store key (provided by
1310 the environment variable PRE_LOAD_KEY_PATH)
1311 - content: List of phandles to entries to sign
1312 - algo-name: Hash and signature algo to use for the signature
1313 - padding-name: Name of the padding (pkcs-1.5 or pss)
1314 - key-name: Filename of the private key to sign
1315 - header-size: Total size of the header
1316 - version: Version of the header
1318 This entry creates a pre-load header that contains a global
1321 For example, this creates an image with a pre-load header and a binary::
1325 filename = "sandbox.bin";
1329 algo-name = "sha256,rsa2048";
1330 padding-name = "pss";
1331 key-name = "private.pem";
1332 header-size = <4096>;
1337 filename = "sandbox.itb";
1346 Entry: scp: System Control Processor (SCP) firmware blob
1347 --------------------------------------------------------
1349 Properties / Entry arguments:
1350 - scp-path: Filename of file to read into the entry, typically scp.bin
1352 This entry holds firmware for an external platform-specific coprocessor.
1358 Entry: section: Entry that contains other entries
1359 -------------------------------------------------
1361 A section is an entry which can contain other entries, thus allowing
1362 hierarchical images to be created. See 'Sections and hierarchical images'
1363 in the binman README for more information.
1365 The base implementation simply joins the various entries together, using
1366 various rules about alignment, etc.
1371 This class can be subclassed to support other file formats which hold
1372 multiple entries, such as CBFS. To do this, override the following
1373 functions. The documentation here describes what your function should do.
1374 For example code, see etypes which subclass `Entry_section`, or `cbfs.py`
1375 for a more involved example::
1377 $ grep -l \(Entry_section tools/binman/etype/*.py
1380 Call `super().ReadNode()`, then read any special properties for the
1381 section. Then call `self.ReadEntries()` to read the entries.
1383 Binman calls this at the start when reading the image description.
1386 Read in the subnodes of the section. This may involve creating entries
1387 of a particular etype automatically, as well as reading any special
1388 properties in the entries. For each entry, entry.ReadNode() should be
1389 called, to read the basic entry properties. The properties should be
1390 added to `self._entries[]`, in the correct order, with a suitable name.
1392 Binman calls this at the start when reading the image description.
1394 BuildSectionData(required)
1395 Create the custom file format that you want and return it as bytes.
1396 This likely sets up a file header, then loops through the entries,
1397 adding them to the file. For each entry, call `entry.GetData()` to
1398 obtain the data. If that returns None, and `required` is False, then
1399 this method must give up and return None. But if `required` is True then
1400 it should assume that all data is valid.
1402 Binman calls this when packing the image, to find out the size of
1403 everything. It is called again at the end when building the final image.
1405 SetImagePos(image_pos):
1406 Call `super().SetImagePos(image_pos)`, then set the `image_pos` values
1407 for each of the entries. This should use the custom file format to find
1408 the `start offset` (and `image_pos`) of each entry. If the file format
1409 uses compression in such a way that there is no offset available (other
1410 than reading the whole file and decompressing it), then the offsets for
1411 affected entries can remain unset (`None`). The size should also be set
1414 Binman calls this after the image has been packed, to update the
1415 location that all the entries ended up at.
1417 ReadChildData(child, decomp, alt_format):
1418 The default version of this may be good enough, if you are able to
1419 implement SetImagePos() correctly. But that is a bit of a bypass, so
1420 you can override this method to read from your custom file format. It
1421 should read the entire entry containing the custom file using
1422 `super().ReadData(True)`, then parse the file to get the data for the
1423 given child, then return that data.
1425 If your file format supports compression, the `decomp` argument tells
1426 you whether to return the compressed data (`decomp` is False) or to
1427 uncompress it first, then return the uncompressed data (`decomp` is
1428 True). This is used by the `binman extract -U` option.
1430 If your entry supports alternative formats, the alt_format provides the
1431 alternative format that the user has selected. Your function should
1432 return data in that format. This is used by the 'binman extract -l'
1435 Binman calls this when reading in an image, in order to populate all the
1436 entries with the data from that image (`binman ls`).
1438 WriteChildData(child):
1439 Binman calls this after `child.data` is updated, to inform the custom
1440 file format about this, in case it needs to do updates.
1442 The default version of this does nothing and probably needs to be
1443 overridden for the 'binman replace' command to work. Your version should
1444 use `child.data` to update the data for that child in the custom file
1447 Binman calls this when updating an image that has been read in and in
1448 particular to update the data for a particular entry (`binman replace`)
1450 Properties / Entry arguments
1451 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1453 See :ref:`develop/package/binman:Image description format` for more
1457 Default alignment for this section, if no alignment is given in the
1461 Pad byte to use when padding
1464 True if entries should be sorted by offset, False if they must be
1465 in-order in the device tree description
1468 Used to build an x86 ROM which ends at 4GB (2^32)
1471 Adds a prefix to the name of every entry in the section when writing out
1475 Number of bytes before the first entry starts. These effectively adjust
1476 the starting offset of entries. For example, if this is 16, then the
1477 first entry would start at 16. An entry with offset = 20 would in fact
1478 be written at offset 4 in the image file, since the first 16 bytes are
1479 skipped when writing.
1481 Since a section is also an entry, it inherits all the properies of entries
1484 Note that the `allow_missing` member controls whether this section permits
1485 external blobs to be missing their contents. The option will produce an
1486 image but of course it will not work. It is useful to make sure that
1487 Continuous Integration systems can build without the binaries being
1488 available. This is set by the `SetAllowMissing()` method, if
1489 `--allow-missing` is passed to binman.
1495 Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
1496 ---------------------------------------------------------------
1498 Properties / Entry arguments:
1499 - tee-os-path: Filename of file to read into entry. This is typically
1500 called tee-pager.bin
1502 This entry holds the run-time firmware, typically started by U-Boot SPL.
1503 See the U-Boot README for your architecture or board for how to use it. See
1504 https://github.com/OP-TEE/optee_os for more information about OP-TEE.
1510 Entry: text: An entry which contains text
1511 -----------------------------------------
1513 The text can be provided either in the node itself or by a command-line
1514 argument. There is a level of indirection to allow multiple text strings
1515 and sharing of text.
1517 Properties / Entry arguments:
1518 text-label: The value of this string indicates the property / entry-arg
1519 that contains the string to place in the entry
1520 <xxx> (actual name is the value of text-label): contains the string to
1522 <text>: The text to place in the entry (overrides the above mechanism).
1523 This is useful when the text is constant.
1529 text-label = "message";
1534 binman -amessage="this is my message"
1536 and binman will insert that string into the entry.
1538 It is also possible to put the string directly in the node::
1542 text-label = "message";
1543 message = "a message directly in the node"
1550 text = "some text directly in the node"
1553 The text is not itself nul-terminated. This can be achieved, if required,
1554 by setting the size of the entry to something larger than the text.
1560 Entry: u-boot: U-Boot flat binary
1561 ---------------------------------
1563 Properties / Entry arguments:
1564 - filename: Filename of u-boot.bin (default 'u-boot.bin')
1566 This is the U-Boot binary, containing relocation information to allow it
1567 to relocate itself at runtime. The binary typically includes a device tree
1568 blob at the end of it.
1570 U-Boot can access binman symbols at runtime. See:
1572 'Access to binman entry offsets at run time (fdt)'
1574 in the binman README for more information.
1576 Note that this entry is automatically replaced with u-boot-expanded unless
1577 --no-expanded is used or the node has a 'no-expanded' property.
1581 .. _etype_u_boot_dtb:
1583 Entry: u-boot-dtb: U-Boot device tree
1584 -------------------------------------
1586 Properties / Entry arguments:
1587 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1589 This is the U-Boot device tree, containing configuration information for
1590 U-Boot. U-Boot needs this to know what devices are present and which drivers
1593 Note: This is mostly an internal entry type, used by others. This allows
1594 binman to know which entries contain a device tree.
1598 .. _etype_u_boot_dtb_with_ucode:
1600 Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
1601 -----------------------------------------------------------------------------------
1603 Properties / Entry arguments:
1604 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1606 See Entry_u_boot_ucode for full details of the three entries involved in
1607 this process. This entry provides the U-Boot device-tree file, which
1608 contains the microcode. If the microcode is not being collated into one
1609 place then the offset and size of the microcode is recorded by this entry,
1610 for use by u-boot-with-ucode_ptr. If it is being collated, then this
1611 entry deletes the microcode from the device tree (to save space) and makes
1612 it available to u-boot-ucode.
1616 .. _etype_u_boot_elf:
1618 Entry: u-boot-elf: U-Boot ELF image
1619 -----------------------------------
1621 Properties / Entry arguments:
1622 - filename: Filename of u-boot (default 'u-boot')
1624 This is the U-Boot ELF image. It does not include a device tree but can be
1625 relocated to any address for execution.
1629 .. _etype_u_boot_env:
1631 Entry: u-boot-env: An entry which contains a U-Boot environment
1632 ---------------------------------------------------------------
1634 Properties / Entry arguments:
1635 - filename: File containing the environment text, with each line in the
1640 .. _etype_u_boot_expanded:
1642 Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
1643 ------------------------------------------------------------------------------
1645 This is a section containing the U-Boot binary and a devicetree. Using this
1646 entry type automatically creates this section, with the following entries
1652 Having the devicetree separate allows binman to update it in the final
1653 image, so that the entries positions are provided to the running U-Boot.
1657 .. _etype_u_boot_img:
1659 Entry: u-boot-img: U-Boot legacy image
1660 --------------------------------------
1662 Properties / Entry arguments:
1663 - filename: Filename of u-boot.img (default 'u-boot.img')
1665 This is the U-Boot binary as a packaged image, in legacy format. It has a
1666 header which allows it to be loaded at the correct address for execution.
1668 You should use FIT (Flat Image Tree) instead of the legacy image for new
1673 .. _etype_u_boot_nodtb:
1675 Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
1676 --------------------------------------------------------------------
1678 Properties / Entry arguments:
1679 - filename: Filename to include (default 'u-boot-nodtb.bin')
1681 This is the U-Boot binary, containing relocation information to allow it
1682 to relocate itself at runtime. It does not include a device tree blob at
1683 the end of it so normally cannot work without it. You can add a u-boot-dtb
1684 entry after this one, or use a u-boot entry instead, normally expands to a
1685 section containing u-boot and u-boot-dtb
1689 .. _etype_u_boot_spl:
1691 Entry: u-boot-spl: U-Boot SPL binary
1692 ------------------------------------
1694 Properties / Entry arguments:
1695 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
1697 This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
1698 binary which loads before U-Boot proper, typically into on-chip SRAM. It is
1699 responsible for locating, loading and jumping to U-Boot. Note that SPL is
1700 not relocatable so must be loaded to the correct address in SRAM, or written
1701 to run from the correct address if direct flash execution is possible (e.g.
1704 SPL can access binman symbols at runtime. See:
1706 'Access to binman entry offsets at run time (symbols)'
1708 in the binman README for more information.
1710 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1711 binman uses that to look up symbols to write into the SPL binary.
1713 Note that this entry is automatically replaced with u-boot-spl-expanded
1714 unless --no-expanded is used or the node has a 'no-expanded' property.
1718 .. _etype_u_boot_spl_bss_pad:
1720 Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
1721 ---------------------------------------------------------------------
1723 Properties / Entry arguments:
1726 This holds the padding added after the SPL binary to cover the BSS (Block
1727 Started by Symbol) region. This region holds the various variables used by
1728 SPL. It is set to 0 by SPL when it starts up. If you want to append data to
1729 the SPL image (such as a device tree file), you must pad out the BSS region
1730 to avoid the data overlapping with U-Boot variables. This entry is useful in
1731 that case. It automatically pads out the entry size to cover both the code,
1734 The contents of this entry will a certain number of zero bytes, determined
1737 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1738 binman uses that to look up the BSS address.
1742 .. _etype_u_boot_spl_dtb:
1744 Entry: u-boot-spl-dtb: U-Boot SPL device tree
1745 ---------------------------------------------
1747 Properties / Entry arguments:
1748 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
1750 This is the SPL device tree, containing configuration information for
1751 SPL. SPL needs this to know what devices are present and which drivers
1756 .. _etype_u_boot_spl_elf:
1758 Entry: u-boot-spl-elf: U-Boot SPL ELF image
1759 -------------------------------------------
1761 Properties / Entry arguments:
1762 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
1764 This is the U-Boot SPL ELF image. It does not include a device tree but can
1765 be relocated to any address for execution.
1769 .. _etype_u_boot_spl_expanded:
1771 Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
1772 --------------------------------------------------------------------------------------
1774 Properties / Entry arguments:
1775 - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
1778 This is a section containing the U-Boot binary, BSS padding if needed and a
1779 devicetree. Using this entry type automatically creates this section, with
1780 the following entries in it:
1786 Having the devicetree separate allows binman to update it in the final
1787 image, so that the entries positions are provided to the running U-Boot.
1789 This entry is selected based on the value of the 'spl-dtb' entryarg. If
1790 this is non-empty (and not 'n' or '0') then this expanded entry is selected.
1794 .. _etype_u_boot_spl_nodtb:
1796 Entry: u-boot-spl-nodtb: SPL binary without device tree appended
1797 ----------------------------------------------------------------
1799 Properties / Entry arguments:
1800 - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin')
1802 This is the U-Boot SPL binary, It does not include a device tree blob at
1803 the end of it so may not be able to work without it, assuming SPL needs
1804 a device tree to operate on your platform. You can add a u-boot-spl-dtb
1805 entry after this one, or use a u-boot-spl entry instead' which normally
1806 expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
1809 SPL can access binman symbols at runtime. See:
1811 'Access to binman entry offsets at run time (symbols)'
1813 in the binman README for more information.
1815 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1816 binman uses that to look up symbols to write into the SPL binary.
1820 .. _etype_u_boot_spl_with_ucode_ptr:
1822 Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
1823 ----------------------------------------------------------------------------
1825 This is used when SPL must set up the microcode for U-Boot.
1827 See Entry_u_boot_ucode for full details of the entries involved in this
1832 .. _etype_u_boot_tpl:
1834 Entry: u-boot-tpl: U-Boot TPL binary
1835 ------------------------------------
1837 Properties / Entry arguments:
1838 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
1840 This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
1841 binary which loads before SPL, typically into on-chip SRAM. It is
1842 responsible for locating, loading and jumping to SPL, the next-stage
1843 loader. Note that SPL is not relocatable so must be loaded to the correct
1844 address in SRAM, or written to run from the correct address if direct
1845 flash execution is possible (e.g. on x86 devices).
1847 SPL can access binman symbols at runtime. See:
1849 'Access to binman entry offsets at run time (symbols)'
1851 in the binman README for more information.
1853 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1854 binman uses that to look up symbols to write into the TPL binary.
1856 Note that this entry is automatically replaced with u-boot-tpl-expanded
1857 unless --no-expanded is used or the node has a 'no-expanded' property.
1861 .. _etype_u_boot_tpl_bss_pad:
1863 Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
1864 ---------------------------------------------------------------------
1866 Properties / Entry arguments:
1869 This holds the padding added after the TPL binary to cover the BSS (Block
1870 Started by Symbol) region. This region holds the various variables used by
1871 TPL. It is set to 0 by TPL when it starts up. If you want to append data to
1872 the TPL image (such as a device tree file), you must pad out the BSS region
1873 to avoid the data overlapping with U-Boot variables. This entry is useful in
1874 that case. It automatically pads out the entry size to cover both the code,
1877 The contents of this entry will a certain number of zero bytes, determined
1880 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1881 binman uses that to look up the BSS address.
1885 .. _etype_u_boot_tpl_dtb:
1887 Entry: u-boot-tpl-dtb: U-Boot TPL device tree
1888 ---------------------------------------------
1890 Properties / Entry arguments:
1891 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
1893 This is the TPL device tree, containing configuration information for
1894 TPL. TPL needs this to know what devices are present and which drivers
1899 .. _etype_u_boot_tpl_dtb_with_ucode:
1901 Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
1902 ----------------------------------------------------------------------------
1904 This is used when TPL must set up the microcode for U-Boot.
1906 See Entry_u_boot_ucode for full details of the entries involved in this
1911 .. _etype_u_boot_tpl_elf:
1913 Entry: u-boot-tpl-elf: U-Boot TPL ELF image
1914 -------------------------------------------
1916 Properties / Entry arguments:
1917 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
1919 This is the U-Boot TPL ELF image. It does not include a device tree but can
1920 be relocated to any address for execution.
1924 .. _etype_u_boot_tpl_expanded:
1926 Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
1927 --------------------------------------------------------------------------------------
1929 Properties / Entry arguments:
1930 - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
1933 This is a section containing the U-Boot binary, BSS padding if needed and a
1934 devicetree. Using this entry type automatically creates this section, with
1935 the following entries in it:
1941 Having the devicetree separate allows binman to update it in the final
1942 image, so that the entries positions are provided to the running U-Boot.
1944 This entry is selected based on the value of the 'tpl-dtb' entryarg. If
1945 this is non-empty (and not 'n' or '0') then this expanded entry is selected.
1949 .. _etype_u_boot_tpl_nodtb:
1951 Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
1952 ----------------------------------------------------------------
1954 Properties / Entry arguments:
1955 - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin')
1957 This is the U-Boot TPL binary, It does not include a device tree blob at
1958 the end of it so may not be able to work without it, assuming TPL needs
1959 a device tree to operate on your platform. You can add a u-boot-tpl-dtb
1960 entry after this one, or use a u-boot-tpl entry instead, which normally
1961 expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
1964 TPL can access binman symbols at runtime. See:
1966 'Access to binman entry offsets at run time (symbols)'
1968 in the binman README for more information.
1970 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1971 binman uses that to look up symbols to write into the TPL binary.
1975 .. _etype_u_boot_tpl_with_ucode_ptr:
1977 Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
1978 ----------------------------------------------------------------------------
1980 See Entry_u_boot_ucode for full details of the entries involved in this
1985 .. _etype_u_boot_ucode:
1987 Entry: u-boot-ucode: U-Boot microcode block
1988 -------------------------------------------
1990 Properties / Entry arguments:
1993 The contents of this entry are filled in automatically by other entries
1994 which must also be in the image.
1996 U-Boot on x86 needs a single block of microcode. This is collected from
1997 the various microcode update nodes in the device tree. It is also unable
1998 to read the microcode from the device tree on platforms that use FSP
1999 (Firmware Support Package) binaries, because the API requires that the
2000 microcode is supplied before there is any SRAM available to use (i.e.
2001 the FSP sets up the SRAM / cache-as-RAM but does so in the call that
2002 requires the microcode!). To keep things simple, all x86 platforms handle
2003 microcode the same way in U-Boot (even non-FSP platforms). This is that
2004 a table is placed at _dt_ucode_base_size containing the base address and
2005 size of the microcode. This is either passed to the FSP (for FSP
2006 platforms), or used to set up the microcode (for non-FSP platforms).
2007 This all happens in the build system since it is the only way to get
2008 the microcode into a single blob and accessible without SRAM.
2010 There are two cases to handle. If there is only one microcode blob in
2011 the device tree, then the ucode pointer it set to point to that. This
2012 entry (u-boot-ucode) is empty. If there is more than one update, then
2013 this entry holds the concatenation of all updates, and the device tree
2014 entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
2015 last step ensures that that the microcode appears in one contiguous
2016 block in the image and is not unnecessarily duplicated in the device
2017 tree. It is referred to as 'collation' here.
2019 Entry types that have a part to play in handling microcode:
2021 Entry_u_boot_with_ucode_ptr:
2022 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
2023 It updates it with the address and size of the microcode so that
2024 U-Boot can find it early on start-up.
2025 Entry_u_boot_dtb_with_ucode:
2026 Contains u-boot.dtb. It stores the microcode in a
2027 'self.ucode_data' property, which is then read by this class to
2028 obtain the microcode if needed. If collation is performed, it
2029 removes the microcode from the device tree.
2031 This class. If collation is enabled it reads the microcode from
2032 the Entry_u_boot_dtb_with_ucode entry, and uses it as the
2033 contents of this entry.
2037 .. _etype_u_boot_with_ucode_ptr:
2039 Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
2040 --------------------------------------------------------------------
2042 Properties / Entry arguments:
2043 - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
2044 - optional-ucode: boolean property to make microcode optional. If the
2045 u-boot.bin image does not include microcode, no error will
2048 See Entry_u_boot_ucode for full details of the three entries involved in
2049 this process. This entry updates U-Boot with the offset and size of the
2050 microcode, to allow early x86 boot code to find it without doing anything
2051 complicated. Otherwise it is the same as the u-boot entry.
2057 Entry: vblock: An entry which contains a Chromium OS verified boot block
2058 ------------------------------------------------------------------------
2060 Properties / Entry arguments:
2061 - content: List of phandles to entries to sign
2062 - keydir: Directory containing the public keys to use
2063 - keyblock: Name of the key file to use (inside keydir)
2064 - signprivate: Name of provide key file to use (inside keydir)
2065 - version: Version number of the vblock (typically 1)
2066 - kernelkey: Name of the kernel key to use (inside keydir)
2067 - preamble-flags: Value of the vboot preamble flags (typically 0)
2070 - input.<unique_name> - input file passed to futility
2071 - vblock.<unique_name> - output file generated by futility (which is
2072 used as the entry contents)
2074 Chromium OS signs the read-write firmware and kernel, writing the signature
2075 in this block. This allows U-Boot to verify that the next firmware stage
2076 and kernel are genuine.
2080 .. _etype_x86_reset16:
2082 Entry: x86-reset16: x86 16-bit reset code for U-Boot
2083 ----------------------------------------------------
2085 Properties / Entry arguments:
2086 - filename: Filename of u-boot-x86-reset16.bin (default
2087 'u-boot-x86-reset16.bin')
2089 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2090 must be placed at a particular address. This entry holds that code. It is
2091 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2092 for jumping to the x86-start16 code, which continues execution.
2094 For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
2098 .. _etype_x86_reset16_spl:
2100 Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
2101 --------------------------------------------------------
2103 Properties / Entry arguments:
2104 - filename: Filename of u-boot-x86-reset16.bin (default
2105 'u-boot-x86-reset16.bin')
2107 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2108 must be placed at a particular address. This entry holds that code. It is
2109 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2110 for jumping to the x86-start16 code, which continues execution.
2112 For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
2116 .. _etype_x86_reset16_tpl:
2118 Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
2119 --------------------------------------------------------
2121 Properties / Entry arguments:
2122 - filename: Filename of u-boot-x86-reset16.bin (default
2123 'u-boot-x86-reset16.bin')
2125 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2126 must be placed at a particular address. This entry holds that code. It is
2127 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2128 for jumping to the x86-start16 code, which continues execution.
2130 For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
2134 .. _etype_x86_start16:
2136 Entry: x86-start16: x86 16-bit start-up code for U-Boot
2137 -------------------------------------------------------
2139 Properties / Entry arguments:
2140 - filename: Filename of u-boot-x86-start16.bin (default
2141 'u-boot-x86-start16.bin')
2143 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2144 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2145 entry holds that code. It is typically placed at offset
2146 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2147 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2150 For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
2154 .. _etype_x86_start16_spl:
2156 Entry: x86-start16-spl: x86 16-bit start-up code for SPL
2157 --------------------------------------------------------
2159 Properties / Entry arguments:
2160 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
2161 'spl/u-boot-x86-start16-spl.bin')
2163 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2164 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2165 entry holds that code. It is typically placed at offset
2166 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2167 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2170 For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
2174 .. _etype_x86_start16_tpl:
2176 Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
2177 --------------------------------------------------------
2179 Properties / Entry arguments:
2180 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
2181 'tpl/u-boot-x86-start16-tpl.bin')
2183 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2184 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2185 entry holds that code. It is typically placed at offset
2186 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2187 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2190 If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
2191 may be used instead.