blob: 3dc32db8a542eb43fd379e3068577dac32aa7c13 [file] [log] [blame]
Simon Glass7a61c6b2018-07-17 13:25:37 -06001Binman Entry Documentation
2===========================
3
4This file describes the entry types supported by binman. These entry types can
5be placed in an image one by one to build up a final firmware image. It is
6fairly easy to create new entry types. Just add a new file to the 'etype'
7directory. You can use the existing entries as examples.
8
9Note that some entries are subclasses of others, using and extending their
10features to produce new behaviours.
11
12
13
Simon Glassa7c97782022-08-07 16:33:25 -060014.. _etype_atf_bl31:
15
Simon Glass8911fa12021-03-18 20:25:16 +130016Entry: atf-bl31: ARM Trusted Firmware (ATF) BL31 blob
17-----------------------------------------------------
Simon Glass559c4de2020-09-01 05:13:58 -060018
19Properties / Entry arguments:
20 - atf-bl31-path: Filename of file to read into entry. This is typically
21 called bl31.bin or bl31.elf
22
23This entry holds the run-time firmware, typically started by U-Boot SPL.
24See the U-Boot README for your architecture or board for how to use it. See
25https://github.com/ARM-software/arm-trusted-firmware for more information
26about ATF.
27
28
29
Simon Glassa7c97782022-08-07 16:33:25 -060030.. _etype_atf_fip:
31
Simon Glass3efb2972021-11-23 21:08:59 -070032Entry: atf-fip: ARM Trusted Firmware's Firmware Image Package (FIP)
33-------------------------------------------------------------------
34
35A FIP_ provides a way to group binaries in a firmware image, used by ARM's
36Trusted Firmware A (TF-A) code. It is a simple format consisting of a
37table of contents with information about the type, offset and size of the
38binaries in the FIP. It is quite similar to FMAP, with the major difference
39that it uses UUIDs to indicate the type of each entry.
40
41Note: It is recommended to always add an fdtmap to every image, as well as
42any FIPs so that binman and other tools can access the entire image
43correctly.
44
45The UUIDs correspond to useful names in `fiptool`, provided by ATF to
46operate on FIPs. Binman uses these names to make it easier to understand
47what is going on, although it is possible to provide a UUID if needed.
48
49The contents of the FIP are defined by subnodes of the atf-fip entry, e.g.::
50
51 atf-fip {
52 soc-fw {
53 filename = "bl31.bin";
54 };
55
56 scp-fwu-cfg {
57 filename = "bl2u.bin";
58 };
59
60 u-boot {
61 fip-type = "nt-fw";
62 };
63 };
64
65This describes a FIP with three entries: soc-fw, scp-fwu-cfg and nt-fw.
66You can use normal (non-external) binaries like U-Boot simply by adding a
67FIP type, with the `fip-type` property, as above.
68
69Since FIP exists to bring blobs together, Binman assumes that all FIP
70entries 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,
72even though it will not actually work.
73
74The size of the FIP depends on the size of the binaries. There is currently
75no way to specify a fixed size. If the `atf-fip` node has a `size` entry,
76this affects the space taken up by the `atf-fip` entry, but the FIP itself
77does not expand to use that space.
78
79Some other FIP features are available with Binman. The header and the
80entries have 64-bit flag works. The flag flags do not seem to be defined
81anywhere, but you can use `fip-hdr-flags` and fip-flags` to set the values
82of the header and entries respectively.
83
84FIP entries can be aligned to a particular power-of-two boundary. Use
85fip-align for this.
86
87Binman only understands the entry types that are included in its
88implementation. It is possible to specify a 16-byte UUID instead, using the
89fip-uuid property. In this case Binman doesn't know what its type is, so
90just uses the UUID. See the `u-boot` node in this example::
91
92 binman {
93 atf-fip {
94 fip-hdr-flags = /bits/ 64 <0x123>;
95 fip-align = <16>;
96 soc-fw {
97 fip-flags = /bits/ 64 <0x456>;
98 filename = "bl31.bin";
99 };
100
101 scp-fwu-cfg {
102 filename = "bl2u.bin";
103 };
104
105 u-boot {
106 fip-uuid = [fc 65 13 92 4a 5b 11 ec
107 94 35 ff 2d 1c fc 79 9c];
108 };
109 };
110 fdtmap {
111 };
112 };
113
114Binman allows reading and updating FIP entries after the image is created,
115provided that an FDPMAP is present too. Updates which change the size of a
116FIP entry will cause it to be expanded or contracted as needed.
117
118Properties for top-level atf-fip node
119~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120
121fip-hdr-flags (64 bits)
122 Sets the flags for the FIP header.
123
124Properties for subnodes
125~~~~~~~~~~~~~~~~~~~~~~~
126
127fip-type (str)
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).
131
132fip-uuid (16 bytes)
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.
136
137fip-flags (64 bits)
138 Set the flags for a FIP entry. Use in one of the subnodes of the
139 7atf-fip entry.
140
141fip-align
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.
144
145Adding new FIP-entry types
146~~~~~~~~~~~~~~~~~~~~~~~~~~
147
148When 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
150new types, then `send a patch`_ to the U-Boot mailing list. There are two
151source files that the tool examples:
152
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
155
156To run the tool::
157
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
161
162If it shows there is an update, it writes a new version of `fip_util.py`
163to `fip_util.py.out`. You can change the output file using the `-i` flag.
164If you have a problem, use `-D` to enable traceback debugging.
165
166FIP commentary
167~~~~~~~~~~~~~~
168
169As a side effect of use of UUIDs, FIP does not support multiple
170entries of the same type, such as might be used to store fonts or graphics
171icons, for example. For verified boot it could be used for each part of the
172image (e.g. separate FIPs for A and B) but cannot describe the whole
173firmware image. As with FMAP there is no hierarchy defined, although FMAP
174works around this by having 'section' areas which encompass others. A
175similar workaround would be possible with FIP but is not currently defined.
176
177It is recommended to always add an fdtmap to every image, as well as any
178FIPs so that binman and other tools can access the entire image correctly.
179
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
183
184
185
Simon Glassa7c97782022-08-07 16:33:25 -0600186.. _etype_blob:
187
Simon Glass8911fa12021-03-18 20:25:16 +1300188Entry: blob: Arbitrary binary blob
189----------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -0600190
191Note: This should not be used by itself. It is normally used as a parent
192class by other entry types.
193
194Properties / Entry arguments:
195 - filename: Filename of file to read into entry
Simon Glass7ba33592018-09-14 04:57:26 -0600196 - compress: Compression algorithm to use:
197 none: No compression
198 lz4: Use lz4 compression (via 'lz4' command-line utility)
Simon Glass7a61c6b2018-07-17 13:25:37 -0600199
200This entry reads data from a file and places it in the entry. The
201default filename is often specified specified by the subclass. See for
Simon Glass537e0062021-03-18 20:24:54 +1300202example the 'u-boot' entry which provides the filename 'u-boot.bin'.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600203
Simon Glass7ba33592018-09-14 04:57:26 -0600204If compression is enabled, an extra 'uncomp-size' property is written to
205the node (if enabled with -u) which provides the uncompressed size of the
206data.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600207
208
Simon Glass7a61c6b2018-07-17 13:25:37 -0600209
Simon Glassa7c97782022-08-07 16:33:25 -0600210.. _etype_blob_dtb:
211
Simon Glasse219aa42018-09-14 04:57:24 -0600212Entry: blob-dtb: A blob that holds a device tree
213------------------------------------------------
214
215This is a blob containing a device tree. The contents of the blob are
216obtained from the list of available device-tree files, managed by the
217'state' module.
218
Stefan Herbrechtsmeier11121d32022-08-19 16:25:25 +0200219Additional Properties / Entry arguments:
220 - prepend: Header type to use:
221 length: 32-bit length header
Simon Glasse219aa42018-09-14 04:57:24 -0600222
223
Simon Glassa7c97782022-08-07 16:33:25 -0600224.. _etype_blob_ext:
225
Simon Glass8911fa12021-03-18 20:25:16 +1300226Entry: blob-ext: Externally built binary blob
227---------------------------------------------
Simon Glass5e560182020-07-09 18:39:36 -0600228
229Note: This should not be used by itself. It is normally used as a parent
230class by other entry types.
231
Simon Glass5d94cc62020-07-09 18:39:38 -0600232If the file providing this blob is missing, binman can optionally ignore it
233and produce a broken image with a warning.
234
Simon Glass5e560182020-07-09 18:39:36 -0600235See 'blob' for Properties / Entry arguments.
236
237
238
Simon Glassa7c97782022-08-07 16:33:25 -0600239.. _etype_blob_ext_list:
240
Simon Glass0b00ae62021-11-23 21:09:52 -0700241Entry: blob-ext-list: List of externally built binary blobs
242-----------------------------------------------------------
243
244This is like blob-ext except that a number of blobs can be provided,
245typically with some sort of relationship, e.g. all are DDC parameters.
246
247If any of the external files needed by this llist is missing, binman can
248optionally ignore it and produce a broken image with a warning.
249
250Args:
251 filenames: List of filenames to read and include
252
253
Simon Glassa7c97782022-08-07 16:33:25 -0600254
255.. _etype_blob_named_by_arg:
Simon Glass0b00ae62021-11-23 21:09:52 -0700256
Simon Glassdb168d42018-07-17 13:25:39 -0600257Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass
258-----------------------------------------------------------------------------------------
259
260Properties / Entry arguments:
261 - <xxx>-path: Filename containing the contents of this entry (optional,
Simon Glass21db0ff2020-09-01 05:13:54 -0600262 defaults to None)
Simon Glassdb168d42018-07-17 13:25:39 -0600263
264where <xxx> is the blob_fname argument to the constructor.
265
266This entry cannot be used directly. Instead, it is used as a parent class
267for another entry, which defined blob_fname. This parameter is used to
268set the entry-arg or property containing the filename. The entry-arg or
269property is in turn used to set the actual filename.
270
271See cros_ec_rw for an example of this.
272
273
274
Simon Glassa7c97782022-08-07 16:33:25 -0600275.. _etype_blob_phase:
276
Simon Glass718b5292021-03-18 20:25:07 +1300277Entry: blob-phase: Section that holds a phase binary
278----------------------------------------------------
279
280This is a base class that should not normally be used directly. It is used
281when converting a 'u-boot' entry automatically into a 'u-boot-expanded'
282entry; similarly for SPL.
283
284
Simon Glassa7c97782022-08-07 16:33:25 -0600285
286.. _etype_cbfs:
Simon Glass718b5292021-03-18 20:25:07 +1300287
Simon Glass8911fa12021-03-18 20:25:16 +1300288Entry: cbfs: Coreboot Filesystem (CBFS)
289---------------------------------------
Simon Glass1de34482019-07-08 13:18:53 -0600290
291A CBFS provides a way to group files into a group. It has a simple directory
292structure and allows the position of individual files to be set, since it is
293designed to support execute-in-place in an x86 SPI-flash device. Where XIP
294is not used, it supports compression and storing ELF files.
295
296CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
297
Simon Glass0ac96b62021-03-18 20:25:15 +1300298The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::
Simon Glass1de34482019-07-08 13:18:53 -0600299
300 cbfs {
301 size = <0x100000>;
302 u-boot {
303 cbfs-type = "raw";
304 };
305 u-boot-dtb {
306 cbfs-type = "raw";
307 };
308 };
309
310This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb.
311Note that the size is required since binman does not support calculating it.
312The contents of each entry is just what binman would normally provide if it
313were not a CBFS node. A blob type can be used to import arbitrary files as
Simon Glass0ac96b62021-03-18 20:25:15 +1300314with the second subnode below::
Simon Glass1de34482019-07-08 13:18:53 -0600315
316 cbfs {
317 size = <0x100000>;
318 u-boot {
319 cbfs-name = "BOOT";
320 cbfs-type = "raw";
321 };
322
323 dtb {
324 type = "blob";
325 filename = "u-boot.dtb";
326 cbfs-type = "raw";
327 cbfs-compress = "lz4";
Simon Glassc2f1aed2019-07-08 13:18:56 -0600328 cbfs-offset = <0x100000>;
Simon Glass1de34482019-07-08 13:18:53 -0600329 };
330 };
331
332This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and
333u-boot.dtb (named "dtb") and compressed with the lz4 algorithm.
334
335
336Properties supported in the top-level CBFS node:
337
338cbfs-arch:
339 Defaults to "x86", but you can specify the architecture if needed.
340
341
342Properties supported in the CBFS entry subnodes:
343
344cbfs-name:
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
347 property.
348
349cbfs-type:
350 This is the CBFS file type. The following are supported:
351
352 raw:
353 This is a 'raw' file, although compression is supported. It can be
354 used to store any file in CBFS.
355
356 stage:
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'
Simon Glass0ac96b62021-03-18 20:25:15 +1300360 entry::
Simon Glass1de34482019-07-08 13:18:53 -0600361
362 cbfs {
363 size = <0x100000>;
364 u-boot-elf {
365 cbfs-name = "BOOT";
366 cbfs-type = "stage";
367 };
368 };
369
Simon Glass0ac96b62021-03-18 20:25:15 +1300370 You can use your own ELF file with something like::
Simon Glass1de34482019-07-08 13:18:53 -0600371
372 cbfs {
373 size = <0x100000>;
374 something {
375 type = "blob";
376 filename = "cbfs-stage.elf";
377 cbfs-type = "stage";
378 };
379 };
380
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.
386
Simon Glassc2f1aed2019-07-08 13:18:56 -0600387cbfs-offset:
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.
Simon Glass1de34482019-07-08 13:18:53 -0600396
397The current implementation supports only a subset of CBFS features. It does
398not 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
400particular offset in the CBFS and a few other things.
401
402Of course binman can create images containing multiple CBFSs, simply by
Simon Glass0ac96b62021-03-18 20:25:15 +1300403defining these in the binman config::
Simon Glass1de34482019-07-08 13:18:53 -0600404
405
406 binman {
407 size = <0x800000>;
408 cbfs {
409 offset = <0x100000>;
410 size = <0x100000>;
411 u-boot {
412 cbfs-type = "raw";
413 };
414 u-boot-dtb {
415 cbfs-type = "raw";
416 };
417 };
418
419 cbfs2 {
420 offset = <0x700000>;
421 size = <0x100000>;
422 u-boot {
423 cbfs-type = "raw";
424 };
425 u-boot-dtb {
426 cbfs-type = "raw";
427 };
428 image {
429 type = "blob";
430 filename = "image.jpg";
431 };
432 };
433 };
434
435This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB,
436both of size 1MB.
437
438
439
Simon Glassa7c97782022-08-07 16:33:25 -0600440.. _etype_collection:
441
Simon Glasse1915782021-03-21 18:24:31 +1300442Entry: collection: An entry which contains a collection of other entries
443------------------------------------------------------------------------
444
445Properties / Entry arguments:
446 - content: List of phandles to entries to include
447
448This allows reusing the contents of other entries. The contents of the
449listed entries are combined to form this entry. This serves as a useful
450base class for entry types which need to process data from elsewhere in
451the image, not necessarily child entries.
452
Simon Glassbd5cd882022-08-13 11:40:50 -0600453The entries can generally be anywhere in the same image, even if they are in
454a different section from this entry.
455
Simon Glasse1915782021-03-21 18:24:31 +1300456
457
Simon Glassa7c97782022-08-07 16:33:25 -0600458.. _etype_cros_ec_rw:
459
Simon Glassdb168d42018-07-17 13:25:39 -0600460Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image
461--------------------------------------------------------------------------------
462
463Properties / Entry arguments:
464 - cros-ec-rw-path: Filename containing the EC image
465
466This entry holds a Chromium OS EC (embedded controller) image, for use in
467updating the EC on startup via software sync.
468
469
470
Simon Glassa7c97782022-08-07 16:33:25 -0600471.. _etype_fdtmap:
472
Simon Glass0f621332019-07-08 14:25:27 -0600473Entry: fdtmap: An entry which contains an FDT map
474-------------------------------------------------
475
476Properties / Entry arguments:
477 None
478
479An FDT map is just a header followed by an FDT containing a list of all the
Simon Glassfb30e292019-07-20 12:23:51 -0600480entries in the image. The root node corresponds to the image node in the
481original FDT, and an image-name property indicates the image name in that
482original tree.
Simon Glass0f621332019-07-08 14:25:27 -0600483
484The header is the string _FDTMAP_ followed by 8 unused bytes.
485
486When used, this entry will be populated with an FDT map which reflects the
487entries in the current image. Hierarchy is preserved, and all offsets and
488sizes are included.
489
490Note that the -u option must be provided to ensure that binman updates the
491FDT with the position of each entry.
492
Simon Glass0ac96b62021-03-18 20:25:15 +1300493Example output for a simple image with U-Boot and an FDT map::
Simon Glass0f621332019-07-08 14:25:27 -0600494
Simon Glass0ac96b62021-03-18 20:25:15 +1300495 / {
496 image-name = "binman";
497 size = <0x00000112>;
Simon Glass0f621332019-07-08 14:25:27 -0600498 image-pos = <0x00000000>;
499 offset = <0x00000000>;
Simon Glass0ac96b62021-03-18 20:25:15 +1300500 u-boot {
501 size = <0x00000004>;
502 image-pos = <0x00000000>;
503 offset = <0x00000000>;
504 };
505 fdtmap {
506 size = <0x0000010e>;
507 image-pos = <0x00000004>;
508 offset = <0x00000004>;
509 };
Simon Glass0f621332019-07-08 14:25:27 -0600510 };
Simon Glass0f621332019-07-08 14:25:27 -0600511
Simon Glassfb30e292019-07-20 12:23:51 -0600512If allow-repack is used then 'orig-offset' and 'orig-size' properties are
513added as necessary. See the binman README.
514
Simon Glass637958f2021-11-23 21:09:50 -0700515When extracting files, an alternative 'fdt' format is available for fdtmaps.
516Use `binman extract -F fdt ...` to use this. It will export a devicetree,
517without the fdtmap header, so it can be viewed with `fdtdump`.
Simon Glass0f621332019-07-08 14:25:27 -0600518
519
Simon Glass637958f2021-11-23 21:09:50 -0700520
Simon Glassa7c97782022-08-07 16:33:25 -0600521.. _etype_files:
522
Simon Glass8911fa12021-03-18 20:25:16 +1300523Entry: files: A set of files arranged in a section
524--------------------------------------------------
Simon Glassac6328c2018-09-14 04:57:28 -0600525
526Properties / Entry arguments:
527 - pattern: Filename pattern to match the files to include
Simon Glass51d02ad2020-10-26 17:40:07 -0600528 - files-compress: Compression algorithm to use:
Simon Glassac6328c2018-09-14 04:57:28 -0600529 none: No compression
530 lz4: Use lz4 compression (via 'lz4' command-line utility)
Simon Glass3f093a32021-03-18 20:24:53 +1300531 - files-align: Align each file to the given alignment
Simon Glassac6328c2018-09-14 04:57:28 -0600532
533This entry reads a number of files and places each in a separate sub-entry
534within this entry. To access these you need to enable device-tree updates
535at run-time so you can obtain the file positions.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600536
537
Simon Glassac6328c2018-09-14 04:57:28 -0600538
Simon Glassa7c97782022-08-07 16:33:25 -0600539.. _etype_fill:
540
Simon Glass53f53992018-07-17 13:25:40 -0600541Entry: fill: An entry which is filled to a particular byte value
542----------------------------------------------------------------
543
544Properties / Entry arguments:
545 - fill-byte: Byte to use to fill the entry
546
547Note that the size property must be set since otherwise this entry does not
548know how large it should be.
549
550You can often achieve the same effect using the pad-byte property of the
551overall image, in that the space between entries will then be padded with
552that byte. But this entry is sometimes useful for explicitly setting the
553byte value of a region.
554
555
Simon Glassc7b010d2020-07-09 18:39:45 -0600556
Simon Glassa7c97782022-08-07 16:33:25 -0600557.. _etype_fit:
558
Simon Glass8911fa12021-03-18 20:25:16 +1300559Entry: fit: Flat Image Tree (FIT)
560---------------------------------
Simon Glass45d556d2020-07-09 18:39:45 -0600561
562This calls mkimage to create a FIT (U-Boot Flat Image Tree) based on the
563input provided.
564
565Nodes for the FIT should be written out in the binman configuration just as
566they would be in a file passed to mkimage.
567
Simon Glass0ac96b62021-03-18 20:25:15 +1300568For example, this creates an image containing a FIT with U-Boot SPL::
Simon Glass45d556d2020-07-09 18:39:45 -0600569
570 binman {
571 fit {
572 description = "Test FIT";
Simon Glassa435cd12020-09-01 05:13:59 -0600573 fit,fdt-list = "of-list";
Simon Glass45d556d2020-07-09 18:39:45 -0600574
575 images {
576 kernel@1 {
577 description = "SPL";
578 os = "u-boot";
579 type = "rkspi";
580 arch = "arm";
581 compression = "none";
582 load = <0>;
583 entry = <0>;
584
585 u-boot-spl {
586 };
587 };
588 };
589 };
590 };
591
Simon Glass912339f2022-02-08 11:50:03 -0700592More complex setups can be created, with generated nodes, as described
593below.
594
595Properties (in the 'fit' node itself)
596~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
597
598Special properties have a `fit,` prefix, indicating that they should be
599processed but not included in the final FIT.
600
601The top-level 'fit' node supports the following special properties:
602
603 fit,external-offset
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.
606
607 fit,fdt-list
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
611 to binman.
612
613Substitutions
614~~~~~~~~~~~~~
615
616Node names and property values support a basic string-substitution feature.
617Available substitutions for '@' nodes (and property values) are:
618
619SEQ:
620 Sequence number of the generated fdt (1, 2, ...)
621NAME
622 Name of the dtb as provided (i.e. without adding '.dtb')
623
624The `default` property, if present, will be automatically set to the name
625if of configuration whose devicetree matches the `default-dt` entry
626argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.
627
628Available substitutions for property values in these nodes are:
629
630DEFAULT-SEQ:
631 Sequence number of the default fdt, as provided by the 'default-dt'
632 entry argument
633
634Available operations
635~~~~~~~~~~~~~~~~~~~~
636
637You can add an operation to an '@' node to indicate which operation is
638required::
639
640 @fdt-SEQ {
641 fit,operation = "gen-fdt-nodes";
642 ...
643 };
644
645Available operations are:
646
647gen-fdt-nodes
648 Generate FDT nodes as above. This is the default if there is no
649 `fit,operation` property.
650
Simon Glass5f423422022-03-05 20:19:12 -0700651split-elf
652 Split an ELF file into a separate node for each segment.
653
Simon Glass912339f2022-02-08 11:50:03 -0700654Generating nodes from an FDT list (gen-fdt-nodes)
655~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
656
Simon Glassa435cd12020-09-01 05:13:59 -0600657U-Boot supports creating fdt and config nodes automatically. To do this,
Simon Glass9f1c6b92022-02-08 11:50:02 -0700658pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells
659binman 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.
Simon Glassa435cd12020-09-01 05:13:59 -0600662
Simon Glass0ac96b62021-03-18 20:25:15 +1300663Then add a 'generator node', a node with a name starting with '@'::
Simon Glassa435cd12020-09-01 05:13:59 -0600664
665 images {
666 @fdt-SEQ {
667 description = "fdt-NAME";
668 type = "flat_dt";
669 compression = "none";
670 };
671 };
672
Simon Glass9f1c6b92022-02-08 11:50:02 -0700673This tells binman to create nodes `fdt-1` and `fdt-2` for each of your two
Simon Glassa435cd12020-09-01 05:13:59 -0600674files. All the properties you specify will be included in the node. This
675node acts like a template to generate the nodes. The generator node itself
676does not appear in the output - it is replaced with what binman generates.
Simon Glass9f1c6b92022-02-08 11:50:02 -0700677A 'data' property is created with the contents of the FDT file.
Simon Glassa435cd12020-09-01 05:13:59 -0600678
Simon Glass0ac96b62021-03-18 20:25:15 +1300679You can create config nodes in a similar way::
Simon Glassa435cd12020-09-01 05:13:59 -0600680
681 configurations {
682 default = "@config-DEFAULT-SEQ";
683 @config-SEQ {
684 description = "NAME";
Samuel Holland91079ac2020-10-21 21:12:14 -0500685 firmware = "atf";
686 loadables = "uboot";
Simon Glassa435cd12020-09-01 05:13:59 -0600687 fdt = "fdt-SEQ";
688 };
689 };
690
Simon Glass9f1c6b92022-02-08 11:50:02 -0700691This tells binman to create nodes `config-1` and `config-2`, i.e. a config
692for each of your two files.
Simon Glassa435cd12020-09-01 05:13:59 -0600693
Simon Glassa435cd12020-09-01 05:13:59 -0600694Note that if no devicetree files are provided (with '-a of-list' as above)
695then no nodes will be generated.
696
Simon Glass5f423422022-03-05 20:19:12 -0700697Generating nodes from an ELF file (split-elf)
698~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
699
700This uses the node as a template to generate multiple nodes. The following
701special properties are available:
702
703split-elf
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:
707
708 fit,load
709 Generates a `load = <...>` property with the load address of the
710 segment
711
712 fit,entry
713 Generates a `entry = <...>` property with the entry address of the
714 ELF. This is only produced for the first entry
715
716 fit,data
717 Generates a `data = <...>` property with the contents of the segment
718
719 fit,loadables
720 Generates a `loadable = <...>` property with a list of the generated
721 nodes (including all nodes if this operation is used multiple times)
722
723
724Here is an example showing ATF, TEE and a device tree all combined::
725
726 fit {
727 description = "test-desc";
728 #address-cells = <1>;
729 fit,fdt-list = "of-list";
730
731 images {
732 u-boot {
733 description = "U-Boot (64-bit)";
734 type = "standalone";
735 os = "U-Boot";
736 arch = "arm64";
737 compression = "none";
Simon Glass72cc5382022-10-20 18:22:39 -0600738 load = <CONFIG_TEXT_BASE>;
Simon Glass5f423422022-03-05 20:19:12 -0700739 u-boot-nodtb {
740 };
741 };
742 @fdt-SEQ {
743 description = "fdt-NAME.dtb";
744 type = "flat_dt";
745 compression = "none";
746 };
747 @atf-SEQ {
748 fit,operation = "split-elf";
749 description = "ARM Trusted Firmware";
750 type = "firmware";
751 arch = "arm64";
752 os = "arm-trusted-firmware";
753 compression = "none";
754 fit,load;
755 fit,entry;
756 fit,data;
757
758 atf-bl31 {
759 };
760 };
761
762 @tee-SEQ {
763 fit,operation = "split-elf";
764 description = "TEE";
765 type = "tee";
766 arch = "arm64";
767 os = "tee";
768 compression = "none";
769 fit,load;
770 fit,entry;
771 fit,data;
772
773 tee-os {
774 };
775 };
776 };
777
778 configurations {
779 default = "@config-DEFAULT-SEQ";
780 @config-SEQ {
781 description = "conf-NAME.dtb";
782 fdt = "fdt-SEQ";
783 firmware = "u-boot";
784 fit,loadables;
785 };
786 };
787 };
788
789If ATF-BL31 is available, this generates a node for each segment in the
790ELF file, for example::
791
792 images {
793 atf-1 {
794 data = <...contents of first segment...>;
795 data-offset = <0x00000000>;
796 entry = <0x00040000>;
797 load = <0x00040000>;
798 compression = "none";
799 os = "arm-trusted-firmware";
800 arch = "arm64";
801 type = "firmware";
802 description = "ARM Trusted Firmware";
803 };
804 atf-2 {
805 data = <...contents of second segment...>;
806 load = <0xff3b0000>;
807 compression = "none";
808 os = "arm-trusted-firmware";
809 arch = "arm64";
810 type = "firmware";
811 description = "ARM Trusted Firmware";
812 };
813 };
814
815The same applies for OP-TEE if that is available.
816
817If each binary is not available, the relevant template node (@atf-SEQ or
818@tee-SEQ) is removed from the output.
819
820This also generates a `config-xxx` node for each device tree in `of-list`.
821Note that the U-Boot build system uses `-a of-list=$(CONFIG_OF_LIST)`
822so you can use `CONFIG_OF_LIST` to define that list. In this example it is
823set up for `firefly-rk3399` with a single device tree and the default set
824with `-a default-dt=$(CONFIG_DEFAULT_DEVICE_TREE)`, so the resulting output
825is::
826
827 configurations {
828 default = "config-1";
829 config-1 {
830 loadables = "atf-1", "atf-2", "atf-3", "tee-1", "tee-2";
831 description = "rk3399-firefly.dtb";
832 fdt = "fdt-1";
833 firmware = "u-boot";
834 };
835 };
836
837U-Boot SPL can then load the firmware (U-Boot proper) and all the loadables
838(ATF and TEE), then proceed with the boot.
839
Simon Glass45d556d2020-07-09 18:39:45 -0600840
Simon Glassa7c97782022-08-07 16:33:25 -0600841
842.. _etype_fmap:
Simon Glass45d556d2020-07-09 18:39:45 -0600843
Simon Glass7a61c6b2018-07-17 13:25:37 -0600844Entry: fmap: An entry which contains an Fmap section
845----------------------------------------------------
846
847Properties / Entry arguments:
848 None
849
850FMAP is a simple format used by flashrom, an open-source utility for
851reading and writing the SPI flash, typically on x86 CPUs. The format
852provides flashrom with a list of areas, so it knows what it in the flash.
853It can then read or write just a single area, instead of the whole flash.
854
855The format is defined by the flashrom project, in the file lib/fmap.h -
856see www.flashrom.org/Flashrom for more information.
857
858When used, this entry will be populated with an FMAP which reflects the
859entries in the current image. Note that any hierarchy is squashed, since
Simon Glassb1d414c2021-04-03 11:05:10 +1300860FMAP does not support this. Sections are represented as an area appearing
861before its contents, so that it is possible to reconstruct the hierarchy
862from the FMAP by using the offset information. This convention does not
863seem to be documented, but is used in Chromium OS.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600864
Simon Glassb1d414c2021-04-03 11:05:10 +1300865CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600866
867
Simon Glassb1d414c2021-04-03 11:05:10 +1300868
Simon Glassa7c97782022-08-07 16:33:25 -0600869.. _etype_gbb:
870
Simon Glassc1ae83c2018-07-17 13:25:44 -0600871Entry: gbb: An entry which contains a Chromium OS Google Binary Block
872---------------------------------------------------------------------
873
874Properties / 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
878
879Chromium OS uses a GBB to store various pieces of information, in particular
880the root and recovery keys that are used to verify the boot process. Some
881more details are here:
882
883 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
884
885but note that the page dates from 2013 so is quite out of date. See
886README.chromium for how to obtain the required keys and tools.
887
888
Simon Glassa7c97782022-08-07 16:33:25 -0600889
890.. _etype_image_header:
Simon Glassc1ae83c2018-07-17 13:25:44 -0600891
Simon Glasscec34ba2019-07-08 14:25:28 -0600892Entry: image-header: An entry which contains a pointer to the FDT map
893---------------------------------------------------------------------
894
895Properties / 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.
898
899This adds an 8-byte entry to the start or end of the image, pointing to the
900location of the FDT map. The format is a magic number followed by an offset
901from the start or end of the image, in twos-compliment format.
902
903This entry must be in the top-level part of the image.
904
905NOTE: If the location is at the start/end, you will probably need to specify
906sort-by-offset for the image, unless you actually put the image header
907first/last in the entry list.
908
909
910
Simon Glassa7c97782022-08-07 16:33:25 -0600911.. _etype_intel_cmc:
912
Simon Glass8911fa12021-03-18 20:25:16 +1300913Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
914-----------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -0600915
916Properties / Entry arguments:
917 - filename: Filename of file to read into entry
918
919This file contains microcode for some devices in a special format. An
920example filename is 'Microcode/C0_22211.BIN'.
921
922See README.x86 for information about x86 binary blobs.
923
924
925
Simon Glassa7c97782022-08-07 16:33:25 -0600926.. _etype_intel_descriptor:
927
Simon Glass7a61c6b2018-07-17 13:25:37 -0600928Entry: intel-descriptor: Intel flash descriptor block (4KB)
929-----------------------------------------------------------
930
931Properties / Entry arguments:
932 filename: Filename of file containing the descriptor. This is typically
933 a 4KB binary file, sometimes called 'descriptor.bin'
934
935This entry is placed at the start of flash and provides information about
936the SPI flash regions. In particular it provides the base address and
937size of the ME (Management Engine) region, allowing us to place the ME
938binary in the right place.
939
940With this entry in your image, the position of the 'intel-me' entry will be
941fixed in the image, which avoids you needed to specify an offset for that
942region. This is useful, because it is not possible to change the position
943of the ME region without updating the descriptor.
944
945See README.x86 for information about x86 binary blobs.
946
947
948
Simon Glassa7c97782022-08-07 16:33:25 -0600949.. _etype_intel_fit:
950
Simon Glass232f90c2019-08-24 07:22:50 -0600951Entry: intel-fit: Intel Firmware Image Table (FIT)
952--------------------------------------------------
953
954This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
955contains information about the firmware and microcode available in the
956image.
957
958At present binman only supports a basic FIT with no microcode.
959
960
961
Simon Glassa7c97782022-08-07 16:33:25 -0600962.. _etype_intel_fit_ptr:
963
Simon Glass232f90c2019-08-24 07:22:50 -0600964Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
965--------------------------------------------------------------
966
967This entry contains a pointer to the FIT. It is required to be at address
9680xffffffc0 in the image.
969
970
971
Simon Glassa7c97782022-08-07 16:33:25 -0600972.. _etype_intel_fsp:
973
Simon Glass8911fa12021-03-18 20:25:16 +1300974Entry: intel-fsp: Intel Firmware Support Package (FSP) file
975-----------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -0600976
977Properties / Entry arguments:
978 - filename: Filename of file to read into entry
979
980This file contains binary blobs which are used on some devices to make the
981platform work. U-Boot executes this code since it is not possible to set up
982the hardware using U-Boot open-source code. Documentation is typically not
983available in sufficient detail to allow this.
984
985An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
986
987See README.x86 for information about x86 binary blobs.
988
989
990
Simon Glassa7c97782022-08-07 16:33:25 -0600991.. _etype_intel_fsp_m:
992
Simon Glass8911fa12021-03-18 20:25:16 +1300993Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
994--------------------------------------------------------------------
Simon Glassba7985d2019-08-24 07:23:07 -0600995
996Properties / Entry arguments:
997 - filename: Filename of file to read into entry
998
999This file contains a binary blob which is used on some devices to set up
1000SDRAM. U-Boot executes this code in SPL so that it can make full use of
1001memory. Documentation is typically not available in sufficient detail to
1002allow U-Boot do this this itself..
1003
1004An example filename is 'fsp_m.bin'
1005
1006See README.x86 for information about x86 binary blobs.
1007
1008
Simon Glassa7c97782022-08-07 16:33:25 -06001009
1010.. _etype_intel_fsp_s:
Simon Glassba7985d2019-08-24 07:23:07 -06001011
Simon Glass8911fa12021-03-18 20:25:16 +13001012Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
1013---------------------------------------------------------------------
Simon Glass4d9086d2019-10-20 21:31:35 -06001014
1015Properties / Entry arguments:
1016 - filename: Filename of file to read into entry
1017
1018This file contains a binary blob which is used on some devices to set up
1019the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
1020running, so that it can make full use of memory. Documentation is typically
1021not available in sufficient detail to allow U-Boot do this this itself.
1022
1023An example filename is 'fsp_s.bin'
1024
1025See README.x86 for information about x86 binary blobs.
1026
1027
1028
Simon Glassa7c97782022-08-07 16:33:25 -06001029.. _etype_intel_fsp_t:
1030
Simon Glass8911fa12021-03-18 20:25:16 +13001031Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
1032----------------------------------------------------------------------
Simon Glass9ea87b22019-10-20 21:31:36 -06001033
1034Properties / Entry arguments:
1035 - filename: Filename of file to read into entry
1036
1037This file contains a binary blob which is used on some devices to set up
1038temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
1039that it has access to memory for its stack and initial storage.
1040
1041An example filename is 'fsp_t.bin'
1042
1043See README.x86 for information about x86 binary blobs.
1044
1045
Simon Glassa7c97782022-08-07 16:33:25 -06001046
1047.. _etype_intel_ifwi:
Simon Glass9ea87b22019-10-20 21:31:36 -06001048
Simon Glass8911fa12021-03-18 20:25:16 +13001049Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
1050--------------------------------------------------------------
Simon Glassc2f1aed2019-07-08 13:18:56 -06001051
1052Properties / 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
1055 tool
1056 - convert-fit: If present this indicates that the ifwitool should be
1057 used to convert the provided file into a IFWI.
1058
1059This file contains code and data used by the SoC that is required to make
1060it work. It includes U-Boot TPL, microcode, things related to the CSE
1061(Converged Security Engine, the microcontroller that loads all the firmware)
1062and other items beyond the wit of man.
1063
1064A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
1065file that will be converted to an IFWI.
1066
1067The position of this entry is generally set by the intel-descriptor entry.
1068
1069The contents of the IFWI are specified by the subnodes of the IFWI node.
1070Each subnode describes an entry which is placed into the IFWFI with a given
1071sub-partition (and optional entry name).
1072
Simon Glass8a5e2492019-08-24 07:22:47 -06001073Properties for subnodes:
Simon Glass0ac96b62021-03-18 20:25:15 +13001074 - 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.
Simon Glass8a5e2492019-08-24 07:22:47 -06001078
Simon Glassc2f1aed2019-07-08 13:18:56 -06001079See README.x86 for information about x86 binary blobs.
1080
1081
1082
Simon Glassa7c97782022-08-07 16:33:25 -06001083.. _etype_intel_me:
1084
Simon Glass8911fa12021-03-18 20:25:16 +13001085Entry: intel-me: Intel Management Engine (ME) file
1086--------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001087
1088Properties / Entry arguments:
1089 - filename: Filename of file to read into entry
1090
1091This file contains code used by the SoC that is required to make it work.
1092The Management Engine is like a background task that runs things that are
Thomas Hebbfd37f242019-11-13 18:18:03 -08001093not clearly documented, but may include keyboard, display and network
Simon Glass7a61c6b2018-07-17 13:25:37 -06001094access. For platform that use ME it is not possible to disable it. U-Boot
1095does not directly execute code in the ME binary.
1096
1097A typical filename is 'me.bin'.
1098
Simon Glassc4056b82019-07-08 13:18:38 -06001099The position of this entry is generally set by the intel-descriptor entry.
1100
Simon Glass7a61c6b2018-07-17 13:25:37 -06001101See README.x86 for information about x86 binary blobs.
1102
1103
1104
Simon Glassa7c97782022-08-07 16:33:25 -06001105.. _etype_intel_mrc:
1106
Simon Glass8911fa12021-03-18 20:25:16 +13001107Entry: intel-mrc: Intel Memory Reference Code (MRC) file
1108--------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001109
1110Properties / Entry arguments:
1111 - filename: Filename of file to read into entry
1112
1113This file contains code for setting up the SDRAM on some Intel systems. This
1114is executed by U-Boot when needed early during startup. A typical filename
1115is 'mrc.bin'.
1116
1117See README.x86 for information about x86 binary blobs.
1118
1119
1120
Simon Glassa7c97782022-08-07 16:33:25 -06001121.. _etype_intel_refcode:
1122
Simon Glass8911fa12021-03-18 20:25:16 +13001123Entry: intel-refcode: Intel Reference Code file
1124-----------------------------------------------
Simon Glass17b84eb2019-05-17 22:00:53 -06001125
1126Properties / Entry arguments:
1127 - filename: Filename of file to read into entry
1128
1129This file contains code for setting up the platform on some Intel systems.
1130This is executed by U-Boot when needed early during startup. A typical
1131filename is 'refcode.bin'.
1132
1133See README.x86 for information about x86 binary blobs.
1134
1135
1136
Simon Glassa7c97782022-08-07 16:33:25 -06001137.. _etype_intel_vbt:
1138
Simon Glass8911fa12021-03-18 20:25:16 +13001139Entry: intel-vbt: Intel Video BIOS Table (VBT) file
1140---------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001141
1142Properties / Entry arguments:
1143 - filename: Filename of file to read into entry
1144
1145This file contains code that sets up the integrated graphics subsystem on
1146some Intel SoCs. U-Boot executes this when the display is started up.
1147
1148See README.x86 for information about Intel binary blobs.
1149
1150
1151
Simon Glassa7c97782022-08-07 16:33:25 -06001152.. _etype_intel_vga:
1153
Simon Glass8911fa12021-03-18 20:25:16 +13001154Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
1155---------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001156
1157Properties / Entry arguments:
1158 - filename: Filename of file to read into entry
1159
1160This file contains code that sets up the integrated graphics subsystem on
1161some Intel SoCs. U-Boot executes this when the display is started up.
1162
1163This is similar to the VBT file but in a different format.
1164
1165See README.x86 for information about Intel binary blobs.
1166
1167
1168
Simon Glassa7c97782022-08-07 16:33:25 -06001169.. _etype_mkimage:
1170
Simon Glass8911fa12021-03-18 20:25:16 +13001171Entry: mkimage: Binary produced by mkimage
1172------------------------------------------
Simon Glass48f3aad2020-07-09 18:39:31 -06001173
1174Properties / Entry arguments:
Simon Glass42074dc2022-08-13 11:40:47 -06001175 - args: Arguments to pass
Simon Glass8fbca772022-08-13 11:40:48 -06001176 - data-to-imagename: Indicates that the -d data should be passed in as
1177 the image name also (-n)
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001178 - 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
Simon Glass48f3aad2020-07-09 18:39:31 -06001181
Simon Glass42074dc2022-08-13 11:40:47 -06001182The data passed to mkimage via the -d flag is collected from subnodes of the
1183mkimage node, e.g.::
Simon Glass48f3aad2020-07-09 18:39:31 -06001184
1185 mkimage {
1186 args = "-n test -T imximage";
1187
1188 u-boot-spl {
1189 };
1190 };
1191
Simon Glass42074dc2022-08-13 11:40:47 -06001192This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
1193file, which mkimage being called like this::
1194
1195 mkimage -d <data_file> -n test -T imximage <output_file>
1196
1197The output from mkimage then becomes part of the image produced by
1198binman. If you need to put mulitple things in the data file, you can use
1199a section, or just multiple subnodes like this::
1200
1201 mkimage {
1202 args = "-n test -T imximage";
1203
1204 u-boot-spl {
1205 };
1206
1207 u-boot-tpl {
1208 };
1209 };
Simon Glass48f3aad2020-07-09 18:39:31 -06001210
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001211To pass all datafiles untouched to mkimage::
1212
1213 mkimage {
1214 args = "-n rk3399 -T rkspi";
1215 multiple-data-files;
1216
1217 u-boot-tpl {
1218 };
1219
1220 u-boot-spl {
1221 };
1222 };
1223
1224This calls mkimage to create a Rockchip RK3399-specific first stage
1225bootloader, made of TPL+SPL. Since this first stage bootloader requires to
1226align the TPL and SPL but also some weird hacks that is handled by mkimage
1227directly, binman is told to not perform the concatenation of datafiles prior
1228to passing the data to mkimage.
1229
Simon Glass948dd3a2022-02-08 11:49:58 -07001230To use CONFIG options in the arguments, use a string list instead, as in
1231this example which also produces four arguments::
1232
1233 mkimage {
1234 args = "-n", CONFIG_SYS_SOC, "-T imximage";
1235
1236 u-boot-spl {
1237 };
1238 };
1239
Simon Glass8fbca772022-08-13 11:40:48 -06001240If you need to pass the input data in with the -n argument as well, then use
1241the 'data-to-imagename' property::
1242
1243 mkimage {
1244 args = "-T imximage";
1245 data-to-imagename';
1246
1247 u-boot-spl {
1248 };
1249 };
1250
1251That will pass the data to mkimage both as the data file (with -d) and as
1252the image name (with -n).
Simon Glass948dd3a2022-02-08 11:49:58 -07001253
Simon Glass48f3aad2020-07-09 18:39:31 -06001254
Simon Glassb1669752022-08-13 11:40:49 -06001255If need to pass different data in with -n, then use an imagename subnode::
1256
1257 mkimage {
1258 args = "-T imximage";
1259
1260 imagename {
1261 blob {
1262 filename = "spl/u-boot-spl.cfgout"
1263 };
1264 };
1265
1266 u-boot-spl {
1267 };
1268 };
1269
1270This will pass in u-boot-spl as the input data and the .cfgout file as the
1271-n data.
1272
Simon Glassa7c97782022-08-07 16:33:25 -06001273
1274.. _etype_opensbi:
Simon Glass48f3aad2020-07-09 18:39:31 -06001275
Bin Mengc0b15742021-05-10 20:23:33 +08001276Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
1277----------------------------------------------
1278
1279Properties / Entry arguments:
1280 - opensbi-path: Filename of file to read into entry. This is typically
1281 called fw_dynamic.bin
1282
1283This entry holds the run-time firmware, typically started by U-Boot SPL.
1284See the U-Boot README for your architecture or board for how to use it. See
1285https://github.com/riscv/opensbi for more information about OpenSBI.
1286
1287
1288
Simon Glassa7c97782022-08-07 16:33:25 -06001289.. _etype_powerpc_mpc85xx_bootpg_resetvec:
1290
Jagdish Gediya311d4842018-09-03 21:35:08 +05301291Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
1292-----------------------------------------------------------------------------------------
1293
1294Properties / Entry arguments:
1295 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
1296
Thomas Hebbfd37f242019-11-13 18:18:03 -08001297This entry is valid for PowerPC mpc85xx cpus. This entry holds
Jagdish Gediya311d4842018-09-03 21:35:08 +05301298'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
1299placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
1300
Simon Glass136dd352020-10-26 17:39:59 -06001301
Simon Glassa7c97782022-08-07 16:33:25 -06001302
1303.. _etype_pre_load:
Simon Glass136dd352020-10-26 17:39:59 -06001304
Philippe Reynesebe96cb2022-03-28 22:57:04 +02001305Entry: pre-load: Pre load image header
1306--------------------------------------
1307
1308Properties / Entry arguments:
Simon Glass9f571582022-08-13 11:40:43 -06001309 - pre-load-key-path: Path of the directory that store key (provided by
1310 the environment variable PRE_LOAD_KEY_PATH)
Philippe Reynesebe96cb2022-03-28 22:57:04 +02001311 - 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
1317
1318This entry creates a pre-load header that contains a global
1319image signature.
1320
1321For example, this creates an image with a pre-load header and a binary::
1322
1323 binman {
1324 image2 {
1325 filename = "sandbox.bin";
1326
1327 pre-load {
1328 content = <&image>;
1329 algo-name = "sha256,rsa2048";
1330 padding-name = "pss";
1331 key-name = "private.pem";
1332 header-size = <4096>;
1333 version = <1>;
1334 };
1335
1336 image: blob-ext {
1337 filename = "sandbox.itb";
1338 };
1339 };
1340 };
1341
1342
1343
Simon Glassa7c97782022-08-07 16:33:25 -06001344.. _etype_scp:
1345
Simon Glass8911fa12021-03-18 20:25:16 +13001346Entry: scp: System Control Processor (SCP) firmware blob
1347--------------------------------------------------------
Simon Glass136dd352020-10-26 17:39:59 -06001348
1349Properties / Entry arguments:
1350 - scp-path: Filename of file to read into the entry, typically scp.bin
1351
1352This entry holds firmware for an external platform-specific coprocessor.
Jagdish Gediya311d4842018-09-03 21:35:08 +05301353
1354
Simon Glass136dd352020-10-26 17:39:59 -06001355
Simon Glassa7c97782022-08-07 16:33:25 -06001356.. _etype_section:
1357
Simon Glass7a61c6b2018-07-17 13:25:37 -06001358Entry: section: Entry that contains other entries
1359-------------------------------------------------
1360
Simon Glasscc9a41c2021-11-23 11:03:49 -07001361A section is an entry which can contain other entries, thus allowing
1362hierarchical images to be created. See 'Sections and hierarchical images'
1363in the binman README for more information.
1364
1365The base implementation simply joins the various entries together, using
1366various rules about alignment, etc.
1367
1368Subclassing
1369~~~~~~~~~~~
1370
1371This class can be subclassed to support other file formats which hold
1372multiple entries, such as CBFS. To do this, override the following
1373functions. The documentation here describes what your function should do.
1374For example code, see etypes which subclass `Entry_section`, or `cbfs.py`
1375for a more involved example::
1376
1377 $ grep -l \(Entry_section tools/binman/etype/*.py
1378
1379ReadNode()
1380 Call `super().ReadNode()`, then read any special properties for the
1381 section. Then call `self.ReadEntries()` to read the entries.
1382
1383 Binman calls this at the start when reading the image description.
1384
1385ReadEntries()
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.
1391
1392 Binman calls this at the start when reading the image description.
1393
1394BuildSectionData(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.
1401
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.
1404
1405SetImagePos(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
1412 if possible.
Simon Glass0ac96b62021-03-18 20:25:15 +13001413
Simon Glasscc9a41c2021-11-23 11:03:49 -07001414 Binman calls this after the image has been packed, to update the
1415 location that all the entries ended up at.
Simon Glass0ac96b62021-03-18 20:25:15 +13001416
Simon Glass637958f2021-11-23 21:09:50 -07001417ReadChildData(child, decomp, alt_format):
Simon Glasscc9a41c2021-11-23 11:03:49 -07001418 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.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001424
Simon Glasscc9a41c2021-11-23 11:03:49 -07001425 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.
Simon Glass21db0ff2020-09-01 05:13:54 -06001429
Simon Glass637958f2021-11-23 21:09:50 -07001430 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'
1433 option.
1434
Simon Glasscc9a41c2021-11-23 11:03:49 -07001435 Binman calls this when reading in an image, in order to populate all the
1436 entries with the data from that image (`binman ls`).
1437
1438WriteChildData(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.
1441
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
1445 format.
1446
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`)
1449
1450Properties / Entry arguments
1451~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1452
1453See :ref:`develop/package/binman:Image description format` for more
1454information.
1455
1456align-default
1457 Default alignment for this section, if no alignment is given in the
1458 entry
1459
1460pad-byte
1461 Pad byte to use when padding
1462
1463sort-by-offset
1464 True if entries should be sorted by offset, False if they must be
1465 in-order in the device tree description
1466
1467end-at-4gb
1468 Used to build an x86 ROM which ends at 4GB (2^32)
1469
1470name-prefix
1471 Adds a prefix to the name of every entry in the section when writing out
1472 the map
1473
1474skip-at-start
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.
Simon Glassb1d414c2021-04-03 11:05:10 +13001480
Simon Glass39dd2152019-07-08 14:25:47 -06001481Since a section is also an entry, it inherits all the properies of entries
1482too.
1483
Simon Glasscc9a41c2021-11-23 11:03:49 -07001484Note that the `allow_missing` member controls whether this section permits
1485external blobs to be missing their contents. The option will produce an
1486image but of course it will not work. It is useful to make sure that
1487Continuous Integration systems can build without the binaries being
1488available. This is set by the `SetAllowMissing()` method, if
1489`--allow-missing` is passed to binman.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001490
1491
1492
Simon Glassa7c97782022-08-07 16:33:25 -06001493.. _etype_tee_os:
1494
Roger Quadros5cdcea02022-02-19 20:50:04 +02001495Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
1496---------------------------------------------------------------
1497
1498Properties / Entry arguments:
1499 - tee-os-path: Filename of file to read into entry. This is typically
1500 called tee-pager.bin
1501
1502This entry holds the run-time firmware, typically started by U-Boot SPL.
1503See the U-Boot README for your architecture or board for how to use it. See
1504https://github.com/OP-TEE/optee_os for more information about OP-TEE.
1505
1506
1507
Simon Glassa7c97782022-08-07 16:33:25 -06001508.. _etype_text:
1509
Simon Glass7a61c6b2018-07-17 13:25:37 -06001510Entry: text: An entry which contains text
1511-----------------------------------------
1512
1513The text can be provided either in the node itself or by a command-line
1514argument. There is a level of indirection to allow multiple text strings
1515and sharing of text.
1516
1517Properties / 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
1521 place in the entry.
Simon Glass47f6a622019-07-08 13:18:40 -06001522 <text>: The text to place in the entry (overrides the above mechanism).
1523 This is useful when the text is constant.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001524
Simon Glass0ac96b62021-03-18 20:25:15 +13001525Example node::
Simon Glass7a61c6b2018-07-17 13:25:37 -06001526
1527 text {
1528 size = <50>;
1529 text-label = "message";
1530 };
1531
1532You can then use:
1533
1534 binman -amessage="this is my message"
1535
1536and binman will insert that string into the entry.
1537
Simon Glass0ac96b62021-03-18 20:25:15 +13001538It is also possible to put the string directly in the node::
Simon Glass7a61c6b2018-07-17 13:25:37 -06001539
1540 text {
1541 size = <8>;
1542 text-label = "message";
1543 message = "a message directly in the node"
1544 };
1545
Simon Glass0ac96b62021-03-18 20:25:15 +13001546or just::
Simon Glass47f6a622019-07-08 13:18:40 -06001547
1548 text {
1549 size = <8>;
1550 text = "some text directly in the node"
1551 };
1552
Simon Glass7a61c6b2018-07-17 13:25:37 -06001553The text is not itself nul-terminated. This can be achieved, if required,
1554by setting the size of the entry to something larger than the text.
1555
1556
1557
Simon Glassa7c97782022-08-07 16:33:25 -06001558.. _etype_u_boot:
1559
Simon Glass7a61c6b2018-07-17 13:25:37 -06001560Entry: u-boot: U-Boot flat binary
1561---------------------------------
1562
1563Properties / Entry arguments:
1564 - filename: Filename of u-boot.bin (default 'u-boot.bin')
1565
1566This is the U-Boot binary, containing relocation information to allow it
1567to relocate itself at runtime. The binary typically includes a device tree
Simon Glass718b5292021-03-18 20:25:07 +13001568blob at the end of it.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001569
1570U-Boot can access binman symbols at runtime. See:
1571
1572 'Access to binman entry offsets at run time (fdt)'
1573
1574in the binman README for more information.
1575
Simon Glass718b5292021-03-18 20:25:07 +13001576Note that this entry is automatically replaced with u-boot-expanded unless
Simon Glass7098b7f2021-03-21 18:24:30 +13001577--no-expanded is used or the node has a 'no-expanded' property.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001578
1579
Simon Glass718b5292021-03-18 20:25:07 +13001580
Simon Glassa7c97782022-08-07 16:33:25 -06001581.. _etype_u_boot_dtb:
1582
Simon Glass7a61c6b2018-07-17 13:25:37 -06001583Entry: u-boot-dtb: U-Boot device tree
1584-------------------------------------
1585
1586Properties / Entry arguments:
1587 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1588
1589This is the U-Boot device tree, containing configuration information for
1590U-Boot. U-Boot needs this to know what devices are present and which drivers
1591to activate.
1592
Simon Glasse219aa42018-09-14 04:57:24 -06001593Note: This is mostly an internal entry type, used by others. This allows
1594binman to know which entries contain a device tree.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001595
1596
Simon Glassa7c97782022-08-07 16:33:25 -06001597
1598.. _etype_u_boot_dtb_with_ucode:
Simon Glass7a61c6b2018-07-17 13:25:37 -06001599
1600Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
1601-----------------------------------------------------------------------------------
1602
1603Properties / Entry arguments:
1604 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1605
1606See Entry_u_boot_ucode for full details of the three entries involved in
1607this process. This entry provides the U-Boot device-tree file, which
1608contains the microcode. If the microcode is not being collated into one
1609place then the offset and size of the microcode is recorded by this entry,
Simon Glass537e0062021-03-18 20:24:54 +13001610for use by u-boot-with-ucode_ptr. If it is being collated, then this
Simon Glass7a61c6b2018-07-17 13:25:37 -06001611entry deletes the microcode from the device tree (to save space) and makes
Simon Glass537e0062021-03-18 20:24:54 +13001612it available to u-boot-ucode.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001613
1614
1615
Simon Glassa7c97782022-08-07 16:33:25 -06001616.. _etype_u_boot_elf:
1617
Simon Glassb1714232018-09-14 04:57:35 -06001618Entry: u-boot-elf: U-Boot ELF image
1619-----------------------------------
1620
1621Properties / Entry arguments:
1622 - filename: Filename of u-boot (default 'u-boot')
1623
1624This is the U-Boot ELF image. It does not include a device tree but can be
1625relocated to any address for execution.
1626
1627
Simon Glassa7c97782022-08-07 16:33:25 -06001628
1629.. _etype_u_boot_env:
Simon Glassb1714232018-09-14 04:57:35 -06001630
Simon Glass136dd352020-10-26 17:39:59 -06001631Entry: u-boot-env: An entry which contains a U-Boot environment
1632---------------------------------------------------------------
1633
1634Properties / Entry arguments:
1635 - filename: File containing the environment text, with each line in the
1636 form var=value
1637
1638
Simon Glass718b5292021-03-18 20:25:07 +13001639
Simon Glassa7c97782022-08-07 16:33:25 -06001640.. _etype_u_boot_expanded:
1641
Simon Glass718b5292021-03-18 20:25:07 +13001642Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
1643------------------------------------------------------------------------------
1644
1645This is a section containing the U-Boot binary and a devicetree. Using this
1646entry type automatically creates this section, with the following entries
1647in it:
1648
1649 u-boot-nodtb
1650 u-boot-dtb
1651
1652Having the devicetree separate allows binman to update it in the final
1653image, so that the entries positions are provided to the running U-Boot.
1654
1655
Simon Glass136dd352020-10-26 17:39:59 -06001656
Simon Glassa7c97782022-08-07 16:33:25 -06001657.. _etype_u_boot_img:
1658
Simon Glass7a61c6b2018-07-17 13:25:37 -06001659Entry: u-boot-img: U-Boot legacy image
1660--------------------------------------
1661
1662Properties / Entry arguments:
1663 - filename: Filename of u-boot.img (default 'u-boot.img')
1664
1665This is the U-Boot binary as a packaged image, in legacy format. It has a
1666header which allows it to be loaded at the correct address for execution.
1667
1668You should use FIT (Flat Image Tree) instead of the legacy image for new
1669applications.
1670
1671
1672
Simon Glassa7c97782022-08-07 16:33:25 -06001673.. _etype_u_boot_nodtb:
1674
Simon Glass7a61c6b2018-07-17 13:25:37 -06001675Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
1676--------------------------------------------------------------------
1677
1678Properties / Entry arguments:
Simon Glass537e0062021-03-18 20:24:54 +13001679 - filename: Filename to include (default 'u-boot-nodtb.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06001680
1681This is the U-Boot binary, containing relocation information to allow it
1682to relocate itself at runtime. It does not include a device tree blob at
Simon Glass537e0062021-03-18 20:24:54 +13001683the end of it so normally cannot work without it. You can add a u-boot-dtb
Simon Glass718b5292021-03-18 20:25:07 +13001684entry after this one, or use a u-boot entry instead, normally expands to a
1685section containing u-boot and u-boot-dtb
Simon Glass7a61c6b2018-07-17 13:25:37 -06001686
1687
1688
Simon Glassa7c97782022-08-07 16:33:25 -06001689.. _etype_u_boot_spl:
1690
Simon Glass7a61c6b2018-07-17 13:25:37 -06001691Entry: u-boot-spl: U-Boot SPL binary
1692------------------------------------
1693
1694Properties / Entry arguments:
1695 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
1696
1697This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
1698binary which loads before U-Boot proper, typically into on-chip SRAM. It is
1699responsible for locating, loading and jumping to U-Boot. Note that SPL is
1700not relocatable so must be loaded to the correct address in SRAM, or written
Simon Glass8425a1f2018-07-17 13:25:48 -06001701to run from the correct address if direct flash execution is possible (e.g.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001702on x86 devices).
1703
1704SPL can access binman symbols at runtime. See:
1705
1706 'Access to binman entry offsets at run time (symbols)'
1707
1708in the binman README for more information.
1709
1710The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1711binman uses that to look up symbols to write into the SPL binary.
1712
Simon Glass718b5292021-03-18 20:25:07 +13001713Note that this entry is automatically replaced with u-boot-spl-expanded
Simon Glass7098b7f2021-03-21 18:24:30 +13001714unless --no-expanded is used or the node has a 'no-expanded' property.
Simon Glass718b5292021-03-18 20:25:07 +13001715
Simon Glass7a61c6b2018-07-17 13:25:37 -06001716
1717
Simon Glassa7c97782022-08-07 16:33:25 -06001718.. _etype_u_boot_spl_bss_pad:
1719
Simon Glass7a61c6b2018-07-17 13:25:37 -06001720Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
1721---------------------------------------------------------------------
1722
1723Properties / Entry arguments:
1724 None
1725
Simon Glass308939b2021-03-18 20:24:55 +13001726This holds the padding added after the SPL binary to cover the BSS (Block
1727Started by Symbol) region. This region holds the various variables used by
1728SPL. It is set to 0 by SPL when it starts up. If you want to append data to
1729the SPL image (such as a device tree file), you must pad out the BSS region
1730to avoid the data overlapping with U-Boot variables. This entry is useful in
1731that case. It automatically pads out the entry size to cover both the code,
1732data and BSS.
1733
1734The contents of this entry will a certain number of zero bytes, determined
1735by __bss_size
Simon Glass7a61c6b2018-07-17 13:25:37 -06001736
1737The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1738binman uses that to look up the BSS address.
1739
1740
1741
Simon Glassa7c97782022-08-07 16:33:25 -06001742.. _etype_u_boot_spl_dtb:
1743
Simon Glass7a61c6b2018-07-17 13:25:37 -06001744Entry: u-boot-spl-dtb: U-Boot SPL device tree
1745---------------------------------------------
1746
1747Properties / Entry arguments:
1748 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
1749
1750This is the SPL device tree, containing configuration information for
1751SPL. SPL needs this to know what devices are present and which drivers
1752to activate.
1753
1754
Simon Glassa7c97782022-08-07 16:33:25 -06001755
1756.. _etype_u_boot_spl_elf:
Simon Glass7a61c6b2018-07-17 13:25:37 -06001757
Simon Glassb1714232018-09-14 04:57:35 -06001758Entry: u-boot-spl-elf: U-Boot SPL ELF image
1759-------------------------------------------
1760
1761Properties / Entry arguments:
Simon Glass5dcc21d2019-07-08 13:18:45 -06001762 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
Simon Glassb1714232018-09-14 04:57:35 -06001763
1764This is the U-Boot SPL ELF image. It does not include a device tree but can
1765be relocated to any address for execution.
1766
Simon Glass718b5292021-03-18 20:25:07 +13001767
1768
Simon Glassa7c97782022-08-07 16:33:25 -06001769.. _etype_u_boot_spl_expanded:
1770
Simon Glass718b5292021-03-18 20:25:07 +13001771Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
1772--------------------------------------------------------------------------------------
1773
1774Properties / Entry arguments:
1775 - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
1776 select)
1777
1778This is a section containing the U-Boot binary, BSS padding if needed and a
1779devicetree. Using this entry type automatically creates this section, with
1780the following entries in it:
1781
1782 u-boot-spl-nodtb
1783 u-boot-spl-bss-pad
1784 u-boot-dtb
1785
1786Having the devicetree separate allows binman to update it in the final
1787image, so that the entries positions are provided to the running U-Boot.
1788
1789This entry is selected based on the value of the 'spl-dtb' entryarg. If
1790this is non-empty (and not 'n' or '0') then this expanded entry is selected.
Simon Glassb1714232018-09-14 04:57:35 -06001791
1792
Simon Glassa7c97782022-08-07 16:33:25 -06001793
1794.. _etype_u_boot_spl_nodtb:
Simon Glass718b5292021-03-18 20:25:07 +13001795
Simon Glass7a61c6b2018-07-17 13:25:37 -06001796Entry: u-boot-spl-nodtb: SPL binary without device tree appended
1797----------------------------------------------------------------
1798
1799Properties / Entry arguments:
Simon Glass537e0062021-03-18 20:24:54 +13001800 - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06001801
1802This is the U-Boot SPL binary, It does not include a device tree blob at
1803the end of it so may not be able to work without it, assuming SPL needs
Simon Glass537e0062021-03-18 20:24:54 +13001804a device tree to operate on your platform. You can add a u-boot-spl-dtb
Simon Glass718b5292021-03-18 20:25:07 +13001805entry after this one, or use a u-boot-spl entry instead' which normally
1806expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
1807u-boot-spl-dtb
Simon Glass7a61c6b2018-07-17 13:25:37 -06001808
Simon Glass31e04cb2021-03-18 20:24:56 +13001809SPL can access binman symbols at runtime. See:
1810
1811 'Access to binman entry offsets at run time (symbols)'
1812
1813in the binman README for more information.
1814
1815The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1816binman uses that to look up symbols to write into the SPL binary.
1817
Simon Glass7a61c6b2018-07-17 13:25:37 -06001818
1819
Simon Glassa7c97782022-08-07 16:33:25 -06001820.. _etype_u_boot_spl_with_ucode_ptr:
1821
Simon Glass7a61c6b2018-07-17 13:25:37 -06001822Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
1823----------------------------------------------------------------------------
1824
Simon Glass3fb4f422018-09-14 04:57:32 -06001825This is used when SPL must set up the microcode for U-Boot.
1826
Simon Glass7a61c6b2018-07-17 13:25:37 -06001827See Entry_u_boot_ucode for full details of the entries involved in this
1828process.
1829
1830
1831
Simon Glassa7c97782022-08-07 16:33:25 -06001832.. _etype_u_boot_tpl:
1833
Simon Glass8425a1f2018-07-17 13:25:48 -06001834Entry: u-boot-tpl: U-Boot TPL binary
1835------------------------------------
1836
1837Properties / Entry arguments:
1838 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
1839
1840This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
1841binary which loads before SPL, typically into on-chip SRAM. It is
1842responsible for locating, loading and jumping to SPL, the next-stage
1843loader. Note that SPL is not relocatable so must be loaded to the correct
1844address in SRAM, or written to run from the correct address if direct
1845flash execution is possible (e.g. on x86 devices).
1846
1847SPL can access binman symbols at runtime. See:
1848
1849 'Access to binman entry offsets at run time (symbols)'
1850
1851in the binman README for more information.
1852
1853The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1854binman uses that to look up symbols to write into the TPL binary.
1855
Simon Glass718b5292021-03-18 20:25:07 +13001856Note that this entry is automatically replaced with u-boot-tpl-expanded
Simon Glass7098b7f2021-03-21 18:24:30 +13001857unless --no-expanded is used or the node has a 'no-expanded' property.
Simon Glass718b5292021-03-18 20:25:07 +13001858
Simon Glass8425a1f2018-07-17 13:25:48 -06001859
1860
Simon Glassa7c97782022-08-07 16:33:25 -06001861.. _etype_u_boot_tpl_bss_pad:
1862
Simon Glass63f41d42021-03-18 20:24:58 +13001863Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
1864---------------------------------------------------------------------
1865
1866Properties / Entry arguments:
1867 None
1868
1869This holds the padding added after the TPL binary to cover the BSS (Block
1870Started by Symbol) region. This region holds the various variables used by
1871TPL. It is set to 0 by TPL when it starts up. If you want to append data to
1872the TPL image (such as a device tree file), you must pad out the BSS region
1873to avoid the data overlapping with U-Boot variables. This entry is useful in
1874that case. It automatically pads out the entry size to cover both the code,
1875data and BSS.
1876
1877The contents of this entry will a certain number of zero bytes, determined
1878by __bss_size
1879
1880The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1881binman uses that to look up the BSS address.
1882
1883
1884
Simon Glassa7c97782022-08-07 16:33:25 -06001885.. _etype_u_boot_tpl_dtb:
1886
Simon Glass8425a1f2018-07-17 13:25:48 -06001887Entry: u-boot-tpl-dtb: U-Boot TPL device tree
1888---------------------------------------------
1889
1890Properties / Entry arguments:
1891 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
1892
1893This is the TPL device tree, containing configuration information for
1894TPL. TPL needs this to know what devices are present and which drivers
1895to activate.
1896
1897
1898
Simon Glassa7c97782022-08-07 16:33:25 -06001899.. _etype_u_boot_tpl_dtb_with_ucode:
1900
Simon Glass3fb4f422018-09-14 04:57:32 -06001901Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
1902----------------------------------------------------------------------------
1903
1904This is used when TPL must set up the microcode for U-Boot.
1905
1906See Entry_u_boot_ucode for full details of the entries involved in this
1907process.
1908
1909
1910
Simon Glassa7c97782022-08-07 16:33:25 -06001911.. _etype_u_boot_tpl_elf:
1912
Simon Glassa899f712019-07-08 13:18:46 -06001913Entry: u-boot-tpl-elf: U-Boot TPL ELF image
1914-------------------------------------------
1915
1916Properties / Entry arguments:
1917 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
1918
1919This is the U-Boot TPL ELF image. It does not include a device tree but can
1920be relocated to any address for execution.
1921
1922
Simon Glassa7c97782022-08-07 16:33:25 -06001923
1924.. _etype_u_boot_tpl_expanded:
Simon Glassa899f712019-07-08 13:18:46 -06001925
Simon Glass718b5292021-03-18 20:25:07 +13001926Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
1927--------------------------------------------------------------------------------------
1928
1929Properties / Entry arguments:
1930 - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
1931 select)
1932
1933This is a section containing the U-Boot binary, BSS padding if needed and a
1934devicetree. Using this entry type automatically creates this section, with
1935the following entries in it:
1936
1937 u-boot-tpl-nodtb
1938 u-boot-tpl-bss-pad
1939 u-boot-dtb
1940
1941Having the devicetree separate allows binman to update it in the final
1942image, so that the entries positions are provided to the running U-Boot.
1943
1944This entry is selected based on the value of the 'tpl-dtb' entryarg. If
1945this is non-empty (and not 'n' or '0') then this expanded entry is selected.
1946
1947
1948
Simon Glassa7c97782022-08-07 16:33:25 -06001949.. _etype_u_boot_tpl_nodtb:
1950
Simon Glassc98de972021-03-18 20:24:57 +13001951Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
1952----------------------------------------------------------------
1953
1954Properties / Entry arguments:
1955 - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin')
1956
1957This is the U-Boot TPL binary, It does not include a device tree blob at
1958the end of it so may not be able to work without it, assuming TPL needs
1959a device tree to operate on your platform. You can add a u-boot-tpl-dtb
Simon Glass718b5292021-03-18 20:25:07 +13001960entry after this one, or use a u-boot-tpl entry instead, which normally
1961expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
1962u-boot-tpl-dtb
Simon Glassc98de972021-03-18 20:24:57 +13001963
1964TPL can access binman symbols at runtime. See:
1965
1966 'Access to binman entry offsets at run time (symbols)'
1967
1968in the binman README for more information.
1969
1970The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1971binman uses that to look up symbols to write into the TPL binary.
1972
1973
Simon Glassa7c97782022-08-07 16:33:25 -06001974
1975.. _etype_u_boot_tpl_with_ucode_ptr:
Simon Glassc98de972021-03-18 20:24:57 +13001976
Simon Glass3fb4f422018-09-14 04:57:32 -06001977Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
1978----------------------------------------------------------------------------
1979
1980See Entry_u_boot_ucode for full details of the entries involved in this
1981process.
1982
1983
1984
Simon Glassa7c97782022-08-07 16:33:25 -06001985.. _etype_u_boot_ucode:
1986
Simon Glass7a61c6b2018-07-17 13:25:37 -06001987Entry: u-boot-ucode: U-Boot microcode block
1988-------------------------------------------
1989
1990Properties / Entry arguments:
1991 None
1992
1993The contents of this entry are filled in automatically by other entries
1994which must also be in the image.
1995
1996U-Boot on x86 needs a single block of microcode. This is collected from
1997the various microcode update nodes in the device tree. It is also unable
1998to read the microcode from the device tree on platforms that use FSP
1999(Firmware Support Package) binaries, because the API requires that the
2000microcode is supplied before there is any SRAM available to use (i.e.
2001the FSP sets up the SRAM / cache-as-RAM but does so in the call that
2002requires the microcode!). To keep things simple, all x86 platforms handle
2003microcode the same way in U-Boot (even non-FSP platforms). This is that
2004a table is placed at _dt_ucode_base_size containing the base address and
2005size of the microcode. This is either passed to the FSP (for FSP
2006platforms), or used to set up the microcode (for non-FSP platforms).
2007This all happens in the build system since it is the only way to get
2008the microcode into a single blob and accessible without SRAM.
2009
2010There are two cases to handle. If there is only one microcode blob in
2011the device tree, then the ucode pointer it set to point to that. This
2012entry (u-boot-ucode) is empty. If there is more than one update, then
2013this entry holds the concatenation of all updates, and the device tree
2014entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
2015last step ensures that that the microcode appears in one contiguous
2016block in the image and is not unnecessarily duplicated in the device
2017tree. It is referred to as 'collation' here.
2018
2019Entry types that have a part to play in handling microcode:
2020
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.
2030 Entry_u_boot_ucode:
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.
2034
2035
2036
Simon Glassa7c97782022-08-07 16:33:25 -06002037.. _etype_u_boot_with_ucode_ptr:
2038
Simon Glass7a61c6b2018-07-17 13:25:37 -06002039Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
2040--------------------------------------------------------------------
2041
2042Properties / Entry arguments:
Masahiro Yamadaa7a0ca42019-12-14 13:47:26 +09002043 - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
Simon Glassee21d3a2018-09-14 04:57:07 -06002044 - optional-ucode: boolean property to make microcode optional. If the
2045 u-boot.bin image does not include microcode, no error will
2046 be generated.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002047
2048See Entry_u_boot_ucode for full details of the three entries involved in
2049this process. This entry updates U-Boot with the offset and size of the
2050microcode, to allow early x86 boot code to find it without doing anything
Simon Glass537e0062021-03-18 20:24:54 +13002051complicated. Otherwise it is the same as the u-boot entry.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002052
2053
2054
Simon Glassa7c97782022-08-07 16:33:25 -06002055.. _etype_vblock:
2056
Simon Glass5c350162018-07-17 13:25:47 -06002057Entry: vblock: An entry which contains a Chromium OS verified boot block
2058------------------------------------------------------------------------
2059
2060Properties / Entry arguments:
Simon Glass17b84eb2019-05-17 22:00:53 -06002061 - content: List of phandles to entries to sign
Simon Glass5c350162018-07-17 13:25:47 -06002062 - 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)
2068
Simon Glass639505b2018-09-14 04:57:11 -06002069Output files:
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)
2073
Jagdish Gediya311d4842018-09-03 21:35:08 +05302074Chromium OS signs the read-write firmware and kernel, writing the signature
Simon Glass5c350162018-07-17 13:25:47 -06002075in this block. This allows U-Boot to verify that the next firmware stage
2076and kernel are genuine.
2077
2078
2079
Simon Glassa7c97782022-08-07 16:33:25 -06002080.. _etype_x86_reset16:
2081
Simon Glass0b074d62019-08-24 07:22:48 -06002082Entry: x86-reset16: x86 16-bit reset code for U-Boot
2083----------------------------------------------------
2084
2085Properties / Entry arguments:
2086 - filename: Filename of u-boot-x86-reset16.bin (default
2087 'u-boot-x86-reset16.bin')
2088
2089x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2090must be placed at a particular address. This entry holds that code. It is
2091typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2092for jumping to the x86-start16 code, which continues execution.
2093
2094For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
2095
2096
2097
Simon Glassa7c97782022-08-07 16:33:25 -06002098.. _etype_x86_reset16_spl:
2099
Simon Glass0b074d62019-08-24 07:22:48 -06002100Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
2101--------------------------------------------------------
2102
2103Properties / Entry arguments:
2104 - filename: Filename of u-boot-x86-reset16.bin (default
2105 'u-boot-x86-reset16.bin')
2106
2107x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2108must be placed at a particular address. This entry holds that code. It is
2109typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2110for jumping to the x86-start16 code, which continues execution.
2111
2112For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
2113
2114
2115
Simon Glassa7c97782022-08-07 16:33:25 -06002116.. _etype_x86_reset16_tpl:
2117
Simon Glass0b074d62019-08-24 07:22:48 -06002118Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
2119--------------------------------------------------------
2120
2121Properties / Entry arguments:
2122 - filename: Filename of u-boot-x86-reset16.bin (default
2123 'u-boot-x86-reset16.bin')
2124
2125x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2126must be placed at a particular address. This entry holds that code. It is
2127typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2128for jumping to the x86-start16 code, which continues execution.
2129
2130For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
2131
2132
Simon Glassa7c97782022-08-07 16:33:25 -06002133
2134.. _etype_x86_start16:
Simon Glass0b074d62019-08-24 07:22:48 -06002135
Simon Glass7a61c6b2018-07-17 13:25:37 -06002136Entry: x86-start16: x86 16-bit start-up code for U-Boot
2137-------------------------------------------------------
2138
2139Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002140 - filename: Filename of u-boot-x86-start16.bin (default
2141 'u-boot-x86-start16.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002142
2143x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
Simon Glassabab18c2019-08-24 07:22:49 -06002144must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2145entry holds that code. It is typically placed at offset
2146CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2147and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2148U-Boot).
Simon Glass7a61c6b2018-07-17 13:25:37 -06002149
2150For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
2151
2152
2153
Simon Glassa7c97782022-08-07 16:33:25 -06002154.. _etype_x86_start16_spl:
2155
Simon Glass7a61c6b2018-07-17 13:25:37 -06002156Entry: x86-start16-spl: x86 16-bit start-up code for SPL
2157--------------------------------------------------------
2158
2159Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002160 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
2161 'spl/u-boot-x86-start16-spl.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002162
Simon Glassabab18c2019-08-24 07:22:49 -06002163x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2164must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2165entry holds that code. It is typically placed at offset
2166CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2167and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2168U-Boot).
Simon Glass7a61c6b2018-07-17 13:25:37 -06002169
Simon Glassabab18c2019-08-24 07:22:49 -06002170For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002171
2172
2173
Simon Glassa7c97782022-08-07 16:33:25 -06002174.. _etype_x86_start16_tpl:
2175
Simon Glassed40e962018-09-14 04:57:10 -06002176Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
2177--------------------------------------------------------
2178
2179Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002180 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
2181 'tpl/u-boot-x86-start16-tpl.bin')
Simon Glassed40e962018-09-14 04:57:10 -06002182
Simon Glassabab18c2019-08-24 07:22:49 -06002183x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2184must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2185entry holds that code. It is typically placed at offset
2186CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2187and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2188U-Boot).
Simon Glassed40e962018-09-14 04:57:10 -06002189
Simon Glassabab18c2019-08-24 07:22:49 -06002190If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
Simon Glassed40e962018-09-14 04:57:10 -06002191may be used instead.
2192
2193
2194