blob: 7a04a613992da6615949af28a73c0cf1b4aa3460 [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
Simon Glassda6a9082023-01-07 14:07:10 -0700219Additional attributes:
220 prepend: Header used (e.g. 'length')
Simon Glasse219aa42018-09-14 04:57:24 -0600221
222
Simon Glassda6a9082023-01-07 14:07:10 -0700223
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
Jonas Karlmanc59ea892023-01-21 19:01:39 +0000607 fit,align
608 Indicates what alignment to use for the FIT and its external data,
609 and provides the alignment to use. This is passed to mkimage via
610 the -B flag.
611
Simon Glass912339f2022-02-08 11:50:03 -0700612 fit,fdt-list
613 Indicates the entry argument which provides the list of device tree
614 files for the gen-fdt-nodes operation (as below). This is often
615 `of-list` meaning that `-a of-list="dtb1 dtb2..."` should be passed
616 to binman.
617
618Substitutions
619~~~~~~~~~~~~~
620
621Node names and property values support a basic string-substitution feature.
622Available substitutions for '@' nodes (and property values) are:
623
624SEQ:
625 Sequence number of the generated fdt (1, 2, ...)
626NAME
627 Name of the dtb as provided (i.e. without adding '.dtb')
628
629The `default` property, if present, will be automatically set to the name
630if of configuration whose devicetree matches the `default-dt` entry
631argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.
632
633Available substitutions for property values in these nodes are:
634
635DEFAULT-SEQ:
636 Sequence number of the default fdt, as provided by the 'default-dt'
637 entry argument
638
639Available operations
640~~~~~~~~~~~~~~~~~~~~
641
642You can add an operation to an '@' node to indicate which operation is
643required::
644
645 @fdt-SEQ {
646 fit,operation = "gen-fdt-nodes";
647 ...
648 };
649
650Available operations are:
651
652gen-fdt-nodes
653 Generate FDT nodes as above. This is the default if there is no
654 `fit,operation` property.
655
Simon Glass5f423422022-03-05 20:19:12 -0700656split-elf
657 Split an ELF file into a separate node for each segment.
658
Simon Glass912339f2022-02-08 11:50:03 -0700659Generating nodes from an FDT list (gen-fdt-nodes)
660~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
661
Simon Glassa435cd12020-09-01 05:13:59 -0600662U-Boot supports creating fdt and config nodes automatically. To do this,
Simon Glass9f1c6b92022-02-08 11:50:02 -0700663pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells
664binman that you want to generates nodes for two files: `file1.dtb` and
665`file2.dtb`. The `fit,fdt-list` property (see above) indicates that
666`of-list` should be used. If the property is missing you will get an error.
Simon Glassa435cd12020-09-01 05:13:59 -0600667
Simon Glass0ac96b62021-03-18 20:25:15 +1300668Then add a 'generator node', a node with a name starting with '@'::
Simon Glassa435cd12020-09-01 05:13:59 -0600669
670 images {
671 @fdt-SEQ {
672 description = "fdt-NAME";
673 type = "flat_dt";
674 compression = "none";
675 };
676 };
677
Simon Glass9f1c6b92022-02-08 11:50:02 -0700678This tells binman to create nodes `fdt-1` and `fdt-2` for each of your two
Simon Glassa435cd12020-09-01 05:13:59 -0600679files. All the properties you specify will be included in the node. This
680node acts like a template to generate the nodes. The generator node itself
681does not appear in the output - it is replaced with what binman generates.
Simon Glass9f1c6b92022-02-08 11:50:02 -0700682A 'data' property is created with the contents of the FDT file.
Simon Glassa435cd12020-09-01 05:13:59 -0600683
Simon Glass0ac96b62021-03-18 20:25:15 +1300684You can create config nodes in a similar way::
Simon Glassa435cd12020-09-01 05:13:59 -0600685
686 configurations {
687 default = "@config-DEFAULT-SEQ";
688 @config-SEQ {
689 description = "NAME";
Samuel Holland91079ac2020-10-21 21:12:14 -0500690 firmware = "atf";
691 loadables = "uboot";
Simon Glassa435cd12020-09-01 05:13:59 -0600692 fdt = "fdt-SEQ";
693 };
694 };
695
Simon Glass9f1c6b92022-02-08 11:50:02 -0700696This tells binman to create nodes `config-1` and `config-2`, i.e. a config
697for each of your two files.
Simon Glassa435cd12020-09-01 05:13:59 -0600698
Simon Glassa435cd12020-09-01 05:13:59 -0600699Note that if no devicetree files are provided (with '-a of-list' as above)
700then no nodes will be generated.
701
Simon Glass5f423422022-03-05 20:19:12 -0700702Generating nodes from an ELF file (split-elf)
703~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
704
705This uses the node as a template to generate multiple nodes. The following
706special properties are available:
707
708split-elf
709 Split an ELF file into a separate node for each segment. This uses the
710 node as a template to generate multiple nodes. The following special
711 properties are available:
712
713 fit,load
714 Generates a `load = <...>` property with the load address of the
715 segment
716
717 fit,entry
718 Generates a `entry = <...>` property with the entry address of the
719 ELF. This is only produced for the first entry
720
721 fit,data
722 Generates a `data = <...>` property with the contents of the segment
723
Jonas Karlman490f73c2023-01-21 19:02:12 +0000724 fit,firmware
725 Generates a `firmware = <...>` property. Provides a list of possible
726 nodes to be used as the `firmware` property value. The first valid
727 node is picked as the firmware. Any remaining valid nodes is
728 prepended to the `loadable` property generated by `fit,loadables`
729
Simon Glass5f423422022-03-05 20:19:12 -0700730 fit,loadables
731 Generates a `loadable = <...>` property with a list of the generated
732 nodes (including all nodes if this operation is used multiple times)
733
734
735Here is an example showing ATF, TEE and a device tree all combined::
736
737 fit {
738 description = "test-desc";
739 #address-cells = <1>;
740 fit,fdt-list = "of-list";
741
742 images {
743 u-boot {
744 description = "U-Boot (64-bit)";
745 type = "standalone";
746 os = "U-Boot";
747 arch = "arm64";
748 compression = "none";
Simon Glass72cc5382022-10-20 18:22:39 -0600749 load = <CONFIG_TEXT_BASE>;
Simon Glass5f423422022-03-05 20:19:12 -0700750 u-boot-nodtb {
751 };
752 };
753 @fdt-SEQ {
754 description = "fdt-NAME.dtb";
755 type = "flat_dt";
756 compression = "none";
757 };
758 @atf-SEQ {
759 fit,operation = "split-elf";
760 description = "ARM Trusted Firmware";
761 type = "firmware";
762 arch = "arm64";
763 os = "arm-trusted-firmware";
764 compression = "none";
765 fit,load;
766 fit,entry;
767 fit,data;
768
769 atf-bl31 {
770 };
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000771 hash {
772 algo = "sha256";
773 };
Simon Glass5f423422022-03-05 20:19:12 -0700774 };
775
776 @tee-SEQ {
777 fit,operation = "split-elf";
778 description = "TEE";
779 type = "tee";
780 arch = "arm64";
781 os = "tee";
782 compression = "none";
783 fit,load;
784 fit,entry;
785 fit,data;
786
787 tee-os {
788 };
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000789 hash {
790 algo = "sha256";
791 };
Simon Glass5f423422022-03-05 20:19:12 -0700792 };
793 };
794
795 configurations {
796 default = "@config-DEFAULT-SEQ";
797 @config-SEQ {
798 description = "conf-NAME.dtb";
799 fdt = "fdt-SEQ";
Jonas Karlman490f73c2023-01-21 19:02:12 +0000800 fit,firmware = "atf-1", "u-boot";
Simon Glass5f423422022-03-05 20:19:12 -0700801 fit,loadables;
802 };
803 };
804 };
805
806If ATF-BL31 is available, this generates a node for each segment in the
807ELF file, for example::
808
809 images {
810 atf-1 {
811 data = <...contents of first segment...>;
812 data-offset = <0x00000000>;
813 entry = <0x00040000>;
814 load = <0x00040000>;
815 compression = "none";
816 os = "arm-trusted-firmware";
817 arch = "arm64";
818 type = "firmware";
819 description = "ARM Trusted Firmware";
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000820 hash {
821 algo = "sha256";
822 value = <...hash of first segment...>;
823 };
Simon Glass5f423422022-03-05 20:19:12 -0700824 };
825 atf-2 {
826 data = <...contents of second segment...>;
827 load = <0xff3b0000>;
828 compression = "none";
829 os = "arm-trusted-firmware";
830 arch = "arm64";
831 type = "firmware";
832 description = "ARM Trusted Firmware";
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000833 hash {
834 algo = "sha256";
835 value = <...hash of second segment...>;
836 };
Simon Glass5f423422022-03-05 20:19:12 -0700837 };
838 };
839
840The same applies for OP-TEE if that is available.
841
842If each binary is not available, the relevant template node (@atf-SEQ or
843@tee-SEQ) is removed from the output.
844
845This also generates a `config-xxx` node for each device tree in `of-list`.
846Note that the U-Boot build system uses `-a of-list=$(CONFIG_OF_LIST)`
847so you can use `CONFIG_OF_LIST` to define that list. In this example it is
848set up for `firefly-rk3399` with a single device tree and the default set
849with `-a default-dt=$(CONFIG_DEFAULT_DEVICE_TREE)`, so the resulting output
850is::
851
852 configurations {
853 default = "config-1";
854 config-1 {
Jonas Karlman490f73c2023-01-21 19:02:12 +0000855 loadables = "u-boot", "atf-2", "atf-3", "tee-1", "tee-2";
Simon Glass5f423422022-03-05 20:19:12 -0700856 description = "rk3399-firefly.dtb";
857 fdt = "fdt-1";
Jonas Karlman490f73c2023-01-21 19:02:12 +0000858 firmware = "atf-1";
Simon Glass5f423422022-03-05 20:19:12 -0700859 };
860 };
861
Jonas Karlman490f73c2023-01-21 19:02:12 +0000862U-Boot SPL can then load the firmware (ATF) and all the loadables (U-Boot
863proper, ATF and TEE), then proceed with the boot.
Simon Glass5f423422022-03-05 20:19:12 -0700864
Simon Glass45d556d2020-07-09 18:39:45 -0600865
Simon Glassa7c97782022-08-07 16:33:25 -0600866
867.. _etype_fmap:
Simon Glass45d556d2020-07-09 18:39:45 -0600868
Simon Glass7a61c6b2018-07-17 13:25:37 -0600869Entry: fmap: An entry which contains an Fmap section
870----------------------------------------------------
871
872Properties / Entry arguments:
873 None
874
875FMAP is a simple format used by flashrom, an open-source utility for
876reading and writing the SPI flash, typically on x86 CPUs. The format
877provides flashrom with a list of areas, so it knows what it in the flash.
878It can then read or write just a single area, instead of the whole flash.
879
880The format is defined by the flashrom project, in the file lib/fmap.h -
881see www.flashrom.org/Flashrom for more information.
882
883When used, this entry will be populated with an FMAP which reflects the
884entries in the current image. Note that any hierarchy is squashed, since
Simon Glassb1d414c2021-04-03 11:05:10 +1300885FMAP does not support this. Sections are represented as an area appearing
886before its contents, so that it is possible to reconstruct the hierarchy
887from the FMAP by using the offset information. This convention does not
888seem to be documented, but is used in Chromium OS.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600889
Simon Glassb1d414c2021-04-03 11:05:10 +1300890CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600891
892
Simon Glassb1d414c2021-04-03 11:05:10 +1300893
Simon Glassa7c97782022-08-07 16:33:25 -0600894.. _etype_gbb:
895
Simon Glassc1ae83c2018-07-17 13:25:44 -0600896Entry: gbb: An entry which contains a Chromium OS Google Binary Block
897---------------------------------------------------------------------
898
899Properties / Entry arguments:
900 - hardware-id: Hardware ID to use for this build (a string)
901 - keydir: Directory containing the public keys to use
902 - bmpblk: Filename containing images used by recovery
903
904Chromium OS uses a GBB to store various pieces of information, in particular
905the root and recovery keys that are used to verify the boot process. Some
906more details are here:
907
908 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
909
910but note that the page dates from 2013 so is quite out of date. See
911README.chromium for how to obtain the required keys and tools.
912
913
Simon Glassa7c97782022-08-07 16:33:25 -0600914
915.. _etype_image_header:
Simon Glassc1ae83c2018-07-17 13:25:44 -0600916
Simon Glasscec34ba2019-07-08 14:25:28 -0600917Entry: image-header: An entry which contains a pointer to the FDT map
918---------------------------------------------------------------------
919
920Properties / Entry arguments:
921 location: Location of header ("start" or "end" of image). This is
922 optional. If omitted then the entry must have an offset property.
923
924This adds an 8-byte entry to the start or end of the image, pointing to the
925location of the FDT map. The format is a magic number followed by an offset
926from the start or end of the image, in twos-compliment format.
927
928This entry must be in the top-level part of the image.
929
930NOTE: If the location is at the start/end, you will probably need to specify
931sort-by-offset for the image, unless you actually put the image header
932first/last in the entry list.
933
934
935
Simon Glassa7c97782022-08-07 16:33:25 -0600936.. _etype_intel_cmc:
937
Simon Glass8911fa12021-03-18 20:25:16 +1300938Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
939-----------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -0600940
941Properties / Entry arguments:
942 - filename: Filename of file to read into entry
943
944This file contains microcode for some devices in a special format. An
945example filename is 'Microcode/C0_22211.BIN'.
946
947See README.x86 for information about x86 binary blobs.
948
949
950
Simon Glassa7c97782022-08-07 16:33:25 -0600951.. _etype_intel_descriptor:
952
Simon Glass7a61c6b2018-07-17 13:25:37 -0600953Entry: intel-descriptor: Intel flash descriptor block (4KB)
954-----------------------------------------------------------
955
956Properties / Entry arguments:
957 filename: Filename of file containing the descriptor. This is typically
958 a 4KB binary file, sometimes called 'descriptor.bin'
959
960This entry is placed at the start of flash and provides information about
961the SPI flash regions. In particular it provides the base address and
962size of the ME (Management Engine) region, allowing us to place the ME
963binary in the right place.
964
965With this entry in your image, the position of the 'intel-me' entry will be
966fixed in the image, which avoids you needed to specify an offset for that
967region. This is useful, because it is not possible to change the position
968of the ME region without updating the descriptor.
969
970See README.x86 for information about x86 binary blobs.
971
972
973
Simon Glassa7c97782022-08-07 16:33:25 -0600974.. _etype_intel_fit:
975
Simon Glass232f90c2019-08-24 07:22:50 -0600976Entry: intel-fit: Intel Firmware Image Table (FIT)
977--------------------------------------------------
978
979This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
980contains information about the firmware and microcode available in the
981image.
982
983At present binman only supports a basic FIT with no microcode.
984
985
986
Simon Glassa7c97782022-08-07 16:33:25 -0600987.. _etype_intel_fit_ptr:
988
Simon Glass232f90c2019-08-24 07:22:50 -0600989Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
990--------------------------------------------------------------
991
992This entry contains a pointer to the FIT. It is required to be at address
9930xffffffc0 in the image.
994
995
996
Simon Glassa7c97782022-08-07 16:33:25 -0600997.. _etype_intel_fsp:
998
Simon Glass8911fa12021-03-18 20:25:16 +1300999Entry: intel-fsp: Intel Firmware Support Package (FSP) file
1000-----------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001001
1002Properties / Entry arguments:
1003 - filename: Filename of file to read into entry
1004
1005This file contains binary blobs which are used on some devices to make the
1006platform work. U-Boot executes this code since it is not possible to set up
1007the hardware using U-Boot open-source code. Documentation is typically not
1008available in sufficient detail to allow this.
1009
1010An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
1011
1012See README.x86 for information about x86 binary blobs.
1013
1014
1015
Simon Glassa7c97782022-08-07 16:33:25 -06001016.. _etype_intel_fsp_m:
1017
Simon Glass8911fa12021-03-18 20:25:16 +13001018Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
1019--------------------------------------------------------------------
Simon Glassba7985d2019-08-24 07:23:07 -06001020
1021Properties / Entry arguments:
1022 - filename: Filename of file to read into entry
1023
1024This file contains a binary blob which is used on some devices to set up
1025SDRAM. U-Boot executes this code in SPL so that it can make full use of
1026memory. Documentation is typically not available in sufficient detail to
1027allow U-Boot do this this itself..
1028
1029An example filename is 'fsp_m.bin'
1030
1031See README.x86 for information about x86 binary blobs.
1032
1033
Simon Glassa7c97782022-08-07 16:33:25 -06001034
1035.. _etype_intel_fsp_s:
Simon Glassba7985d2019-08-24 07:23:07 -06001036
Simon Glass8911fa12021-03-18 20:25:16 +13001037Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
1038---------------------------------------------------------------------
Simon Glass4d9086d2019-10-20 21:31:35 -06001039
1040Properties / Entry arguments:
1041 - filename: Filename of file to read into entry
1042
1043This file contains a binary blob which is used on some devices to set up
1044the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
1045running, so that it can make full use of memory. Documentation is typically
1046not available in sufficient detail to allow U-Boot do this this itself.
1047
1048An example filename is 'fsp_s.bin'
1049
1050See README.x86 for information about x86 binary blobs.
1051
1052
1053
Simon Glassa7c97782022-08-07 16:33:25 -06001054.. _etype_intel_fsp_t:
1055
Simon Glass8911fa12021-03-18 20:25:16 +13001056Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
1057----------------------------------------------------------------------
Simon Glass9ea87b22019-10-20 21:31:36 -06001058
1059Properties / Entry arguments:
1060 - filename: Filename of file to read into entry
1061
1062This file contains a binary blob which is used on some devices to set up
1063temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
1064that it has access to memory for its stack and initial storage.
1065
1066An example filename is 'fsp_t.bin'
1067
1068See README.x86 for information about x86 binary blobs.
1069
1070
Simon Glassa7c97782022-08-07 16:33:25 -06001071
1072.. _etype_intel_ifwi:
Simon Glass9ea87b22019-10-20 21:31:36 -06001073
Simon Glass8911fa12021-03-18 20:25:16 +13001074Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
1075--------------------------------------------------------------
Simon Glassc2f1aed2019-07-08 13:18:56 -06001076
1077Properties / Entry arguments:
1078 - filename: Filename of file to read into entry. This is either the
1079 IFWI file itself, or a file that can be converted into one using a
1080 tool
1081 - convert-fit: If present this indicates that the ifwitool should be
1082 used to convert the provided file into a IFWI.
1083
1084This file contains code and data used by the SoC that is required to make
1085it work. It includes U-Boot TPL, microcode, things related to the CSE
1086(Converged Security Engine, the microcontroller that loads all the firmware)
1087and other items beyond the wit of man.
1088
1089A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
1090file that will be converted to an IFWI.
1091
1092The position of this entry is generally set by the intel-descriptor entry.
1093
1094The contents of the IFWI are specified by the subnodes of the IFWI node.
1095Each subnode describes an entry which is placed into the IFWFI with a given
1096sub-partition (and optional entry name).
1097
Simon Glass8a5e2492019-08-24 07:22:47 -06001098Properties for subnodes:
Simon Glass0ac96b62021-03-18 20:25:15 +13001099 - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
1100 - ifwi-entry: entry name t use, e.g. "IBBL"
1101 - ifwi-replace: if present, indicates that the item should be replaced
1102 in the IFWI. Otherwise it is added.
Simon Glass8a5e2492019-08-24 07:22:47 -06001103
Simon Glassc2f1aed2019-07-08 13:18:56 -06001104See README.x86 for information about x86 binary blobs.
1105
1106
1107
Simon Glassa7c97782022-08-07 16:33:25 -06001108.. _etype_intel_me:
1109
Simon Glass8911fa12021-03-18 20:25:16 +13001110Entry: intel-me: Intel Management Engine (ME) file
1111--------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001112
1113Properties / Entry arguments:
1114 - filename: Filename of file to read into entry
1115
1116This file contains code used by the SoC that is required to make it work.
1117The Management Engine is like a background task that runs things that are
Thomas Hebbfd37f242019-11-13 18:18:03 -08001118not clearly documented, but may include keyboard, display and network
Simon Glass7a61c6b2018-07-17 13:25:37 -06001119access. For platform that use ME it is not possible to disable it. U-Boot
1120does not directly execute code in the ME binary.
1121
1122A typical filename is 'me.bin'.
1123
Simon Glassc4056b82019-07-08 13:18:38 -06001124The position of this entry is generally set by the intel-descriptor entry.
1125
Simon Glass7a61c6b2018-07-17 13:25:37 -06001126See README.x86 for information about x86 binary blobs.
1127
1128
1129
Simon Glassa7c97782022-08-07 16:33:25 -06001130.. _etype_intel_mrc:
1131
Simon Glass8911fa12021-03-18 20:25:16 +13001132Entry: intel-mrc: Intel Memory Reference Code (MRC) file
1133--------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001134
1135Properties / Entry arguments:
1136 - filename: Filename of file to read into entry
1137
1138This file contains code for setting up the SDRAM on some Intel systems. This
1139is executed by U-Boot when needed early during startup. A typical filename
1140is 'mrc.bin'.
1141
1142See README.x86 for information about x86 binary blobs.
1143
1144
1145
Simon Glassa7c97782022-08-07 16:33:25 -06001146.. _etype_intel_refcode:
1147
Simon Glass8911fa12021-03-18 20:25:16 +13001148Entry: intel-refcode: Intel Reference Code file
1149-----------------------------------------------
Simon Glass17b84eb2019-05-17 22:00:53 -06001150
1151Properties / Entry arguments:
1152 - filename: Filename of file to read into entry
1153
1154This file contains code for setting up the platform on some Intel systems.
1155This is executed by U-Boot when needed early during startup. A typical
1156filename is 'refcode.bin'.
1157
1158See README.x86 for information about x86 binary blobs.
1159
1160
1161
Simon Glassa7c97782022-08-07 16:33:25 -06001162.. _etype_intel_vbt:
1163
Simon Glass8911fa12021-03-18 20:25:16 +13001164Entry: intel-vbt: Intel Video BIOS Table (VBT) file
1165---------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001166
1167Properties / Entry arguments:
1168 - filename: Filename of file to read into entry
1169
1170This file contains code that sets up the integrated graphics subsystem on
1171some Intel SoCs. U-Boot executes this when the display is started up.
1172
1173See README.x86 for information about Intel binary blobs.
1174
1175
1176
Simon Glassa7c97782022-08-07 16:33:25 -06001177.. _etype_intel_vga:
1178
Simon Glass8911fa12021-03-18 20:25:16 +13001179Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
1180---------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001181
1182Properties / Entry arguments:
1183 - filename: Filename of file to read into entry
1184
1185This file contains code that sets up the integrated graphics subsystem on
1186some Intel SoCs. U-Boot executes this when the display is started up.
1187
1188This is similar to the VBT file but in a different format.
1189
1190See README.x86 for information about Intel binary blobs.
1191
1192
1193
Simon Glassa7c97782022-08-07 16:33:25 -06001194.. _etype_mkimage:
1195
Simon Glass8911fa12021-03-18 20:25:16 +13001196Entry: mkimage: Binary produced by mkimage
1197------------------------------------------
Simon Glass48f3aad2020-07-09 18:39:31 -06001198
1199Properties / Entry arguments:
Simon Glass42074dc2022-08-13 11:40:47 -06001200 - args: Arguments to pass
Simon Glass8fbca772022-08-13 11:40:48 -06001201 - data-to-imagename: Indicates that the -d data should be passed in as
1202 the image name also (-n)
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001203 - multiple-data-files: boolean to tell binman to pass all files as
1204 datafiles to mkimage instead of creating a temporary file the result
1205 of datafiles concatenation
Simon Glassda6a9082023-01-07 14:07:10 -07001206 - filename: filename of output binary generated by mkimage
Simon Glass48f3aad2020-07-09 18:39:31 -06001207
Simon Glass42074dc2022-08-13 11:40:47 -06001208The data passed to mkimage via the -d flag is collected from subnodes of the
1209mkimage node, e.g.::
Simon Glass48f3aad2020-07-09 18:39:31 -06001210
1211 mkimage {
Simon Glassda6a9082023-01-07 14:07:10 -07001212 filename = "imximage.bin";
Simon Glass48f3aad2020-07-09 18:39:31 -06001213 args = "-n test -T imximage";
1214
1215 u-boot-spl {
1216 };
1217 };
1218
Simon Glass42074dc2022-08-13 11:40:47 -06001219This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
Simon Glassda6a9082023-01-07 14:07:10 -07001220file, with mkimage being called like this::
Simon Glass42074dc2022-08-13 11:40:47 -06001221
1222 mkimage -d <data_file> -n test -T imximage <output_file>
1223
1224The output from mkimage then becomes part of the image produced by
Simon Glassda6a9082023-01-07 14:07:10 -07001225binman but also is written into `imximage.bin` file. If you need to put
1226multiple things in the data file, you can use a section, or just multiple
1227subnodes like this::
Simon Glass42074dc2022-08-13 11:40:47 -06001228
1229 mkimage {
1230 args = "-n test -T imximage";
1231
1232 u-boot-spl {
1233 };
1234
1235 u-boot-tpl {
1236 };
1237 };
Simon Glass48f3aad2020-07-09 18:39:31 -06001238
Simon Glassda6a9082023-01-07 14:07:10 -07001239Note that binman places the contents (here SPL and TPL) into a single file
1240and passes that to mkimage using the -d option.
1241
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001242To pass all datafiles untouched to mkimage::
1243
1244 mkimage {
Simon Glassda6a9082023-01-07 14:07:10 -07001245 args = "-n rk3399 -T rkspi";
1246 multiple-data-files;
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001247
Simon Glassda6a9082023-01-07 14:07:10 -07001248 u-boot-tpl {
1249 };
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001250
Simon Glassda6a9082023-01-07 14:07:10 -07001251 u-boot-spl {
1252 };
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001253 };
1254
1255This calls mkimage to create a Rockchip RK3399-specific first stage
1256bootloader, made of TPL+SPL. Since this first stage bootloader requires to
1257align the TPL and SPL but also some weird hacks that is handled by mkimage
1258directly, binman is told to not perform the concatenation of datafiles prior
1259to passing the data to mkimage.
1260
Simon Glass948dd3a2022-02-08 11:49:58 -07001261To use CONFIG options in the arguments, use a string list instead, as in
1262this example which also produces four arguments::
1263
1264 mkimage {
1265 args = "-n", CONFIG_SYS_SOC, "-T imximage";
1266
1267 u-boot-spl {
1268 };
1269 };
1270
Simon Glass8fbca772022-08-13 11:40:48 -06001271If you need to pass the input data in with the -n argument as well, then use
1272the 'data-to-imagename' property::
1273
1274 mkimage {
1275 args = "-T imximage";
Simon Glassda6a9082023-01-07 14:07:10 -07001276 data-to-imagename;
Simon Glass8fbca772022-08-13 11:40:48 -06001277
1278 u-boot-spl {
1279 };
1280 };
1281
1282That will pass the data to mkimage both as the data file (with -d) and as
Simon Glassda6a9082023-01-07 14:07:10 -07001283the image name (with -n). In both cases, a filename is passed as the
1284argument, with the actual data being in that file.
Simon Glass948dd3a2022-02-08 11:49:58 -07001285
Simon Glassda6a9082023-01-07 14:07:10 -07001286If need to pass different data in with -n, then use an `imagename` subnode::
Simon Glassb1669752022-08-13 11:40:49 -06001287
1288 mkimage {
1289 args = "-T imximage";
1290
1291 imagename {
1292 blob {
1293 filename = "spl/u-boot-spl.cfgout"
1294 };
1295 };
1296
1297 u-boot-spl {
1298 };
1299 };
1300
1301This will pass in u-boot-spl as the input data and the .cfgout file as the
1302-n data.
1303
Simon Glassa7c97782022-08-07 16:33:25 -06001304
Simon Glassda6a9082023-01-07 14:07:10 -07001305
Simon Glassa4948b22023-01-11 16:10:14 -07001306.. _etype_null:
1307
1308Entry: null: An entry which has no contents of its own
1309------------------------------------------------------
1310
1311Note that the size property must be set since otherwise this entry does not
1312know how large it should be.
1313
1314The contents are set by the containing section, e.g. the section's pad
1315byte.
1316
1317
1318
Simon Glassa7c97782022-08-07 16:33:25 -06001319.. _etype_opensbi:
Simon Glass48f3aad2020-07-09 18:39:31 -06001320
Bin Mengc0b15742021-05-10 20:23:33 +08001321Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
1322----------------------------------------------
1323
1324Properties / Entry arguments:
1325 - opensbi-path: Filename of file to read into entry. This is typically
1326 called fw_dynamic.bin
1327
1328This entry holds the run-time firmware, typically started by U-Boot SPL.
1329See the U-Boot README for your architecture or board for how to use it. See
1330https://github.com/riscv/opensbi for more information about OpenSBI.
1331
1332
1333
Simon Glassa7c97782022-08-07 16:33:25 -06001334.. _etype_powerpc_mpc85xx_bootpg_resetvec:
1335
Jagdish Gediya311d4842018-09-03 21:35:08 +05301336Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
1337-----------------------------------------------------------------------------------------
1338
1339Properties / Entry arguments:
1340 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
1341
Thomas Hebbfd37f242019-11-13 18:18:03 -08001342This entry is valid for PowerPC mpc85xx cpus. This entry holds
Jagdish Gediya311d4842018-09-03 21:35:08 +05301343'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
1344placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
1345
Simon Glass136dd352020-10-26 17:39:59 -06001346
Simon Glassa7c97782022-08-07 16:33:25 -06001347
1348.. _etype_pre_load:
Simon Glass136dd352020-10-26 17:39:59 -06001349
Philippe Reynesebe96cb2022-03-28 22:57:04 +02001350Entry: pre-load: Pre load image header
1351--------------------------------------
1352
1353Properties / Entry arguments:
Simon Glass9f571582022-08-13 11:40:43 -06001354 - pre-load-key-path: Path of the directory that store key (provided by
1355 the environment variable PRE_LOAD_KEY_PATH)
Philippe Reynesebe96cb2022-03-28 22:57:04 +02001356 - content: List of phandles to entries to sign
1357 - algo-name: Hash and signature algo to use for the signature
1358 - padding-name: Name of the padding (pkcs-1.5 or pss)
1359 - key-name: Filename of the private key to sign
1360 - header-size: Total size of the header
1361 - version: Version of the header
1362
1363This entry creates a pre-load header that contains a global
1364image signature.
1365
1366For example, this creates an image with a pre-load header and a binary::
1367
1368 binman {
1369 image2 {
1370 filename = "sandbox.bin";
1371
1372 pre-load {
1373 content = <&image>;
1374 algo-name = "sha256,rsa2048";
1375 padding-name = "pss";
1376 key-name = "private.pem";
1377 header-size = <4096>;
1378 version = <1>;
1379 };
1380
1381 image: blob-ext {
1382 filename = "sandbox.itb";
1383 };
1384 };
1385 };
1386
1387
1388
Simon Glassa7c97782022-08-07 16:33:25 -06001389.. _etype_scp:
1390
Simon Glass8911fa12021-03-18 20:25:16 +13001391Entry: scp: System Control Processor (SCP) firmware blob
1392--------------------------------------------------------
Simon Glass136dd352020-10-26 17:39:59 -06001393
1394Properties / Entry arguments:
1395 - scp-path: Filename of file to read into the entry, typically scp.bin
1396
1397This entry holds firmware for an external platform-specific coprocessor.
Jagdish Gediya311d4842018-09-03 21:35:08 +05301398
1399
Simon Glass136dd352020-10-26 17:39:59 -06001400
Simon Glassa7c97782022-08-07 16:33:25 -06001401.. _etype_section:
1402
Simon Glass7a61c6b2018-07-17 13:25:37 -06001403Entry: section: Entry that contains other entries
1404-------------------------------------------------
1405
Simon Glasscc9a41c2021-11-23 11:03:49 -07001406A section is an entry which can contain other entries, thus allowing
1407hierarchical images to be created. See 'Sections and hierarchical images'
1408in the binman README for more information.
1409
1410The base implementation simply joins the various entries together, using
1411various rules about alignment, etc.
1412
1413Subclassing
1414~~~~~~~~~~~
1415
1416This class can be subclassed to support other file formats which hold
1417multiple entries, such as CBFS. To do this, override the following
1418functions. The documentation here describes what your function should do.
1419For example code, see etypes which subclass `Entry_section`, or `cbfs.py`
1420for a more involved example::
1421
1422 $ grep -l \(Entry_section tools/binman/etype/*.py
1423
1424ReadNode()
1425 Call `super().ReadNode()`, then read any special properties for the
1426 section. Then call `self.ReadEntries()` to read the entries.
1427
1428 Binman calls this at the start when reading the image description.
1429
1430ReadEntries()
1431 Read in the subnodes of the section. This may involve creating entries
1432 of a particular etype automatically, as well as reading any special
1433 properties in the entries. For each entry, entry.ReadNode() should be
1434 called, to read the basic entry properties. The properties should be
1435 added to `self._entries[]`, in the correct order, with a suitable name.
1436
1437 Binman calls this at the start when reading the image description.
1438
1439BuildSectionData(required)
1440 Create the custom file format that you want and return it as bytes.
1441 This likely sets up a file header, then loops through the entries,
1442 adding them to the file. For each entry, call `entry.GetData()` to
1443 obtain the data. If that returns None, and `required` is False, then
1444 this method must give up and return None. But if `required` is True then
1445 it should assume that all data is valid.
1446
1447 Binman calls this when packing the image, to find out the size of
1448 everything. It is called again at the end when building the final image.
1449
1450SetImagePos(image_pos):
1451 Call `super().SetImagePos(image_pos)`, then set the `image_pos` values
1452 for each of the entries. This should use the custom file format to find
1453 the `start offset` (and `image_pos`) of each entry. If the file format
1454 uses compression in such a way that there is no offset available (other
1455 than reading the whole file and decompressing it), then the offsets for
1456 affected entries can remain unset (`None`). The size should also be set
1457 if possible.
Simon Glass0ac96b62021-03-18 20:25:15 +13001458
Simon Glasscc9a41c2021-11-23 11:03:49 -07001459 Binman calls this after the image has been packed, to update the
1460 location that all the entries ended up at.
Simon Glass0ac96b62021-03-18 20:25:15 +13001461
Simon Glass637958f2021-11-23 21:09:50 -07001462ReadChildData(child, decomp, alt_format):
Simon Glasscc9a41c2021-11-23 11:03:49 -07001463 The default version of this may be good enough, if you are able to
1464 implement SetImagePos() correctly. But that is a bit of a bypass, so
1465 you can override this method to read from your custom file format. It
1466 should read the entire entry containing the custom file using
1467 `super().ReadData(True)`, then parse the file to get the data for the
1468 given child, then return that data.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001469
Simon Glasscc9a41c2021-11-23 11:03:49 -07001470 If your file format supports compression, the `decomp` argument tells
1471 you whether to return the compressed data (`decomp` is False) or to
1472 uncompress it first, then return the uncompressed data (`decomp` is
1473 True). This is used by the `binman extract -U` option.
Simon Glass21db0ff2020-09-01 05:13:54 -06001474
Simon Glass637958f2021-11-23 21:09:50 -07001475 If your entry supports alternative formats, the alt_format provides the
1476 alternative format that the user has selected. Your function should
1477 return data in that format. This is used by the 'binman extract -l'
1478 option.
1479
Simon Glasscc9a41c2021-11-23 11:03:49 -07001480 Binman calls this when reading in an image, in order to populate all the
1481 entries with the data from that image (`binman ls`).
1482
1483WriteChildData(child):
1484 Binman calls this after `child.data` is updated, to inform the custom
1485 file format about this, in case it needs to do updates.
1486
1487 The default version of this does nothing and probably needs to be
1488 overridden for the 'binman replace' command to work. Your version should
1489 use `child.data` to update the data for that child in the custom file
1490 format.
1491
1492 Binman calls this when updating an image that has been read in and in
1493 particular to update the data for a particular entry (`binman replace`)
1494
1495Properties / Entry arguments
1496~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1497
1498See :ref:`develop/package/binman:Image description format` for more
1499information.
1500
1501align-default
1502 Default alignment for this section, if no alignment is given in the
1503 entry
1504
1505pad-byte
1506 Pad byte to use when padding
1507
1508sort-by-offset
1509 True if entries should be sorted by offset, False if they must be
1510 in-order in the device tree description
1511
1512end-at-4gb
1513 Used to build an x86 ROM which ends at 4GB (2^32)
1514
1515name-prefix
1516 Adds a prefix to the name of every entry in the section when writing out
1517 the map
1518
1519skip-at-start
1520 Number of bytes before the first entry starts. These effectively adjust
1521 the starting offset of entries. For example, if this is 16, then the
1522 first entry would start at 16. An entry with offset = 20 would in fact
1523 be written at offset 4 in the image file, since the first 16 bytes are
1524 skipped when writing.
Simon Glassb1d414c2021-04-03 11:05:10 +13001525
Simon Glassda6a9082023-01-07 14:07:10 -07001526filename
1527 filename to write the unpadded section contents to within the output
1528 directory (None to skip this).
1529
Simon Glass39dd2152019-07-08 14:25:47 -06001530Since a section is also an entry, it inherits all the properies of entries
1531too.
1532
Simon Glasscc9a41c2021-11-23 11:03:49 -07001533Note that the `allow_missing` member controls whether this section permits
1534external blobs to be missing their contents. The option will produce an
1535image but of course it will not work. It is useful to make sure that
1536Continuous Integration systems can build without the binaries being
1537available. This is set by the `SetAllowMissing()` method, if
1538`--allow-missing` is passed to binman.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001539
1540
1541
Simon Glassa7c97782022-08-07 16:33:25 -06001542.. _etype_tee_os:
1543
Roger Quadros5cdcea02022-02-19 20:50:04 +02001544Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
1545---------------------------------------------------------------
1546
1547Properties / Entry arguments:
1548 - tee-os-path: Filename of file to read into entry. This is typically
Simon Glassad5cfe12023-01-07 14:07:14 -07001549 called tee.bin or tee.elf
Roger Quadros5cdcea02022-02-19 20:50:04 +02001550
1551This entry holds the run-time firmware, typically started by U-Boot SPL.
1552See the U-Boot README for your architecture or board for how to use it. See
1553https://github.com/OP-TEE/optee_os for more information about OP-TEE.
1554
Simon Glassad5cfe12023-01-07 14:07:14 -07001555Note that if the file is in ELF format, it must go in a FIT. In that case,
1556this entry will mark itself as absent, providing the data only through the
1557read_elf_segments() method.
1558
1559Marking this entry as absent means that it if is used in the wrong context
1560it can be automatically dropped. Thus it is possible to add an OP-TEE entry
1561like this::
1562
1563 binman {
1564 tee-os {
1565 };
1566 };
1567
1568and pass either an ELF or plain binary in with -a tee-os-path <filename>
1569and have binman do the right thing:
1570
1571 - include the entry if tee.bin is provided and it does NOT have the v1
1572 header
1573 - drop it otherwise
1574
1575When used within a FIT, we can do::
1576
1577 binman {
1578 fit {
1579 tee-os {
1580 };
1581 };
1582 };
1583
1584which will split the ELF into separate nodes for each segment, if an ELF
1585file is provided (see :ref:`etype_fit`), or produce a single node if the
1586OP-TEE binary v1 format is provided (see optee_doc_) .
1587
1588.. _optee_doc: https://optee.readthedocs.io/en/latest/architecture/core.html#partitioning-of-the-binary
1589
Roger Quadros5cdcea02022-02-19 20:50:04 +02001590
1591
Simon Glassa7c97782022-08-07 16:33:25 -06001592.. _etype_text:
1593
Simon Glass7a61c6b2018-07-17 13:25:37 -06001594Entry: text: An entry which contains text
1595-----------------------------------------
1596
1597The text can be provided either in the node itself or by a command-line
1598argument. There is a level of indirection to allow multiple text strings
1599and sharing of text.
1600
1601Properties / Entry arguments:
1602 text-label: The value of this string indicates the property / entry-arg
1603 that contains the string to place in the entry
1604 <xxx> (actual name is the value of text-label): contains the string to
1605 place in the entry.
Simon Glass47f6a622019-07-08 13:18:40 -06001606 <text>: The text to place in the entry (overrides the above mechanism).
1607 This is useful when the text is constant.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001608
Simon Glass0ac96b62021-03-18 20:25:15 +13001609Example node::
Simon Glass7a61c6b2018-07-17 13:25:37 -06001610
1611 text {
1612 size = <50>;
1613 text-label = "message";
1614 };
1615
1616You can then use:
1617
1618 binman -amessage="this is my message"
1619
1620and binman will insert that string into the entry.
1621
Simon Glass0ac96b62021-03-18 20:25:15 +13001622It is also possible to put the string directly in the node::
Simon Glass7a61c6b2018-07-17 13:25:37 -06001623
1624 text {
1625 size = <8>;
1626 text-label = "message";
1627 message = "a message directly in the node"
1628 };
1629
Simon Glass0ac96b62021-03-18 20:25:15 +13001630or just::
Simon Glass47f6a622019-07-08 13:18:40 -06001631
1632 text {
1633 size = <8>;
1634 text = "some text directly in the node"
1635 };
1636
Simon Glass7a61c6b2018-07-17 13:25:37 -06001637The text is not itself nul-terminated. This can be achieved, if required,
1638by setting the size of the entry to something larger than the text.
1639
1640
1641
Simon Glassa7c97782022-08-07 16:33:25 -06001642.. _etype_u_boot:
1643
Simon Glass7a61c6b2018-07-17 13:25:37 -06001644Entry: u-boot: U-Boot flat binary
1645---------------------------------
1646
1647Properties / Entry arguments:
1648 - filename: Filename of u-boot.bin (default 'u-boot.bin')
1649
1650This is the U-Boot binary, containing relocation information to allow it
1651to relocate itself at runtime. The binary typically includes a device tree
Simon Glass718b5292021-03-18 20:25:07 +13001652blob at the end of it.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001653
Simon Glass18ed9962023-01-07 14:07:11 -07001654U-Boot can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001655
Simon Glass718b5292021-03-18 20:25:07 +13001656Note that this entry is automatically replaced with u-boot-expanded unless
Simon Glass7098b7f2021-03-21 18:24:30 +13001657--no-expanded is used or the node has a 'no-expanded' property.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001658
1659
Simon Glass718b5292021-03-18 20:25:07 +13001660
Simon Glassa7c97782022-08-07 16:33:25 -06001661.. _etype_u_boot_dtb:
1662
Simon Glass7a61c6b2018-07-17 13:25:37 -06001663Entry: u-boot-dtb: U-Boot device tree
1664-------------------------------------
1665
1666Properties / Entry arguments:
1667 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1668
1669This is the U-Boot device tree, containing configuration information for
1670U-Boot. U-Boot needs this to know what devices are present and which drivers
1671to activate.
1672
Simon Glasse219aa42018-09-14 04:57:24 -06001673Note: This is mostly an internal entry type, used by others. This allows
1674binman to know which entries contain a device tree.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001675
1676
Simon Glassa7c97782022-08-07 16:33:25 -06001677
1678.. _etype_u_boot_dtb_with_ucode:
Simon Glass7a61c6b2018-07-17 13:25:37 -06001679
1680Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
1681-----------------------------------------------------------------------------------
1682
1683Properties / Entry arguments:
1684 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1685
1686See Entry_u_boot_ucode for full details of the three entries involved in
1687this process. This entry provides the U-Boot device-tree file, which
1688contains the microcode. If the microcode is not being collated into one
1689place then the offset and size of the microcode is recorded by this entry,
Simon Glass537e0062021-03-18 20:24:54 +13001690for use by u-boot-with-ucode_ptr. If it is being collated, then this
Simon Glass7a61c6b2018-07-17 13:25:37 -06001691entry deletes the microcode from the device tree (to save space) and makes
Simon Glass537e0062021-03-18 20:24:54 +13001692it available to u-boot-ucode.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001693
1694
1695
Simon Glassa7c97782022-08-07 16:33:25 -06001696.. _etype_u_boot_elf:
1697
Simon Glassb1714232018-09-14 04:57:35 -06001698Entry: u-boot-elf: U-Boot ELF image
1699-----------------------------------
1700
1701Properties / Entry arguments:
1702 - filename: Filename of u-boot (default 'u-boot')
1703
1704This is the U-Boot ELF image. It does not include a device tree but can be
1705relocated to any address for execution.
1706
1707
Simon Glassa7c97782022-08-07 16:33:25 -06001708
1709.. _etype_u_boot_env:
Simon Glassb1714232018-09-14 04:57:35 -06001710
Simon Glass136dd352020-10-26 17:39:59 -06001711Entry: u-boot-env: An entry which contains a U-Boot environment
1712---------------------------------------------------------------
1713
1714Properties / Entry arguments:
1715 - filename: File containing the environment text, with each line in the
1716 form var=value
1717
1718
Simon Glass718b5292021-03-18 20:25:07 +13001719
Simon Glassa7c97782022-08-07 16:33:25 -06001720.. _etype_u_boot_expanded:
1721
Simon Glass718b5292021-03-18 20:25:07 +13001722Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
1723------------------------------------------------------------------------------
1724
1725This is a section containing the U-Boot binary and a devicetree. Using this
1726entry type automatically creates this section, with the following entries
1727in it:
1728
1729 u-boot-nodtb
1730 u-boot-dtb
1731
1732Having the devicetree separate allows binman to update it in the final
1733image, so that the entries positions are provided to the running U-Boot.
1734
1735
Simon Glass136dd352020-10-26 17:39:59 -06001736
Simon Glassa7c97782022-08-07 16:33:25 -06001737.. _etype_u_boot_img:
1738
Simon Glass7a61c6b2018-07-17 13:25:37 -06001739Entry: u-boot-img: U-Boot legacy image
1740--------------------------------------
1741
1742Properties / Entry arguments:
1743 - filename: Filename of u-boot.img (default 'u-boot.img')
1744
1745This is the U-Boot binary as a packaged image, in legacy format. It has a
1746header which allows it to be loaded at the correct address for execution.
1747
1748You should use FIT (Flat Image Tree) instead of the legacy image for new
1749applications.
1750
1751
1752
Simon Glassa7c97782022-08-07 16:33:25 -06001753.. _etype_u_boot_nodtb:
1754
Simon Glass7a61c6b2018-07-17 13:25:37 -06001755Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
1756--------------------------------------------------------------------
1757
1758Properties / Entry arguments:
Simon Glass537e0062021-03-18 20:24:54 +13001759 - filename: Filename to include (default 'u-boot-nodtb.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06001760
1761This is the U-Boot binary, containing relocation information to allow it
1762to relocate itself at runtime. It does not include a device tree blob at
Simon Glass537e0062021-03-18 20:24:54 +13001763the end of it so normally cannot work without it. You can add a u-boot-dtb
Simon Glass718b5292021-03-18 20:25:07 +13001764entry after this one, or use a u-boot entry instead, normally expands to a
1765section containing u-boot and u-boot-dtb
Simon Glass7a61c6b2018-07-17 13:25:37 -06001766
1767
1768
Simon Glassa7c97782022-08-07 16:33:25 -06001769.. _etype_u_boot_spl:
1770
Simon Glass7a61c6b2018-07-17 13:25:37 -06001771Entry: u-boot-spl: U-Boot SPL binary
1772------------------------------------
1773
1774Properties / Entry arguments:
1775 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
1776
1777This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
1778binary which loads before U-Boot proper, typically into on-chip SRAM. It is
1779responsible for locating, loading and jumping to U-Boot. Note that SPL is
1780not relocatable so must be loaded to the correct address in SRAM, or written
Simon Glass8425a1f2018-07-17 13:25:48 -06001781to run from the correct address if direct flash execution is possible (e.g.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001782on x86 devices).
1783
Simon Glass18ed9962023-01-07 14:07:11 -07001784SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001785
1786in the binman README for more information.
1787
1788The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1789binman uses that to look up symbols to write into the SPL binary.
1790
Simon Glass718b5292021-03-18 20:25:07 +13001791Note that this entry is automatically replaced with u-boot-spl-expanded
Simon Glass7098b7f2021-03-21 18:24:30 +13001792unless --no-expanded is used or the node has a 'no-expanded' property.
Simon Glass718b5292021-03-18 20:25:07 +13001793
Simon Glass7a61c6b2018-07-17 13:25:37 -06001794
1795
Simon Glassa7c97782022-08-07 16:33:25 -06001796.. _etype_u_boot_spl_bss_pad:
1797
Simon Glass7a61c6b2018-07-17 13:25:37 -06001798Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
1799---------------------------------------------------------------------
1800
1801Properties / Entry arguments:
1802 None
1803
Simon Glass308939b2021-03-18 20:24:55 +13001804This holds the padding added after the SPL binary to cover the BSS (Block
1805Started by Symbol) region. This region holds the various variables used by
1806SPL. It is set to 0 by SPL when it starts up. If you want to append data to
1807the SPL image (such as a device tree file), you must pad out the BSS region
1808to avoid the data overlapping with U-Boot variables. This entry is useful in
1809that case. It automatically pads out the entry size to cover both the code,
1810data and BSS.
1811
1812The contents of this entry will a certain number of zero bytes, determined
1813by __bss_size
Simon Glass7a61c6b2018-07-17 13:25:37 -06001814
1815The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1816binman uses that to look up the BSS address.
1817
1818
1819
Simon Glassa7c97782022-08-07 16:33:25 -06001820.. _etype_u_boot_spl_dtb:
1821
Simon Glass7a61c6b2018-07-17 13:25:37 -06001822Entry: u-boot-spl-dtb: U-Boot SPL device tree
1823---------------------------------------------
1824
1825Properties / Entry arguments:
1826 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
1827
1828This is the SPL device tree, containing configuration information for
1829SPL. SPL needs this to know what devices are present and which drivers
1830to activate.
1831
1832
Simon Glassa7c97782022-08-07 16:33:25 -06001833
1834.. _etype_u_boot_spl_elf:
Simon Glass7a61c6b2018-07-17 13:25:37 -06001835
Simon Glassb1714232018-09-14 04:57:35 -06001836Entry: u-boot-spl-elf: U-Boot SPL ELF image
1837-------------------------------------------
1838
1839Properties / Entry arguments:
Simon Glass5dcc21d2019-07-08 13:18:45 -06001840 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
Simon Glassb1714232018-09-14 04:57:35 -06001841
1842This is the U-Boot SPL ELF image. It does not include a device tree but can
1843be relocated to any address for execution.
1844
Simon Glass718b5292021-03-18 20:25:07 +13001845
1846
Simon Glassa7c97782022-08-07 16:33:25 -06001847.. _etype_u_boot_spl_expanded:
1848
Simon Glass718b5292021-03-18 20:25:07 +13001849Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
1850--------------------------------------------------------------------------------------
1851
1852Properties / Entry arguments:
1853 - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
1854 select)
1855
1856This is a section containing the U-Boot binary, BSS padding if needed and a
1857devicetree. Using this entry type automatically creates this section, with
1858the following entries in it:
1859
1860 u-boot-spl-nodtb
1861 u-boot-spl-bss-pad
1862 u-boot-dtb
1863
1864Having the devicetree separate allows binman to update it in the final
1865image, so that the entries positions are provided to the running U-Boot.
1866
1867This entry is selected based on the value of the 'spl-dtb' entryarg. If
1868this is non-empty (and not 'n' or '0') then this expanded entry is selected.
Simon Glassb1714232018-09-14 04:57:35 -06001869
1870
Simon Glassa7c97782022-08-07 16:33:25 -06001871
1872.. _etype_u_boot_spl_nodtb:
Simon Glass718b5292021-03-18 20:25:07 +13001873
Simon Glass7a61c6b2018-07-17 13:25:37 -06001874Entry: u-boot-spl-nodtb: SPL binary without device tree appended
1875----------------------------------------------------------------
1876
1877Properties / Entry arguments:
Simon Glass537e0062021-03-18 20:24:54 +13001878 - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06001879
1880This is the U-Boot SPL binary, It does not include a device tree blob at
1881the end of it so may not be able to work without it, assuming SPL needs
Simon Glass537e0062021-03-18 20:24:54 +13001882a device tree to operate on your platform. You can add a u-boot-spl-dtb
Simon Glass718b5292021-03-18 20:25:07 +13001883entry after this one, or use a u-boot-spl entry instead' which normally
1884expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
1885u-boot-spl-dtb
Simon Glass7a61c6b2018-07-17 13:25:37 -06001886
Simon Glass18ed9962023-01-07 14:07:11 -07001887SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass31e04cb2021-03-18 20:24:56 +13001888
1889in the binman README for more information.
1890
1891The ELF file 'spl/u-boot-spl' must also be available for this to work, since
1892binman uses that to look up symbols to write into the SPL binary.
1893
Simon Glass7a61c6b2018-07-17 13:25:37 -06001894
1895
Simon Glassa7c97782022-08-07 16:33:25 -06001896.. _etype_u_boot_spl_with_ucode_ptr:
1897
Simon Glass7a61c6b2018-07-17 13:25:37 -06001898Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
1899----------------------------------------------------------------------------
1900
Simon Glass3fb4f422018-09-14 04:57:32 -06001901This is used when SPL must set up the microcode for U-Boot.
1902
Simon Glass7a61c6b2018-07-17 13:25:37 -06001903See Entry_u_boot_ucode for full details of the entries involved in this
1904process.
1905
1906
1907
Simon Glassa7c97782022-08-07 16:33:25 -06001908.. _etype_u_boot_tpl:
1909
Simon Glass8425a1f2018-07-17 13:25:48 -06001910Entry: u-boot-tpl: U-Boot TPL binary
1911------------------------------------
1912
1913Properties / Entry arguments:
1914 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
1915
1916This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
1917binary which loads before SPL, typically into on-chip SRAM. It is
1918responsible for locating, loading and jumping to SPL, the next-stage
1919loader. Note that SPL is not relocatable so must be loaded to the correct
1920address in SRAM, or written to run from the correct address if direct
1921flash execution is possible (e.g. on x86 devices).
1922
Simon Glass18ed9962023-01-07 14:07:11 -07001923SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass8425a1f2018-07-17 13:25:48 -06001924
1925in the binman README for more information.
1926
1927The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1928binman uses that to look up symbols to write into the TPL binary.
1929
Simon Glass718b5292021-03-18 20:25:07 +13001930Note that this entry is automatically replaced with u-boot-tpl-expanded
Simon Glass7098b7f2021-03-21 18:24:30 +13001931unless --no-expanded is used or the node has a 'no-expanded' property.
Simon Glass718b5292021-03-18 20:25:07 +13001932
Simon Glass8425a1f2018-07-17 13:25:48 -06001933
1934
Simon Glassa7c97782022-08-07 16:33:25 -06001935.. _etype_u_boot_tpl_bss_pad:
1936
Simon Glass63f41d42021-03-18 20:24:58 +13001937Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
1938---------------------------------------------------------------------
1939
1940Properties / Entry arguments:
1941 None
1942
1943This holds the padding added after the TPL binary to cover the BSS (Block
1944Started by Symbol) region. This region holds the various variables used by
1945TPL. It is set to 0 by TPL when it starts up. If you want to append data to
1946the TPL image (such as a device tree file), you must pad out the BSS region
1947to avoid the data overlapping with U-Boot variables. This entry is useful in
1948that case. It automatically pads out the entry size to cover both the code,
1949data and BSS.
1950
1951The contents of this entry will a certain number of zero bytes, determined
1952by __bss_size
1953
1954The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
1955binman uses that to look up the BSS address.
1956
1957
1958
Simon Glassa7c97782022-08-07 16:33:25 -06001959.. _etype_u_boot_tpl_dtb:
1960
Simon Glass8425a1f2018-07-17 13:25:48 -06001961Entry: u-boot-tpl-dtb: U-Boot TPL device tree
1962---------------------------------------------
1963
1964Properties / Entry arguments:
1965 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
1966
1967This is the TPL device tree, containing configuration information for
1968TPL. TPL needs this to know what devices are present and which drivers
1969to activate.
1970
1971
1972
Simon Glassa7c97782022-08-07 16:33:25 -06001973.. _etype_u_boot_tpl_dtb_with_ucode:
1974
Simon Glass3fb4f422018-09-14 04:57:32 -06001975Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
1976----------------------------------------------------------------------------
1977
1978This is used when TPL must set up the microcode for U-Boot.
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_tpl_elf:
1986
Simon Glassa899f712019-07-08 13:18:46 -06001987Entry: u-boot-tpl-elf: U-Boot TPL ELF image
1988-------------------------------------------
1989
1990Properties / Entry arguments:
1991 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
1992
1993This is the U-Boot TPL ELF image. It does not include a device tree but can
1994be relocated to any address for execution.
1995
1996
Simon Glassa7c97782022-08-07 16:33:25 -06001997
1998.. _etype_u_boot_tpl_expanded:
Simon Glassa899f712019-07-08 13:18:46 -06001999
Simon Glass718b5292021-03-18 20:25:07 +13002000Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
2001--------------------------------------------------------------------------------------
2002
2003Properties / Entry arguments:
2004 - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2005 select)
2006
2007This is a section containing the U-Boot binary, BSS padding if needed and a
2008devicetree. Using this entry type automatically creates this section, with
2009the following entries in it:
2010
2011 u-boot-tpl-nodtb
2012 u-boot-tpl-bss-pad
2013 u-boot-dtb
2014
2015Having the devicetree separate allows binman to update it in the final
2016image, so that the entries positions are provided to the running U-Boot.
2017
2018This entry is selected based on the value of the 'tpl-dtb' entryarg. If
2019this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2020
2021
2022
Simon Glassa7c97782022-08-07 16:33:25 -06002023.. _etype_u_boot_tpl_nodtb:
2024
Simon Glassc98de972021-03-18 20:24:57 +13002025Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
2026----------------------------------------------------------------
2027
2028Properties / Entry arguments:
2029 - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin')
2030
2031This is the U-Boot TPL binary, It does not include a device tree blob at
2032the end of it so may not be able to work without it, assuming TPL needs
2033a device tree to operate on your platform. You can add a u-boot-tpl-dtb
Simon Glass718b5292021-03-18 20:25:07 +13002034entry after this one, or use a u-boot-tpl entry instead, which normally
2035expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
2036u-boot-tpl-dtb
Simon Glassc98de972021-03-18 20:24:57 +13002037
Simon Glass18ed9962023-01-07 14:07:11 -07002038TPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassc98de972021-03-18 20:24:57 +13002039
2040in the binman README for more information.
2041
2042The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2043binman uses that to look up symbols to write into the TPL binary.
2044
2045
Simon Glassa7c97782022-08-07 16:33:25 -06002046
2047.. _etype_u_boot_tpl_with_ucode_ptr:
Simon Glassc98de972021-03-18 20:24:57 +13002048
Simon Glass3fb4f422018-09-14 04:57:32 -06002049Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
2050----------------------------------------------------------------------------
2051
2052See Entry_u_boot_ucode for full details of the entries involved in this
2053process.
2054
2055
2056
Simon Glassa7c97782022-08-07 16:33:25 -06002057.. _etype_u_boot_ucode:
2058
Simon Glass7a61c6b2018-07-17 13:25:37 -06002059Entry: u-boot-ucode: U-Boot microcode block
2060-------------------------------------------
2061
2062Properties / Entry arguments:
2063 None
2064
2065The contents of this entry are filled in automatically by other entries
2066which must also be in the image.
2067
2068U-Boot on x86 needs a single block of microcode. This is collected from
2069the various microcode update nodes in the device tree. It is also unable
2070to read the microcode from the device tree on platforms that use FSP
2071(Firmware Support Package) binaries, because the API requires that the
2072microcode is supplied before there is any SRAM available to use (i.e.
2073the FSP sets up the SRAM / cache-as-RAM but does so in the call that
2074requires the microcode!). To keep things simple, all x86 platforms handle
2075microcode the same way in U-Boot (even non-FSP platforms). This is that
2076a table is placed at _dt_ucode_base_size containing the base address and
2077size of the microcode. This is either passed to the FSP (for FSP
2078platforms), or used to set up the microcode (for non-FSP platforms).
2079This all happens in the build system since it is the only way to get
2080the microcode into a single blob and accessible without SRAM.
2081
2082There are two cases to handle. If there is only one microcode blob in
2083the device tree, then the ucode pointer it set to point to that. This
2084entry (u-boot-ucode) is empty. If there is more than one update, then
2085this entry holds the concatenation of all updates, and the device tree
2086entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
2087last step ensures that that the microcode appears in one contiguous
2088block in the image and is not unnecessarily duplicated in the device
2089tree. It is referred to as 'collation' here.
2090
2091Entry types that have a part to play in handling microcode:
2092
2093 Entry_u_boot_with_ucode_ptr:
2094 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
2095 It updates it with the address and size of the microcode so that
2096 U-Boot can find it early on start-up.
2097 Entry_u_boot_dtb_with_ucode:
2098 Contains u-boot.dtb. It stores the microcode in a
2099 'self.ucode_data' property, which is then read by this class to
2100 obtain the microcode if needed. If collation is performed, it
2101 removes the microcode from the device tree.
2102 Entry_u_boot_ucode:
2103 This class. If collation is enabled it reads the microcode from
2104 the Entry_u_boot_dtb_with_ucode entry, and uses it as the
2105 contents of this entry.
2106
2107
2108
Simon Glassda6a9082023-01-07 14:07:10 -07002109.. _etype_u_boot_vpl:
2110
2111Entry: u-boot-vpl: U-Boot VPL binary
2112------------------------------------
2113
2114Properties / Entry arguments:
2115 - filename: Filename of u-boot-vpl.bin (default 'vpl/u-boot-vpl.bin')
2116
2117This is the U-Boot VPL (Verifying Program Loader) binary. This is a small
2118binary which loads before SPL, typically into on-chip SRAM. It is
2119responsible for locating, loading and jumping to SPL, the next-stage
2120loader. Note that VPL is not relocatable so must be loaded to the correct
2121address in SRAM, or written to run from the correct address if direct
2122flash execution is possible (e.g. on x86 devices).
2123
Simon Glass18ed9962023-01-07 14:07:11 -07002124SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassda6a9082023-01-07 14:07:10 -07002125
2126in the binman README for more information.
2127
2128The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2129binman uses that to look up symbols to write into the VPL binary.
2130
2131
2132
2133.. _etype_u_boot_vpl_bss_pad:
2134
2135Entry: u-boot-vpl-bss-pad: U-Boot VPL binary padded with a BSS region
2136---------------------------------------------------------------------
2137
2138Properties / Entry arguments:
2139 None
2140
2141This holds the padding added after the VPL binary to cover the BSS (Block
2142Started by Symbol) region. This region holds the various variables used by
2143VPL. It is set to 0 by VPL when it starts up. If you want to append data to
2144the VPL image (such as a device tree file), you must pad out the BSS region
2145to avoid the data overlapping with U-Boot variables. This entry is useful in
2146that case. It automatically pads out the entry size to cover both the code,
2147data and BSS.
2148
2149The contents of this entry will a certain number of zero bytes, determined
2150by __bss_size
2151
2152The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2153binman uses that to look up the BSS address.
2154
2155
2156
2157.. _etype_u_boot_vpl_dtb:
2158
2159Entry: u-boot-vpl-dtb: U-Boot VPL device tree
2160---------------------------------------------
2161
2162Properties / Entry arguments:
2163 - filename: Filename of u-boot.dtb (default 'vpl/u-boot-vpl.dtb')
2164
2165This is the VPL device tree, containing configuration information for
2166VPL. VPL needs this to know what devices are present and which drivers
2167to activate.
2168
2169
2170
2171.. _etype_u_boot_vpl_elf:
2172
2173Entry: u-boot-vpl-elf: U-Boot VPL ELF image
2174-------------------------------------------
2175
2176Properties / Entry arguments:
2177 - filename: Filename of VPL u-boot (default 'vpl/u-boot-vpl')
2178
2179This is the U-Boot VPL ELF image. It does not include a device tree but can
2180be relocated to any address for execution.
2181
2182
2183
2184.. _etype_u_boot_vpl_expanded:
2185
2186Entry: u-boot-vpl-expanded: U-Boot VPL flat binary broken out into its component parts
2187--------------------------------------------------------------------------------------
2188
2189Properties / Entry arguments:
2190 - vpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2191 select)
2192
2193This is a section containing the U-Boot binary, BSS padding if needed and a
2194devicetree. Using this entry type automatically creates this section, with
2195the following entries in it:
2196
2197 u-boot-vpl-nodtb
2198 u-boot-vpl-bss-pad
2199 u-boot-dtb
2200
2201Having the devicetree separate allows binman to update it in the final
2202image, so that the entries positions are provided to the running U-Boot.
2203
2204This entry is selected based on the value of the 'vpl-dtb' entryarg. If
2205this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2206
2207
2208
2209.. _etype_u_boot_vpl_nodtb:
2210
2211Entry: u-boot-vpl-nodtb: VPL binary without device tree appended
2212----------------------------------------------------------------
2213
2214Properties / Entry arguments:
2215 - filename: Filename to include (default 'vpl/u-boot-vpl-nodtb.bin')
2216
2217This is the U-Boot VPL binary, It does not include a device tree blob at
2218the end of it so may not be able to work without it, assuming VPL needs
2219a device tree to operate on your platform. You can add a u_boot_vpl_dtb
2220entry after this one, or use a u_boot_vpl entry instead, which normally
2221expands to a section containing u-boot-vpl-dtb, u-boot-vpl-bss-pad and
2222u-boot-vpl-dtb
2223
Simon Glass18ed9962023-01-07 14:07:11 -07002224VPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassda6a9082023-01-07 14:07:10 -07002225
2226The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2227binman uses that to look up symbols to write into the VPL binary.
2228
2229
2230
Simon Glassa7c97782022-08-07 16:33:25 -06002231.. _etype_u_boot_with_ucode_ptr:
2232
Simon Glass7a61c6b2018-07-17 13:25:37 -06002233Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
2234--------------------------------------------------------------------
2235
2236Properties / Entry arguments:
Masahiro Yamadaa7a0ca42019-12-14 13:47:26 +09002237 - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
Simon Glassee21d3a2018-09-14 04:57:07 -06002238 - optional-ucode: boolean property to make microcode optional. If the
2239 u-boot.bin image does not include microcode, no error will
2240 be generated.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002241
2242See Entry_u_boot_ucode for full details of the three entries involved in
2243this process. This entry updates U-Boot with the offset and size of the
2244microcode, to allow early x86 boot code to find it without doing anything
Simon Glass537e0062021-03-18 20:24:54 +13002245complicated. Otherwise it is the same as the u-boot entry.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002246
2247
2248
Simon Glassa7c97782022-08-07 16:33:25 -06002249.. _etype_vblock:
2250
Simon Glass5c350162018-07-17 13:25:47 -06002251Entry: vblock: An entry which contains a Chromium OS verified boot block
2252------------------------------------------------------------------------
2253
2254Properties / Entry arguments:
Simon Glass17b84eb2019-05-17 22:00:53 -06002255 - content: List of phandles to entries to sign
Simon Glass5c350162018-07-17 13:25:47 -06002256 - keydir: Directory containing the public keys to use
2257 - keyblock: Name of the key file to use (inside keydir)
2258 - signprivate: Name of provide key file to use (inside keydir)
2259 - version: Version number of the vblock (typically 1)
2260 - kernelkey: Name of the kernel key to use (inside keydir)
2261 - preamble-flags: Value of the vboot preamble flags (typically 0)
2262
Simon Glass639505b2018-09-14 04:57:11 -06002263Output files:
2264 - input.<unique_name> - input file passed to futility
2265 - vblock.<unique_name> - output file generated by futility (which is
2266 used as the entry contents)
2267
Jagdish Gediya311d4842018-09-03 21:35:08 +05302268Chromium OS signs the read-write firmware and kernel, writing the signature
Simon Glass5c350162018-07-17 13:25:47 -06002269in this block. This allows U-Boot to verify that the next firmware stage
2270and kernel are genuine.
2271
2272
2273
Simon Glassa7c97782022-08-07 16:33:25 -06002274.. _etype_x86_reset16:
2275
Simon Glass0b074d62019-08-24 07:22:48 -06002276Entry: x86-reset16: x86 16-bit reset code for U-Boot
2277----------------------------------------------------
2278
2279Properties / Entry arguments:
2280 - filename: Filename of u-boot-x86-reset16.bin (default
2281 'u-boot-x86-reset16.bin')
2282
2283x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2284must be placed at a particular address. This entry holds that code. It is
2285typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2286for jumping to the x86-start16 code, which continues execution.
2287
2288For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
2289
2290
2291
Simon Glassa7c97782022-08-07 16:33:25 -06002292.. _etype_x86_reset16_spl:
2293
Simon Glass0b074d62019-08-24 07:22:48 -06002294Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
2295--------------------------------------------------------
2296
2297Properties / Entry arguments:
2298 - filename: Filename of u-boot-x86-reset16.bin (default
2299 'u-boot-x86-reset16.bin')
2300
2301x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2302must be placed at a particular address. This entry holds that code. It is
2303typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2304for jumping to the x86-start16 code, which continues execution.
2305
2306For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
2307
2308
2309
Simon Glassa7c97782022-08-07 16:33:25 -06002310.. _etype_x86_reset16_tpl:
2311
Simon Glass0b074d62019-08-24 07:22:48 -06002312Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
2313--------------------------------------------------------
2314
2315Properties / Entry arguments:
2316 - filename: Filename of u-boot-x86-reset16.bin (default
2317 'u-boot-x86-reset16.bin')
2318
2319x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2320must be placed at a particular address. This entry holds that code. It is
2321typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2322for jumping to the x86-start16 code, which continues execution.
2323
2324For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
2325
2326
Simon Glassa7c97782022-08-07 16:33:25 -06002327
2328.. _etype_x86_start16:
Simon Glass0b074d62019-08-24 07:22:48 -06002329
Simon Glass7a61c6b2018-07-17 13:25:37 -06002330Entry: x86-start16: x86 16-bit start-up code for U-Boot
2331-------------------------------------------------------
2332
2333Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002334 - filename: Filename of u-boot-x86-start16.bin (default
2335 'u-boot-x86-start16.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002336
2337x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
Simon Glassabab18c2019-08-24 07:22:49 -06002338must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2339entry holds that code. It is typically placed at offset
2340CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2341and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2342U-Boot).
Simon Glass7a61c6b2018-07-17 13:25:37 -06002343
2344For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
2345
2346
2347
Simon Glassa7c97782022-08-07 16:33:25 -06002348.. _etype_x86_start16_spl:
2349
Simon Glass7a61c6b2018-07-17 13:25:37 -06002350Entry: x86-start16-spl: x86 16-bit start-up code for SPL
2351--------------------------------------------------------
2352
2353Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002354 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
2355 'spl/u-boot-x86-start16-spl.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002356
Simon Glassabab18c2019-08-24 07:22:49 -06002357x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2358must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2359entry holds that code. It is typically placed at offset
2360CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2361and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2362U-Boot).
Simon Glass7a61c6b2018-07-17 13:25:37 -06002363
Simon Glassabab18c2019-08-24 07:22:49 -06002364For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002365
2366
2367
Simon Glassa7c97782022-08-07 16:33:25 -06002368.. _etype_x86_start16_tpl:
2369
Simon Glassed40e962018-09-14 04:57:10 -06002370Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
2371--------------------------------------------------------
2372
2373Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002374 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
2375 'tpl/u-boot-x86-start16-tpl.bin')
Simon Glassed40e962018-09-14 04:57:10 -06002376
Simon Glassabab18c2019-08-24 07:22:49 -06002377x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2378must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2379entry holds that code. It is typically placed at offset
2380CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2381and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2382U-Boot).
Simon Glassed40e962018-09-14 04:57:10 -06002383
Simon Glassabab18c2019-08-24 07:22:49 -06002384If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
Simon Glassed40e962018-09-14 04:57:10 -06002385may be used instead.
2386
2387
2388