blob: b2fc665e471cf1686406cf1d66fe2ff34114bf09 [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
Christian Taedckebc454362023-07-17 09:05:52 +0200471.. _etype_encrypted:
472
473Entry: encrypted: Externally built encrypted binary blob
474--------------------------------------------------------
475
476This entry provides the functionality to include information about how to
477decrypt an encrypted binary. This information is added to the
478resulting device tree by adding a new cipher node in the entry's parent
479node (i.e. the binary).
480
481The key that must be used to decrypt the binary is either directly embedded
482in the device tree or indirectly by specifying a key source. The key source
483can be used as an id of a key that is stored in an external device.
484
485Using an embedded key
486~~~~~~~~~~~~~~~~~~~~~
487
488This is an example using an embedded key::
489
490 blob-ext {
491 filename = "encrypted-blob.bin";
492 };
493
494 encrypted {
495 algo = "aes256-gcm";
496 iv-filename = "encrypted-blob.bin.iv";
497 key-filename = "encrypted-blob.bin.key";
498 };
499
500This entry generates the following device tree structure form the example
501above::
502
503 data = [...]
504 cipher {
505 algo = "aes256-gcm";
506 key = <0x...>;
507 iv = <0x...>;
508 };
509
510The data property is generated by the blob-ext etype, the cipher node and
511its content is generated by this etype.
512
513Using an external key
514~~~~~~~~~~~~~~~~~~~~~
515
516Instead of embedding the key itself into the device tree, it is also
517possible to address an externally stored key by specifying a 'key-source'
518instead of the 'key'::
519
520 blob-ext {
521 filename = "encrypted-blob.bin";
522 };
523
524 encrypted {
525 algo = "aes256-gcm";
526 iv-filename = "encrypted-blob.bin.iv";
527 key-source = "external-key-id";
528 };
529
530This entry generates the following device tree structure form the example
531above::
532
533 data = [...]
534 cipher {
535 algo = "aes256-gcm";
536 key-source = "external-key-id";
537 iv = <0x...>;
538 };
539
540Properties
541~~~~~~~~~~
542
543Properties / Entry arguments:
544 - algo: The encryption algorithm. Currently no algorithm is supported
545 out-of-the-box. Certain algorithms will be added in future
546 patches.
547 - iv-filename: The name of the file containing the initialization
548 vector (in short iv). See
549 https://en.wikipedia.org/wiki/Initialization_vector
550 - key-filename: The name of the file containing the key. Either
551 key-filename or key-source must be provided.
552 - key-source: The key that should be used. Either key-filename or
553 key-source must be provided.
554
555
556
Simon Glassa7c97782022-08-07 16:33:25 -0600557.. _etype_fdtmap:
558
Simon Glass0f621332019-07-08 14:25:27 -0600559Entry: fdtmap: An entry which contains an FDT map
560-------------------------------------------------
561
562Properties / Entry arguments:
563 None
564
565An FDT map is just a header followed by an FDT containing a list of all the
Simon Glassfb30e292019-07-20 12:23:51 -0600566entries in the image. The root node corresponds to the image node in the
567original FDT, and an image-name property indicates the image name in that
568original tree.
Simon Glass0f621332019-07-08 14:25:27 -0600569
570The header is the string _FDTMAP_ followed by 8 unused bytes.
571
572When used, this entry will be populated with an FDT map which reflects the
573entries in the current image. Hierarchy is preserved, and all offsets and
574sizes are included.
575
576Note that the -u option must be provided to ensure that binman updates the
577FDT with the position of each entry.
578
Simon Glass0ac96b62021-03-18 20:25:15 +1300579Example output for a simple image with U-Boot and an FDT map::
Simon Glass0f621332019-07-08 14:25:27 -0600580
Simon Glass0ac96b62021-03-18 20:25:15 +1300581 / {
582 image-name = "binman";
583 size = <0x00000112>;
Simon Glass0f621332019-07-08 14:25:27 -0600584 image-pos = <0x00000000>;
585 offset = <0x00000000>;
Simon Glass0ac96b62021-03-18 20:25:15 +1300586 u-boot {
587 size = <0x00000004>;
588 image-pos = <0x00000000>;
589 offset = <0x00000000>;
590 };
591 fdtmap {
592 size = <0x0000010e>;
593 image-pos = <0x00000004>;
594 offset = <0x00000004>;
595 };
Simon Glass0f621332019-07-08 14:25:27 -0600596 };
Simon Glass0f621332019-07-08 14:25:27 -0600597
Simon Glassfb30e292019-07-20 12:23:51 -0600598If allow-repack is used then 'orig-offset' and 'orig-size' properties are
599added as necessary. See the binman README.
600
Simon Glass637958f2021-11-23 21:09:50 -0700601When extracting files, an alternative 'fdt' format is available for fdtmaps.
602Use `binman extract -F fdt ...` to use this. It will export a devicetree,
603without the fdtmap header, so it can be viewed with `fdtdump`.
Simon Glass0f621332019-07-08 14:25:27 -0600604
605
Simon Glass637958f2021-11-23 21:09:50 -0700606
Simon Glassa7c97782022-08-07 16:33:25 -0600607.. _etype_files:
608
Simon Glass8911fa12021-03-18 20:25:16 +1300609Entry: files: A set of files arranged in a section
610--------------------------------------------------
Simon Glassac6328c2018-09-14 04:57:28 -0600611
612Properties / Entry arguments:
613 - pattern: Filename pattern to match the files to include
Simon Glass51d02ad2020-10-26 17:40:07 -0600614 - files-compress: Compression algorithm to use:
Simon Glassac6328c2018-09-14 04:57:28 -0600615 none: No compression
616 lz4: Use lz4 compression (via 'lz4' command-line utility)
Simon Glass3f093a32021-03-18 20:24:53 +1300617 - files-align: Align each file to the given alignment
Simon Glassac6328c2018-09-14 04:57:28 -0600618
619This entry reads a number of files and places each in a separate sub-entry
620within this entry. To access these you need to enable device-tree updates
621at run-time so you can obtain the file positions.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600622
623
Simon Glassac6328c2018-09-14 04:57:28 -0600624
Simon Glassa7c97782022-08-07 16:33:25 -0600625.. _etype_fill:
626
Simon Glass53f53992018-07-17 13:25:40 -0600627Entry: fill: An entry which is filled to a particular byte value
628----------------------------------------------------------------
629
630Properties / Entry arguments:
631 - fill-byte: Byte to use to fill the entry
632
633Note that the size property must be set since otherwise this entry does not
634know how large it should be.
635
636You can often achieve the same effect using the pad-byte property of the
637overall image, in that the space between entries will then be padded with
638that byte. But this entry is sometimes useful for explicitly setting the
639byte value of a region.
640
641
Simon Glassc7b010d2020-07-09 18:39:45 -0600642
Simon Glassa7c97782022-08-07 16:33:25 -0600643.. _etype_fit:
644
Simon Glass8911fa12021-03-18 20:25:16 +1300645Entry: fit: Flat Image Tree (FIT)
646---------------------------------
Simon Glass45d556d2020-07-09 18:39:45 -0600647
648This calls mkimage to create a FIT (U-Boot Flat Image Tree) based on the
649input provided.
650
651Nodes for the FIT should be written out in the binman configuration just as
652they would be in a file passed to mkimage.
653
Simon Glass0ac96b62021-03-18 20:25:15 +1300654For example, this creates an image containing a FIT with U-Boot SPL::
Simon Glass45d556d2020-07-09 18:39:45 -0600655
656 binman {
657 fit {
658 description = "Test FIT";
Simon Glassa435cd12020-09-01 05:13:59 -0600659 fit,fdt-list = "of-list";
Simon Glass45d556d2020-07-09 18:39:45 -0600660
661 images {
662 kernel@1 {
663 description = "SPL";
664 os = "u-boot";
665 type = "rkspi";
666 arch = "arm";
667 compression = "none";
668 load = <0>;
669 entry = <0>;
670
671 u-boot-spl {
672 };
673 };
674 };
675 };
676 };
677
Simon Glass912339f2022-02-08 11:50:03 -0700678More complex setups can be created, with generated nodes, as described
679below.
680
681Properties (in the 'fit' node itself)
682~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
683
684Special properties have a `fit,` prefix, indicating that they should be
685processed but not included in the final FIT.
686
687The top-level 'fit' node supports the following special properties:
688
689 fit,external-offset
690 Indicates that the contents of the FIT are external and provides the
691 external offset. This is passed to mkimage via the -E and -p flags.
692
Jonas Karlmanc59ea892023-01-21 19:01:39 +0000693 fit,align
694 Indicates what alignment to use for the FIT and its external data,
695 and provides the alignment to use. This is passed to mkimage via
696 the -B flag.
697
Simon Glass912339f2022-02-08 11:50:03 -0700698 fit,fdt-list
699 Indicates the entry argument which provides the list of device tree
700 files for the gen-fdt-nodes operation (as below). This is often
701 `of-list` meaning that `-a of-list="dtb1 dtb2..."` should be passed
702 to binman.
703
Simon Glass2d94c422023-07-18 07:23:59 -0600704 fit,fdt-list-val
705 As an alternative to fit,fdt-list the list of device tree files
706 can be provided in this property as a string list, e.g.::
707
708 fit,fdt-list-val = "dtb1", "dtb2";
709
Simon Glass912339f2022-02-08 11:50:03 -0700710Substitutions
711~~~~~~~~~~~~~
712
713Node names and property values support a basic string-substitution feature.
714Available substitutions for '@' nodes (and property values) are:
715
716SEQ:
717 Sequence number of the generated fdt (1, 2, ...)
718NAME
719 Name of the dtb as provided (i.e. without adding '.dtb')
720
721The `default` property, if present, will be automatically set to the name
722if of configuration whose devicetree matches the `default-dt` entry
723argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.
724
725Available substitutions for property values in these nodes are:
726
727DEFAULT-SEQ:
728 Sequence number of the default fdt, as provided by the 'default-dt'
729 entry argument
730
731Available operations
732~~~~~~~~~~~~~~~~~~~~
733
734You can add an operation to an '@' node to indicate which operation is
735required::
736
737 @fdt-SEQ {
738 fit,operation = "gen-fdt-nodes";
739 ...
740 };
741
742Available operations are:
743
744gen-fdt-nodes
745 Generate FDT nodes as above. This is the default if there is no
746 `fit,operation` property.
747
Simon Glass5f423422022-03-05 20:19:12 -0700748split-elf
749 Split an ELF file into a separate node for each segment.
750
Simon Glass912339f2022-02-08 11:50:03 -0700751Generating nodes from an FDT list (gen-fdt-nodes)
752~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
753
Simon Glassa435cd12020-09-01 05:13:59 -0600754U-Boot supports creating fdt and config nodes automatically. To do this,
Simon Glass9f1c6b92022-02-08 11:50:02 -0700755pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells
756binman that you want to generates nodes for two files: `file1.dtb` and
757`file2.dtb`. The `fit,fdt-list` property (see above) indicates that
758`of-list` should be used. If the property is missing you will get an error.
Simon Glassa435cd12020-09-01 05:13:59 -0600759
Simon Glass0ac96b62021-03-18 20:25:15 +1300760Then add a 'generator node', a node with a name starting with '@'::
Simon Glassa435cd12020-09-01 05:13:59 -0600761
762 images {
763 @fdt-SEQ {
764 description = "fdt-NAME";
765 type = "flat_dt";
766 compression = "none";
767 };
768 };
769
Simon Glass9f1c6b92022-02-08 11:50:02 -0700770This tells binman to create nodes `fdt-1` and `fdt-2` for each of your two
Simon Glassa435cd12020-09-01 05:13:59 -0600771files. All the properties you specify will be included in the node. This
772node acts like a template to generate the nodes. The generator node itself
773does not appear in the output - it is replaced with what binman generates.
Simon Glass9f1c6b92022-02-08 11:50:02 -0700774A 'data' property is created with the contents of the FDT file.
Simon Glassa435cd12020-09-01 05:13:59 -0600775
Simon Glass0ac96b62021-03-18 20:25:15 +1300776You can create config nodes in a similar way::
Simon Glassa435cd12020-09-01 05:13:59 -0600777
778 configurations {
779 default = "@config-DEFAULT-SEQ";
780 @config-SEQ {
781 description = "NAME";
Samuel Holland91079ac2020-10-21 21:12:14 -0500782 firmware = "atf";
783 loadables = "uboot";
Simon Glassa435cd12020-09-01 05:13:59 -0600784 fdt = "fdt-SEQ";
785 };
786 };
787
Simon Glass9f1c6b92022-02-08 11:50:02 -0700788This tells binman to create nodes `config-1` and `config-2`, i.e. a config
789for each of your two files.
Simon Glassa435cd12020-09-01 05:13:59 -0600790
Simon Glassa435cd12020-09-01 05:13:59 -0600791Note that if no devicetree files are provided (with '-a of-list' as above)
792then no nodes will be generated.
793
Simon Glass5f423422022-03-05 20:19:12 -0700794Generating nodes from an ELF file (split-elf)
795~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
796
797This uses the node as a template to generate multiple nodes. The following
798special properties are available:
799
800split-elf
801 Split an ELF file into a separate node for each segment. This uses the
802 node as a template to generate multiple nodes. The following special
803 properties are available:
804
805 fit,load
806 Generates a `load = <...>` property with the load address of the
807 segment
808
809 fit,entry
810 Generates a `entry = <...>` property with the entry address of the
811 ELF. This is only produced for the first entry
812
813 fit,data
814 Generates a `data = <...>` property with the contents of the segment
815
Jonas Karlman490f73c2023-01-21 19:02:12 +0000816 fit,firmware
817 Generates a `firmware = <...>` property. Provides a list of possible
818 nodes to be used as the `firmware` property value. The first valid
819 node is picked as the firmware. Any remaining valid nodes is
820 prepended to the `loadable` property generated by `fit,loadables`
821
Simon Glass5f423422022-03-05 20:19:12 -0700822 fit,loadables
823 Generates a `loadable = <...>` property with a list of the generated
824 nodes (including all nodes if this operation is used multiple times)
825
826
827Here is an example showing ATF, TEE and a device tree all combined::
828
829 fit {
830 description = "test-desc";
831 #address-cells = <1>;
832 fit,fdt-list = "of-list";
833
834 images {
835 u-boot {
836 description = "U-Boot (64-bit)";
837 type = "standalone";
838 os = "U-Boot";
839 arch = "arm64";
840 compression = "none";
Simon Glass72cc5382022-10-20 18:22:39 -0600841 load = <CONFIG_TEXT_BASE>;
Simon Glass5f423422022-03-05 20:19:12 -0700842 u-boot-nodtb {
843 };
844 };
845 @fdt-SEQ {
846 description = "fdt-NAME.dtb";
847 type = "flat_dt";
848 compression = "none";
849 };
850 @atf-SEQ {
851 fit,operation = "split-elf";
852 description = "ARM Trusted Firmware";
853 type = "firmware";
854 arch = "arm64";
855 os = "arm-trusted-firmware";
856 compression = "none";
857 fit,load;
858 fit,entry;
859 fit,data;
860
861 atf-bl31 {
862 };
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000863 hash {
864 algo = "sha256";
865 };
Simon Glass5f423422022-03-05 20:19:12 -0700866 };
867
868 @tee-SEQ {
869 fit,operation = "split-elf";
870 description = "TEE";
871 type = "tee";
872 arch = "arm64";
873 os = "tee";
874 compression = "none";
875 fit,load;
876 fit,entry;
877 fit,data;
878
879 tee-os {
880 };
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000881 hash {
882 algo = "sha256";
883 };
Simon Glass5f423422022-03-05 20:19:12 -0700884 };
885 };
886
887 configurations {
888 default = "@config-DEFAULT-SEQ";
889 @config-SEQ {
890 description = "conf-NAME.dtb";
891 fdt = "fdt-SEQ";
Jonas Karlman490f73c2023-01-21 19:02:12 +0000892 fit,firmware = "atf-1", "u-boot";
Simon Glass5f423422022-03-05 20:19:12 -0700893 fit,loadables;
894 };
895 };
896 };
897
898If ATF-BL31 is available, this generates a node for each segment in the
899ELF file, for example::
900
901 images {
902 atf-1 {
903 data = <...contents of first segment...>;
904 data-offset = <0x00000000>;
905 entry = <0x00040000>;
906 load = <0x00040000>;
907 compression = "none";
908 os = "arm-trusted-firmware";
909 arch = "arm64";
910 type = "firmware";
911 description = "ARM Trusted Firmware";
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000912 hash {
913 algo = "sha256";
914 value = <...hash of first segment...>;
915 };
Simon Glass5f423422022-03-05 20:19:12 -0700916 };
917 atf-2 {
918 data = <...contents of second segment...>;
919 load = <0xff3b0000>;
920 compression = "none";
921 os = "arm-trusted-firmware";
922 arch = "arm64";
923 type = "firmware";
924 description = "ARM Trusted Firmware";
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000925 hash {
926 algo = "sha256";
927 value = <...hash of second segment...>;
928 };
Simon Glass5f423422022-03-05 20:19:12 -0700929 };
930 };
931
932The same applies for OP-TEE if that is available.
933
934If each binary is not available, the relevant template node (@atf-SEQ or
935@tee-SEQ) is removed from the output.
936
937This also generates a `config-xxx` node for each device tree in `of-list`.
938Note that the U-Boot build system uses `-a of-list=$(CONFIG_OF_LIST)`
939so you can use `CONFIG_OF_LIST` to define that list. In this example it is
940set up for `firefly-rk3399` with a single device tree and the default set
941with `-a default-dt=$(CONFIG_DEFAULT_DEVICE_TREE)`, so the resulting output
942is::
943
944 configurations {
945 default = "config-1";
946 config-1 {
Jonas Karlman490f73c2023-01-21 19:02:12 +0000947 loadables = "u-boot", "atf-2", "atf-3", "tee-1", "tee-2";
Simon Glass5f423422022-03-05 20:19:12 -0700948 description = "rk3399-firefly.dtb";
949 fdt = "fdt-1";
Jonas Karlman490f73c2023-01-21 19:02:12 +0000950 firmware = "atf-1";
Simon Glass5f423422022-03-05 20:19:12 -0700951 };
952 };
953
Jonas Karlman490f73c2023-01-21 19:02:12 +0000954U-Boot SPL can then load the firmware (ATF) and all the loadables (U-Boot
955proper, ATF and TEE), then proceed with the boot.
Simon Glass5f423422022-03-05 20:19:12 -0700956
Simon Glass45d556d2020-07-09 18:39:45 -0600957
Simon Glassa7c97782022-08-07 16:33:25 -0600958
959.. _etype_fmap:
Simon Glass45d556d2020-07-09 18:39:45 -0600960
Simon Glass7a61c6b2018-07-17 13:25:37 -0600961Entry: fmap: An entry which contains an Fmap section
962----------------------------------------------------
963
964Properties / Entry arguments:
965 None
966
967FMAP is a simple format used by flashrom, an open-source utility for
968reading and writing the SPI flash, typically on x86 CPUs. The format
969provides flashrom with a list of areas, so it knows what it in the flash.
970It can then read or write just a single area, instead of the whole flash.
971
972The format is defined by the flashrom project, in the file lib/fmap.h -
973see www.flashrom.org/Flashrom for more information.
974
975When used, this entry will be populated with an FMAP which reflects the
976entries in the current image. Note that any hierarchy is squashed, since
Simon Glassb1d414c2021-04-03 11:05:10 +1300977FMAP does not support this. Sections are represented as an area appearing
978before its contents, so that it is possible to reconstruct the hierarchy
979from the FMAP by using the offset information. This convention does not
980seem to be documented, but is used in Chromium OS.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600981
Simon Glasscda991e2023-02-12 17:11:15 -0700982To mark an area as preserved, use the normal 'preserved' flag in the entry.
983This will result in the corresponding FMAP area having the
984FMAP_AREA_PRESERVE flag. This flag does not automatically propagate down to
985child entries.
986
Simon Glassb1d414c2021-04-03 11:05:10 +1300987CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600988
989
Simon Glassb1d414c2021-04-03 11:05:10 +1300990
Simon Glassa7c97782022-08-07 16:33:25 -0600991.. _etype_gbb:
992
Simon Glassc1ae83c2018-07-17 13:25:44 -0600993Entry: gbb: An entry which contains a Chromium OS Google Binary Block
994---------------------------------------------------------------------
995
996Properties / Entry arguments:
997 - hardware-id: Hardware ID to use for this build (a string)
998 - keydir: Directory containing the public keys to use
999 - bmpblk: Filename containing images used by recovery
1000
1001Chromium OS uses a GBB to store various pieces of information, in particular
1002the root and recovery keys that are used to verify the boot process. Some
1003more details are here:
1004
1005 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
1006
1007but note that the page dates from 2013 so is quite out of date. See
1008README.chromium for how to obtain the required keys and tools.
1009
1010
Simon Glassa7c97782022-08-07 16:33:25 -06001011
1012.. _etype_image_header:
Simon Glassc1ae83c2018-07-17 13:25:44 -06001013
Simon Glasscec34ba2019-07-08 14:25:28 -06001014Entry: image-header: An entry which contains a pointer to the FDT map
1015---------------------------------------------------------------------
1016
1017Properties / Entry arguments:
1018 location: Location of header ("start" or "end" of image). This is
1019 optional. If omitted then the entry must have an offset property.
1020
1021This adds an 8-byte entry to the start or end of the image, pointing to the
1022location of the FDT map. The format is a magic number followed by an offset
1023from the start or end of the image, in twos-compliment format.
1024
1025This entry must be in the top-level part of the image.
1026
1027NOTE: If the location is at the start/end, you will probably need to specify
1028sort-by-offset for the image, unless you actually put the image header
1029first/last in the entry list.
1030
1031
1032
Simon Glassa7c97782022-08-07 16:33:25 -06001033.. _etype_intel_cmc:
1034
Simon Glass8911fa12021-03-18 20:25:16 +13001035Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
1036-----------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001037
1038Properties / Entry arguments:
1039 - filename: Filename of file to read into entry
1040
1041This file contains microcode for some devices in a special format. An
1042example filename is 'Microcode/C0_22211.BIN'.
1043
1044See README.x86 for information about x86 binary blobs.
1045
1046
1047
Simon Glassa7c97782022-08-07 16:33:25 -06001048.. _etype_intel_descriptor:
1049
Simon Glass7a61c6b2018-07-17 13:25:37 -06001050Entry: intel-descriptor: Intel flash descriptor block (4KB)
1051-----------------------------------------------------------
1052
1053Properties / Entry arguments:
1054 filename: Filename of file containing the descriptor. This is typically
1055 a 4KB binary file, sometimes called 'descriptor.bin'
1056
1057This entry is placed at the start of flash and provides information about
1058the SPI flash regions. In particular it provides the base address and
1059size of the ME (Management Engine) region, allowing us to place the ME
1060binary in the right place.
1061
1062With this entry in your image, the position of the 'intel-me' entry will be
1063fixed in the image, which avoids you needed to specify an offset for that
1064region. This is useful, because it is not possible to change the position
1065of the ME region without updating the descriptor.
1066
1067See README.x86 for information about x86 binary blobs.
1068
1069
1070
Simon Glassa7c97782022-08-07 16:33:25 -06001071.. _etype_intel_fit:
1072
Simon Glass232f90c2019-08-24 07:22:50 -06001073Entry: intel-fit: Intel Firmware Image Table (FIT)
1074--------------------------------------------------
1075
1076This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
1077contains information about the firmware and microcode available in the
1078image.
1079
1080At present binman only supports a basic FIT with no microcode.
1081
1082
1083
Simon Glassa7c97782022-08-07 16:33:25 -06001084.. _etype_intel_fit_ptr:
1085
Simon Glass232f90c2019-08-24 07:22:50 -06001086Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
1087--------------------------------------------------------------
1088
1089This entry contains a pointer to the FIT. It is required to be at address
10900xffffffc0 in the image.
1091
1092
1093
Simon Glassa7c97782022-08-07 16:33:25 -06001094.. _etype_intel_fsp:
1095
Simon Glass8911fa12021-03-18 20:25:16 +13001096Entry: intel-fsp: Intel Firmware Support Package (FSP) file
1097-----------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001098
1099Properties / Entry arguments:
1100 - filename: Filename of file to read into entry
1101
1102This file contains binary blobs which are used on some devices to make the
1103platform work. U-Boot executes this code since it is not possible to set up
1104the hardware using U-Boot open-source code. Documentation is typically not
1105available in sufficient detail to allow this.
1106
1107An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
1108
1109See README.x86 for information about x86 binary blobs.
1110
1111
1112
Simon Glassa7c97782022-08-07 16:33:25 -06001113.. _etype_intel_fsp_m:
1114
Simon Glass8911fa12021-03-18 20:25:16 +13001115Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
1116--------------------------------------------------------------------
Simon Glassba7985d2019-08-24 07:23:07 -06001117
1118Properties / Entry arguments:
1119 - filename: Filename of file to read into entry
1120
1121This file contains a binary blob which is used on some devices to set up
1122SDRAM. U-Boot executes this code in SPL so that it can make full use of
1123memory. Documentation is typically not available in sufficient detail to
1124allow U-Boot do this this itself..
1125
1126An example filename is 'fsp_m.bin'
1127
1128See README.x86 for information about x86 binary blobs.
1129
1130
Simon Glassa7c97782022-08-07 16:33:25 -06001131
1132.. _etype_intel_fsp_s:
Simon Glassba7985d2019-08-24 07:23:07 -06001133
Simon Glass8911fa12021-03-18 20:25:16 +13001134Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
1135---------------------------------------------------------------------
Simon Glass4d9086d2019-10-20 21:31:35 -06001136
1137Properties / Entry arguments:
1138 - filename: Filename of file to read into entry
1139
1140This file contains a binary blob which is used on some devices to set up
1141the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
1142running, so that it can make full use of memory. Documentation is typically
1143not available in sufficient detail to allow U-Boot do this this itself.
1144
1145An example filename is 'fsp_s.bin'
1146
1147See README.x86 for information about x86 binary blobs.
1148
1149
1150
Simon Glassa7c97782022-08-07 16:33:25 -06001151.. _etype_intel_fsp_t:
1152
Simon Glass8911fa12021-03-18 20:25:16 +13001153Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
1154----------------------------------------------------------------------
Simon Glass9ea87b22019-10-20 21:31:36 -06001155
1156Properties / Entry arguments:
1157 - filename: Filename of file to read into entry
1158
1159This file contains a binary blob which is used on some devices to set up
1160temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
1161that it has access to memory for its stack and initial storage.
1162
1163An example filename is 'fsp_t.bin'
1164
1165See README.x86 for information about x86 binary blobs.
1166
1167
Simon Glassa7c97782022-08-07 16:33:25 -06001168
1169.. _etype_intel_ifwi:
Simon Glass9ea87b22019-10-20 21:31:36 -06001170
Simon Glass8911fa12021-03-18 20:25:16 +13001171Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
1172--------------------------------------------------------------
Simon Glassc2f1aed2019-07-08 13:18:56 -06001173
1174Properties / Entry arguments:
1175 - filename: Filename of file to read into entry. This is either the
1176 IFWI file itself, or a file that can be converted into one using a
1177 tool
1178 - convert-fit: If present this indicates that the ifwitool should be
1179 used to convert the provided file into a IFWI.
1180
1181This file contains code and data used by the SoC that is required to make
1182it work. It includes U-Boot TPL, microcode, things related to the CSE
1183(Converged Security Engine, the microcontroller that loads all the firmware)
1184and other items beyond the wit of man.
1185
1186A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
1187file that will be converted to an IFWI.
1188
1189The position of this entry is generally set by the intel-descriptor entry.
1190
1191The contents of the IFWI are specified by the subnodes of the IFWI node.
1192Each subnode describes an entry which is placed into the IFWFI with a given
1193sub-partition (and optional entry name).
1194
Simon Glass8a5e2492019-08-24 07:22:47 -06001195Properties for subnodes:
Simon Glass0ac96b62021-03-18 20:25:15 +13001196 - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
1197 - ifwi-entry: entry name t use, e.g. "IBBL"
1198 - ifwi-replace: if present, indicates that the item should be replaced
1199 in the IFWI. Otherwise it is added.
Simon Glass8a5e2492019-08-24 07:22:47 -06001200
Simon Glassc2f1aed2019-07-08 13:18:56 -06001201See README.x86 for information about x86 binary blobs.
1202
1203
1204
Simon Glassa7c97782022-08-07 16:33:25 -06001205.. _etype_intel_me:
1206
Simon Glass8911fa12021-03-18 20:25:16 +13001207Entry: intel-me: Intel Management Engine (ME) file
1208--------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001209
1210Properties / Entry arguments:
1211 - filename: Filename of file to read into entry
1212
1213This file contains code used by the SoC that is required to make it work.
1214The Management Engine is like a background task that runs things that are
Thomas Hebbfd37f242019-11-13 18:18:03 -08001215not clearly documented, but may include keyboard, display and network
Simon Glass7a61c6b2018-07-17 13:25:37 -06001216access. For platform that use ME it is not possible to disable it. U-Boot
1217does not directly execute code in the ME binary.
1218
1219A typical filename is 'me.bin'.
1220
Simon Glassc4056b82019-07-08 13:18:38 -06001221The position of this entry is generally set by the intel-descriptor entry.
1222
Simon Glass7a61c6b2018-07-17 13:25:37 -06001223See README.x86 for information about x86 binary blobs.
1224
1225
1226
Simon Glassa7c97782022-08-07 16:33:25 -06001227.. _etype_intel_mrc:
1228
Simon Glass8911fa12021-03-18 20:25:16 +13001229Entry: intel-mrc: Intel Memory Reference Code (MRC) file
1230--------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001231
1232Properties / Entry arguments:
1233 - filename: Filename of file to read into entry
1234
1235This file contains code for setting up the SDRAM on some Intel systems. This
1236is executed by U-Boot when needed early during startup. A typical filename
1237is 'mrc.bin'.
1238
1239See README.x86 for information about x86 binary blobs.
1240
1241
1242
Simon Glassa7c97782022-08-07 16:33:25 -06001243.. _etype_intel_refcode:
1244
Simon Glass8911fa12021-03-18 20:25:16 +13001245Entry: intel-refcode: Intel Reference Code file
1246-----------------------------------------------
Simon Glass17b84eb2019-05-17 22:00:53 -06001247
1248Properties / Entry arguments:
1249 - filename: Filename of file to read into entry
1250
1251This file contains code for setting up the platform on some Intel systems.
1252This is executed by U-Boot when needed early during startup. A typical
1253filename is 'refcode.bin'.
1254
1255See README.x86 for information about x86 binary blobs.
1256
1257
1258
Simon Glassa7c97782022-08-07 16:33:25 -06001259.. _etype_intel_vbt:
1260
Simon Glass8911fa12021-03-18 20:25:16 +13001261Entry: intel-vbt: Intel Video BIOS Table (VBT) file
1262---------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001263
1264Properties / Entry arguments:
1265 - filename: Filename of file to read into entry
1266
1267This file contains code that sets up the integrated graphics subsystem on
1268some Intel SoCs. U-Boot executes this when the display is started up.
1269
1270See README.x86 for information about Intel binary blobs.
1271
1272
1273
Simon Glassa7c97782022-08-07 16:33:25 -06001274.. _etype_intel_vga:
1275
Simon Glass8911fa12021-03-18 20:25:16 +13001276Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
1277---------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001278
1279Properties / Entry arguments:
1280 - filename: Filename of file to read into entry
1281
1282This file contains code that sets up the integrated graphics subsystem on
1283some Intel SoCs. U-Boot executes this when the display is started up.
1284
1285This is similar to the VBT file but in a different format.
1286
1287See README.x86 for information about Intel binary blobs.
1288
1289
1290
Simon Glassa7c97782022-08-07 16:33:25 -06001291.. _etype_mkimage:
1292
Simon Glass8911fa12021-03-18 20:25:16 +13001293Entry: mkimage: Binary produced by mkimage
1294------------------------------------------
Simon Glass48f3aad2020-07-09 18:39:31 -06001295
1296Properties / Entry arguments:
Simon Glass42074dc2022-08-13 11:40:47 -06001297 - args: Arguments to pass
Simon Glass8fbca772022-08-13 11:40:48 -06001298 - data-to-imagename: Indicates that the -d data should be passed in as
1299 the image name also (-n)
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001300 - multiple-data-files: boolean to tell binman to pass all files as
1301 datafiles to mkimage instead of creating a temporary file the result
1302 of datafiles concatenation
Simon Glassda6a9082023-01-07 14:07:10 -07001303 - filename: filename of output binary generated by mkimage
Simon Glass48f3aad2020-07-09 18:39:31 -06001304
Simon Glass42074dc2022-08-13 11:40:47 -06001305The data passed to mkimage via the -d flag is collected from subnodes of the
1306mkimage node, e.g.::
Simon Glass48f3aad2020-07-09 18:39:31 -06001307
1308 mkimage {
Simon Glassda6a9082023-01-07 14:07:10 -07001309 filename = "imximage.bin";
Simon Glass48f3aad2020-07-09 18:39:31 -06001310 args = "-n test -T imximage";
1311
1312 u-boot-spl {
1313 };
1314 };
1315
Simon Glass42074dc2022-08-13 11:40:47 -06001316This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
Simon Glassda6a9082023-01-07 14:07:10 -07001317file, with mkimage being called like this::
Simon Glass42074dc2022-08-13 11:40:47 -06001318
1319 mkimage -d <data_file> -n test -T imximage <output_file>
1320
1321The output from mkimage then becomes part of the image produced by
Simon Glassda6a9082023-01-07 14:07:10 -07001322binman but also is written into `imximage.bin` file. If you need to put
1323multiple things in the data file, you can use a section, or just multiple
1324subnodes like this::
Simon Glass42074dc2022-08-13 11:40:47 -06001325
1326 mkimage {
1327 args = "-n test -T imximage";
1328
1329 u-boot-spl {
1330 };
1331
1332 u-boot-tpl {
1333 };
1334 };
Simon Glass48f3aad2020-07-09 18:39:31 -06001335
Simon Glassda6a9082023-01-07 14:07:10 -07001336Note that binman places the contents (here SPL and TPL) into a single file
1337and passes that to mkimage using the -d option.
1338
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001339To pass all datafiles untouched to mkimage::
1340
1341 mkimage {
Simon Glassda6a9082023-01-07 14:07:10 -07001342 args = "-n rk3399 -T rkspi";
1343 multiple-data-files;
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001344
Simon Glassda6a9082023-01-07 14:07:10 -07001345 u-boot-tpl {
1346 };
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001347
Simon Glassda6a9082023-01-07 14:07:10 -07001348 u-boot-spl {
1349 };
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001350 };
1351
1352This calls mkimage to create a Rockchip RK3399-specific first stage
1353bootloader, made of TPL+SPL. Since this first stage bootloader requires to
1354align the TPL and SPL but also some weird hacks that is handled by mkimage
1355directly, binman is told to not perform the concatenation of datafiles prior
1356to passing the data to mkimage.
1357
Simon Glass948dd3a2022-02-08 11:49:58 -07001358To use CONFIG options in the arguments, use a string list instead, as in
1359this example which also produces four arguments::
1360
1361 mkimage {
1362 args = "-n", CONFIG_SYS_SOC, "-T imximage";
1363
1364 u-boot-spl {
1365 };
1366 };
1367
Simon Glass8fbca772022-08-13 11:40:48 -06001368If you need to pass the input data in with the -n argument as well, then use
1369the 'data-to-imagename' property::
1370
1371 mkimage {
1372 args = "-T imximage";
Simon Glassda6a9082023-01-07 14:07:10 -07001373 data-to-imagename;
Simon Glass8fbca772022-08-13 11:40:48 -06001374
1375 u-boot-spl {
1376 };
1377 };
1378
1379That will pass the data to mkimage both as the data file (with -d) and as
Simon Glassda6a9082023-01-07 14:07:10 -07001380the image name (with -n). In both cases, a filename is passed as the
1381argument, with the actual data being in that file.
Simon Glass948dd3a2022-02-08 11:49:58 -07001382
Simon Glassda6a9082023-01-07 14:07:10 -07001383If need to pass different data in with -n, then use an `imagename` subnode::
Simon Glassb1669752022-08-13 11:40:49 -06001384
1385 mkimage {
1386 args = "-T imximage";
1387
1388 imagename {
1389 blob {
1390 filename = "spl/u-boot-spl.cfgout"
1391 };
1392 };
1393
1394 u-boot-spl {
1395 };
1396 };
1397
1398This will pass in u-boot-spl as the input data and the .cfgout file as the
1399-n data.
1400
Simon Glassa7c97782022-08-07 16:33:25 -06001401
Simon Glassda6a9082023-01-07 14:07:10 -07001402
Simon Glassa4948b22023-01-11 16:10:14 -07001403.. _etype_null:
1404
1405Entry: null: An entry which has no contents of its own
1406------------------------------------------------------
1407
1408Note that the size property must be set since otherwise this entry does not
1409know how large it should be.
1410
1411The contents are set by the containing section, e.g. the section's pad
1412byte.
1413
1414
1415
Simon Glassa7c97782022-08-07 16:33:25 -06001416.. _etype_opensbi:
Simon Glass48f3aad2020-07-09 18:39:31 -06001417
Bin Mengc0b15742021-05-10 20:23:33 +08001418Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
1419----------------------------------------------
1420
1421Properties / Entry arguments:
1422 - opensbi-path: Filename of file to read into entry. This is typically
1423 called fw_dynamic.bin
1424
1425This entry holds the run-time firmware, typically started by U-Boot SPL.
1426See the U-Boot README for your architecture or board for how to use it. See
1427https://github.com/riscv/opensbi for more information about OpenSBI.
1428
1429
1430
Simon Glassa7c97782022-08-07 16:33:25 -06001431.. _etype_powerpc_mpc85xx_bootpg_resetvec:
1432
Jagdish Gediya311d4842018-09-03 21:35:08 +05301433Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
1434-----------------------------------------------------------------------------------------
1435
1436Properties / Entry arguments:
1437 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
1438
Thomas Hebbfd37f242019-11-13 18:18:03 -08001439This entry is valid for PowerPC mpc85xx cpus. This entry holds
Jagdish Gediya311d4842018-09-03 21:35:08 +05301440'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
1441placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
1442
Simon Glass136dd352020-10-26 17:39:59 -06001443
Simon Glassa7c97782022-08-07 16:33:25 -06001444
1445.. _etype_pre_load:
Simon Glass136dd352020-10-26 17:39:59 -06001446
Philippe Reynesebe96cb2022-03-28 22:57:04 +02001447Entry: pre-load: Pre load image header
1448--------------------------------------
1449
1450Properties / Entry arguments:
Simon Glass9f571582022-08-13 11:40:43 -06001451 - pre-load-key-path: Path of the directory that store key (provided by
1452 the environment variable PRE_LOAD_KEY_PATH)
Philippe Reynesebe96cb2022-03-28 22:57:04 +02001453 - content: List of phandles to entries to sign
1454 - algo-name: Hash and signature algo to use for the signature
1455 - padding-name: Name of the padding (pkcs-1.5 or pss)
1456 - key-name: Filename of the private key to sign
1457 - header-size: Total size of the header
1458 - version: Version of the header
1459
1460This entry creates a pre-load header that contains a global
1461image signature.
1462
1463For example, this creates an image with a pre-load header and a binary::
1464
1465 binman {
1466 image2 {
1467 filename = "sandbox.bin";
1468
1469 pre-load {
1470 content = <&image>;
1471 algo-name = "sha256,rsa2048";
1472 padding-name = "pss";
1473 key-name = "private.pem";
1474 header-size = <4096>;
1475 version = <1>;
1476 };
1477
1478 image: blob-ext {
1479 filename = "sandbox.itb";
1480 };
1481 };
1482 };
1483
1484
1485
Jonas Karlman35305492023-02-25 19:01:33 +00001486.. _etype_rockchip_tpl:
1487
1488Entry: rockchip-tpl: Rockchip TPL binary
1489----------------------------------------
1490
1491Properties / Entry arguments:
1492 - rockchip-tpl-path: Filename of file to read into the entry,
1493 typically <soc>_ddr_<version>.bin
1494
1495This entry holds an external TPL binary used by some Rockchip SoCs
1496instead of normal U-Boot TPL, typically to initialize DRAM.
1497
1498
1499
Simon Glassa7c97782022-08-07 16:33:25 -06001500.. _etype_scp:
1501
Simon Glass8911fa12021-03-18 20:25:16 +13001502Entry: scp: System Control Processor (SCP) firmware blob
1503--------------------------------------------------------
Simon Glass136dd352020-10-26 17:39:59 -06001504
1505Properties / Entry arguments:
1506 - scp-path: Filename of file to read into the entry, typically scp.bin
1507
1508This entry holds firmware for an external platform-specific coprocessor.
Jagdish Gediya311d4842018-09-03 21:35:08 +05301509
1510
Simon Glass136dd352020-10-26 17:39:59 -06001511
Simon Glassa7c97782022-08-07 16:33:25 -06001512.. _etype_section:
1513
Simon Glass7a61c6b2018-07-17 13:25:37 -06001514Entry: section: Entry that contains other entries
1515-------------------------------------------------
1516
Simon Glasscc9a41c2021-11-23 11:03:49 -07001517A section is an entry which can contain other entries, thus allowing
1518hierarchical images to be created. See 'Sections and hierarchical images'
1519in the binman README for more information.
1520
1521The base implementation simply joins the various entries together, using
1522various rules about alignment, etc.
1523
1524Subclassing
1525~~~~~~~~~~~
1526
1527This class can be subclassed to support other file formats which hold
1528multiple entries, such as CBFS. To do this, override the following
1529functions. The documentation here describes what your function should do.
1530For example code, see etypes which subclass `Entry_section`, or `cbfs.py`
1531for a more involved example::
1532
1533 $ grep -l \(Entry_section tools/binman/etype/*.py
1534
1535ReadNode()
1536 Call `super().ReadNode()`, then read any special properties for the
1537 section. Then call `self.ReadEntries()` to read the entries.
1538
1539 Binman calls this at the start when reading the image description.
1540
1541ReadEntries()
1542 Read in the subnodes of the section. This may involve creating entries
1543 of a particular etype automatically, as well as reading any special
1544 properties in the entries. For each entry, entry.ReadNode() should be
1545 called, to read the basic entry properties. The properties should be
1546 added to `self._entries[]`, in the correct order, with a suitable name.
1547
1548 Binman calls this at the start when reading the image description.
1549
1550BuildSectionData(required)
1551 Create the custom file format that you want and return it as bytes.
1552 This likely sets up a file header, then loops through the entries,
1553 adding them to the file. For each entry, call `entry.GetData()` to
1554 obtain the data. If that returns None, and `required` is False, then
1555 this method must give up and return None. But if `required` is True then
1556 it should assume that all data is valid.
1557
1558 Binman calls this when packing the image, to find out the size of
1559 everything. It is called again at the end when building the final image.
1560
1561SetImagePos(image_pos):
1562 Call `super().SetImagePos(image_pos)`, then set the `image_pos` values
1563 for each of the entries. This should use the custom file format to find
1564 the `start offset` (and `image_pos`) of each entry. If the file format
1565 uses compression in such a way that there is no offset available (other
1566 than reading the whole file and decompressing it), then the offsets for
1567 affected entries can remain unset (`None`). The size should also be set
1568 if possible.
Simon Glass0ac96b62021-03-18 20:25:15 +13001569
Simon Glasscc9a41c2021-11-23 11:03:49 -07001570 Binman calls this after the image has been packed, to update the
1571 location that all the entries ended up at.
Simon Glass0ac96b62021-03-18 20:25:15 +13001572
Simon Glass637958f2021-11-23 21:09:50 -07001573ReadChildData(child, decomp, alt_format):
Simon Glasscc9a41c2021-11-23 11:03:49 -07001574 The default version of this may be good enough, if you are able to
1575 implement SetImagePos() correctly. But that is a bit of a bypass, so
1576 you can override this method to read from your custom file format. It
1577 should read the entire entry containing the custom file using
1578 `super().ReadData(True)`, then parse the file to get the data for the
1579 given child, then return that data.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001580
Simon Glasscc9a41c2021-11-23 11:03:49 -07001581 If your file format supports compression, the `decomp` argument tells
1582 you whether to return the compressed data (`decomp` is False) or to
1583 uncompress it first, then return the uncompressed data (`decomp` is
1584 True). This is used by the `binman extract -U` option.
Simon Glass21db0ff2020-09-01 05:13:54 -06001585
Simon Glass637958f2021-11-23 21:09:50 -07001586 If your entry supports alternative formats, the alt_format provides the
1587 alternative format that the user has selected. Your function should
1588 return data in that format. This is used by the 'binman extract -l'
1589 option.
1590
Simon Glasscc9a41c2021-11-23 11:03:49 -07001591 Binman calls this when reading in an image, in order to populate all the
1592 entries with the data from that image (`binman ls`).
1593
1594WriteChildData(child):
1595 Binman calls this after `child.data` is updated, to inform the custom
1596 file format about this, in case it needs to do updates.
1597
1598 The default version of this does nothing and probably needs to be
1599 overridden for the 'binman replace' command to work. Your version should
1600 use `child.data` to update the data for that child in the custom file
1601 format.
1602
1603 Binman calls this when updating an image that has been read in and in
1604 particular to update the data for a particular entry (`binman replace`)
1605
1606Properties / Entry arguments
1607~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1608
1609See :ref:`develop/package/binman:Image description format` for more
1610information.
1611
1612align-default
1613 Default alignment for this section, if no alignment is given in the
1614 entry
1615
1616pad-byte
1617 Pad byte to use when padding
1618
1619sort-by-offset
1620 True if entries should be sorted by offset, False if they must be
1621 in-order in the device tree description
1622
1623end-at-4gb
1624 Used to build an x86 ROM which ends at 4GB (2^32)
1625
1626name-prefix
1627 Adds a prefix to the name of every entry in the section when writing out
1628 the map
1629
1630skip-at-start
1631 Number of bytes before the first entry starts. These effectively adjust
1632 the starting offset of entries. For example, if this is 16, then the
1633 first entry would start at 16. An entry with offset = 20 would in fact
1634 be written at offset 4 in the image file, since the first 16 bytes are
1635 skipped when writing.
Simon Glassb1d414c2021-04-03 11:05:10 +13001636
Simon Glassda6a9082023-01-07 14:07:10 -07001637filename
1638 filename to write the unpadded section contents to within the output
1639 directory (None to skip this).
1640
Simon Glass39dd2152019-07-08 14:25:47 -06001641Since a section is also an entry, it inherits all the properies of entries
1642too.
1643
Simon Glasscc9a41c2021-11-23 11:03:49 -07001644Note that the `allow_missing` member controls whether this section permits
1645external blobs to be missing their contents. The option will produce an
1646image but of course it will not work. It is useful to make sure that
1647Continuous Integration systems can build without the binaries being
1648available. This is set by the `SetAllowMissing()` method, if
1649`--allow-missing` is passed to binman.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001650
1651
1652
Simon Glassa7c97782022-08-07 16:33:25 -06001653.. _etype_tee_os:
1654
Roger Quadros5cdcea02022-02-19 20:50:04 +02001655Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
1656---------------------------------------------------------------
1657
1658Properties / Entry arguments:
1659 - tee-os-path: Filename of file to read into entry. This is typically
Simon Glassad5cfe12023-01-07 14:07:14 -07001660 called tee.bin or tee.elf
Roger Quadros5cdcea02022-02-19 20:50:04 +02001661
1662This entry holds the run-time firmware, typically started by U-Boot SPL.
1663See the U-Boot README for your architecture or board for how to use it. See
1664https://github.com/OP-TEE/optee_os for more information about OP-TEE.
1665
Simon Glassad5cfe12023-01-07 14:07:14 -07001666Note that if the file is in ELF format, it must go in a FIT. In that case,
1667this entry will mark itself as absent, providing the data only through the
1668read_elf_segments() method.
1669
1670Marking this entry as absent means that it if is used in the wrong context
1671it can be automatically dropped. Thus it is possible to add an OP-TEE entry
1672like this::
1673
1674 binman {
1675 tee-os {
1676 };
1677 };
1678
1679and pass either an ELF or plain binary in with -a tee-os-path <filename>
1680and have binman do the right thing:
1681
1682 - include the entry if tee.bin is provided and it does NOT have the v1
1683 header
1684 - drop it otherwise
1685
1686When used within a FIT, we can do::
1687
1688 binman {
1689 fit {
1690 tee-os {
1691 };
1692 };
1693 };
1694
1695which will split the ELF into separate nodes for each segment, if an ELF
1696file is provided (see :ref:`etype_fit`), or produce a single node if the
1697OP-TEE binary v1 format is provided (see optee_doc_) .
1698
1699.. _optee_doc: https://optee.readthedocs.io/en/latest/architecture/core.html#partitioning-of-the-binary
1700
Roger Quadros5cdcea02022-02-19 20:50:04 +02001701
1702
Simon Glassa7c97782022-08-07 16:33:25 -06001703.. _etype_text:
1704
Simon Glass7a61c6b2018-07-17 13:25:37 -06001705Entry: text: An entry which contains text
1706-----------------------------------------
1707
1708The text can be provided either in the node itself or by a command-line
1709argument. There is a level of indirection to allow multiple text strings
1710and sharing of text.
1711
1712Properties / Entry arguments:
1713 text-label: The value of this string indicates the property / entry-arg
1714 that contains the string to place in the entry
1715 <xxx> (actual name is the value of text-label): contains the string to
1716 place in the entry.
Simon Glass47f6a622019-07-08 13:18:40 -06001717 <text>: The text to place in the entry (overrides the above mechanism).
1718 This is useful when the text is constant.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001719
Simon Glass0ac96b62021-03-18 20:25:15 +13001720Example node::
Simon Glass7a61c6b2018-07-17 13:25:37 -06001721
1722 text {
1723 size = <50>;
1724 text-label = "message";
1725 };
1726
1727You can then use:
1728
1729 binman -amessage="this is my message"
1730
1731and binman will insert that string into the entry.
1732
Simon Glass0ac96b62021-03-18 20:25:15 +13001733It is also possible to put the string directly in the node::
Simon Glass7a61c6b2018-07-17 13:25:37 -06001734
1735 text {
1736 size = <8>;
1737 text-label = "message";
1738 message = "a message directly in the node"
1739 };
1740
Simon Glass0ac96b62021-03-18 20:25:15 +13001741or just::
Simon Glass47f6a622019-07-08 13:18:40 -06001742
1743 text {
1744 size = <8>;
1745 text = "some text directly in the node"
1746 };
1747
Simon Glass7a61c6b2018-07-17 13:25:37 -06001748The text is not itself nul-terminated. This can be achieved, if required,
1749by setting the size of the entry to something larger than the text.
1750
1751
1752
Neha Malcom Francis3b788942023-07-22 00:14:24 +05301753.. _etype_ti_board_config:
1754
1755Entry: ti-board-config: An entry containing a TI schema validated board config binary
1756-------------------------------------------------------------------------------------
1757
1758This etype supports generation of two kinds of board configuration
1759binaries: singular board config binary as well as combined board config
1760binary.
1761
1762Properties / Entry arguments:
1763 - config-file: File containing board configuration data in YAML
1764 - schema-file: File containing board configuration YAML schema against
1765 which the config file is validated
1766
1767Output files:
1768 - board config binary: File containing board configuration binary
1769
1770These above parameters are used only when the generated binary is
1771intended to be a single board configuration binary. Example::
1772
1773 my-ti-board-config {
1774 ti-board-config {
1775 config = "board-config.yaml";
1776 schema = "schema.yaml";
1777 };
1778 };
1779
1780To generate a combined board configuration binary, we pack the
1781needed individual binaries into a ti-board-config binary. In this case,
1782the available supported subnode names are board-cfg, pm-cfg, sec-cfg and
1783rm-cfg. The final binary is prepended with a header containing details about
1784the included board config binaries. Example::
1785
1786 my-combined-ti-board-config {
1787 ti-board-config {
1788 board-cfg {
1789 config = "board-cfg.yaml";
1790 schema = "schema.yaml";
1791 };
1792 sec-cfg {
1793 config = "sec-cfg.yaml";
1794 schema = "schema.yaml";
1795 };
1796 }
1797 }
1798
1799
1800
Neha Malcom Francis5f5f0a62023-07-22 00:14:25 +05301801.. _etype_ti_secure:
1802
1803Entry: ti-secure: Entry containing a TI x509 certificate binary
1804---------------------------------------------------------------
1805
1806Properties / Entry arguments:
1807 - content: List of phandles to entries to sign
1808 - keyfile: Filename of file containing key to sign binary with
1809 - sha: Hash function to be used for signing
1810
1811Output files:
1812 - input.<unique_name> - input file passed to openssl
1813 - config.<unique_name> - input file generated for openssl (which is
1814 used as the config file)
1815 - cert.<unique_name> - output file generated by openssl (which is
1816 used as the entry contents)
1817
1818openssl signs the provided data, using the TI templated config file and
1819writes the signature in this entry. This allows verification that the
1820data is genuine.
1821
1822
1823
1824.. _etype_ti_secure_rom:
1825
1826Entry: ti-secure-rom: Entry containing a TI x509 certificate binary for images booted by ROM
1827--------------------------------------------------------------------------------------------
1828
1829Properties / Entry arguments:
1830 - keyfile: Filename of file containing key to sign binary with
1831 - combined: boolean if device follows combined boot flow
1832 - countersign: boolean if device contains countersigned system firmware
1833 - load: load address of SPL
1834 - sw-rev: software revision
1835 - sha: Hash function to be used for signing
1836 - core: core on which bootloader runs, valid cores are 'secure' and 'public'
1837 - content: phandle of SPL in case of legacy bootflow or phandles of component binaries
1838 in case of combined bootflow
1839
1840The following properties are only for generating a combined bootflow binary:
1841 - sysfw-inner-cert: boolean if binary contains sysfw inner certificate
1842 - dm-data: boolean if binary contains dm-data binary
1843 - content-sbl: phandle of SPL binary
1844 - content-sysfw: phandle of sysfw binary
1845 - content-sysfw-data: phandle of sysfw-data or tifs-data binary
1846 - content-sysfw-inner-cert (optional): phandle of sysfw inner certificate binary
1847 - content-dm-data (optional): phandle of dm-data binary
1848 - load-sysfw: load address of sysfw binary
1849 - load-sysfw-data: load address of sysfw-data or tifs-data binary
1850 - load-sysfw-inner-cert (optional): load address of sysfw inner certificate binary
1851 - load-dm-data (optional): load address of dm-data binary
1852
1853Output files:
1854 - input.<unique_name> - input file passed to openssl
1855 - config.<unique_name> - input file generated for openssl (which is
1856 used as the config file)
1857 - cert.<unique_name> - output file generated by openssl (which is
1858 used as the entry contents)
1859
1860openssl signs the provided data, using the TI templated config file and
1861writes the signature in this entry. This allows verification that the
1862data is genuine.
1863
1864
1865
Simon Glassa7c97782022-08-07 16:33:25 -06001866.. _etype_u_boot:
1867
Simon Glass7a61c6b2018-07-17 13:25:37 -06001868Entry: u-boot: U-Boot flat binary
1869---------------------------------
1870
1871Properties / Entry arguments:
1872 - filename: Filename of u-boot.bin (default 'u-boot.bin')
1873
1874This is the U-Boot binary, containing relocation information to allow it
1875to relocate itself at runtime. The binary typically includes a device tree
Simon Glass718b5292021-03-18 20:25:07 +13001876blob at the end of it.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001877
Simon Glass18ed9962023-01-07 14:07:11 -07001878U-Boot can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001879
Simon Glass718b5292021-03-18 20:25:07 +13001880Note that this entry is automatically replaced with u-boot-expanded unless
Simon Glass7098b7f2021-03-21 18:24:30 +13001881--no-expanded is used or the node has a 'no-expanded' property.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001882
1883
Simon Glass718b5292021-03-18 20:25:07 +13001884
Simon Glassa7c97782022-08-07 16:33:25 -06001885.. _etype_u_boot_dtb:
1886
Simon Glass7a61c6b2018-07-17 13:25:37 -06001887Entry: u-boot-dtb: U-Boot device tree
1888-------------------------------------
1889
1890Properties / Entry arguments:
1891 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1892
1893This is the U-Boot device tree, containing configuration information for
1894U-Boot. U-Boot needs this to know what devices are present and which drivers
1895to activate.
1896
Simon Glasse219aa42018-09-14 04:57:24 -06001897Note: This is mostly an internal entry type, used by others. This allows
1898binman to know which entries contain a device tree.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001899
1900
Simon Glassa7c97782022-08-07 16:33:25 -06001901
1902.. _etype_u_boot_dtb_with_ucode:
Simon Glass7a61c6b2018-07-17 13:25:37 -06001903
1904Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
1905-----------------------------------------------------------------------------------
1906
1907Properties / Entry arguments:
1908 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1909
1910See Entry_u_boot_ucode for full details of the three entries involved in
1911this process. This entry provides the U-Boot device-tree file, which
1912contains the microcode. If the microcode is not being collated into one
1913place then the offset and size of the microcode is recorded by this entry,
Simon Glass537e0062021-03-18 20:24:54 +13001914for use by u-boot-with-ucode_ptr. If it is being collated, then this
Simon Glass7a61c6b2018-07-17 13:25:37 -06001915entry deletes the microcode from the device tree (to save space) and makes
Simon Glass537e0062021-03-18 20:24:54 +13001916it available to u-boot-ucode.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001917
1918
1919
Simon Glassa7c97782022-08-07 16:33:25 -06001920.. _etype_u_boot_elf:
1921
Simon Glassb1714232018-09-14 04:57:35 -06001922Entry: u-boot-elf: U-Boot ELF image
1923-----------------------------------
1924
1925Properties / Entry arguments:
1926 - filename: Filename of u-boot (default 'u-boot')
1927
1928This is the U-Boot ELF image. It does not include a device tree but can be
1929relocated to any address for execution.
1930
1931
Simon Glassa7c97782022-08-07 16:33:25 -06001932
1933.. _etype_u_boot_env:
Simon Glassb1714232018-09-14 04:57:35 -06001934
Simon Glass136dd352020-10-26 17:39:59 -06001935Entry: u-boot-env: An entry which contains a U-Boot environment
1936---------------------------------------------------------------
1937
1938Properties / Entry arguments:
1939 - filename: File containing the environment text, with each line in the
1940 form var=value
1941
1942
Simon Glass718b5292021-03-18 20:25:07 +13001943
Simon Glassa7c97782022-08-07 16:33:25 -06001944.. _etype_u_boot_expanded:
1945
Simon Glass718b5292021-03-18 20:25:07 +13001946Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
1947------------------------------------------------------------------------------
1948
1949This is a section containing the U-Boot binary and a devicetree. Using this
1950entry type automatically creates this section, with the following entries
1951in it:
1952
1953 u-boot-nodtb
1954 u-boot-dtb
1955
1956Having the devicetree separate allows binman to update it in the final
1957image, so that the entries positions are provided to the running U-Boot.
1958
1959
Simon Glass136dd352020-10-26 17:39:59 -06001960
Simon Glassa7c97782022-08-07 16:33:25 -06001961.. _etype_u_boot_img:
1962
Simon Glass7a61c6b2018-07-17 13:25:37 -06001963Entry: u-boot-img: U-Boot legacy image
1964--------------------------------------
1965
1966Properties / Entry arguments:
1967 - filename: Filename of u-boot.img (default 'u-boot.img')
1968
1969This is the U-Boot binary as a packaged image, in legacy format. It has a
1970header which allows it to be loaded at the correct address for execution.
1971
1972You should use FIT (Flat Image Tree) instead of the legacy image for new
1973applications.
1974
1975
1976
Simon Glassa7c97782022-08-07 16:33:25 -06001977.. _etype_u_boot_nodtb:
1978
Simon Glass7a61c6b2018-07-17 13:25:37 -06001979Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
1980--------------------------------------------------------------------
1981
1982Properties / Entry arguments:
Simon Glass537e0062021-03-18 20:24:54 +13001983 - filename: Filename to include (default 'u-boot-nodtb.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06001984
1985This is the U-Boot binary, containing relocation information to allow it
1986to relocate itself at runtime. It does not include a device tree blob at
Simon Glass537e0062021-03-18 20:24:54 +13001987the end of it so normally cannot work without it. You can add a u-boot-dtb
Simon Glass718b5292021-03-18 20:25:07 +13001988entry after this one, or use a u-boot entry instead, normally expands to a
1989section containing u-boot and u-boot-dtb
Simon Glass7a61c6b2018-07-17 13:25:37 -06001990
1991
1992
Simon Glassa7c97782022-08-07 16:33:25 -06001993.. _etype_u_boot_spl:
1994
Simon Glass7a61c6b2018-07-17 13:25:37 -06001995Entry: u-boot-spl: U-Boot SPL binary
1996------------------------------------
1997
1998Properties / Entry arguments:
1999 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
2000
2001This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
2002binary which loads before U-Boot proper, typically into on-chip SRAM. It is
2003responsible for locating, loading and jumping to U-Boot. Note that SPL is
2004not relocatable so must be loaded to the correct address in SRAM, or written
Simon Glass8425a1f2018-07-17 13:25:48 -06002005to run from the correct address if direct flash execution is possible (e.g.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002006on x86 devices).
2007
Simon Glass18ed9962023-01-07 14:07:11 -07002008SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002009
2010in the binman README for more information.
2011
2012The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2013binman uses that to look up symbols to write into the SPL binary.
2014
Simon Glass718b5292021-03-18 20:25:07 +13002015Note that this entry is automatically replaced with u-boot-spl-expanded
Simon Glass7098b7f2021-03-21 18:24:30 +13002016unless --no-expanded is used or the node has a 'no-expanded' property.
Simon Glass718b5292021-03-18 20:25:07 +13002017
Simon Glass7a61c6b2018-07-17 13:25:37 -06002018
2019
Simon Glassa7c97782022-08-07 16:33:25 -06002020.. _etype_u_boot_spl_bss_pad:
2021
Simon Glass7a61c6b2018-07-17 13:25:37 -06002022Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
2023---------------------------------------------------------------------
2024
2025Properties / Entry arguments:
2026 None
2027
Simon Glass308939b2021-03-18 20:24:55 +13002028This holds the padding added after the SPL binary to cover the BSS (Block
2029Started by Symbol) region. This region holds the various variables used by
2030SPL. It is set to 0 by SPL when it starts up. If you want to append data to
2031the SPL image (such as a device tree file), you must pad out the BSS region
2032to avoid the data overlapping with U-Boot variables. This entry is useful in
2033that case. It automatically pads out the entry size to cover both the code,
2034data and BSS.
2035
2036The contents of this entry will a certain number of zero bytes, determined
2037by __bss_size
Simon Glass7a61c6b2018-07-17 13:25:37 -06002038
2039The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2040binman uses that to look up the BSS address.
2041
2042
2043
Simon Glassa7c97782022-08-07 16:33:25 -06002044.. _etype_u_boot_spl_dtb:
2045
Simon Glass7a61c6b2018-07-17 13:25:37 -06002046Entry: u-boot-spl-dtb: U-Boot SPL device tree
2047---------------------------------------------
2048
2049Properties / Entry arguments:
2050 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
2051
2052This is the SPL device tree, containing configuration information for
2053SPL. SPL needs this to know what devices are present and which drivers
2054to activate.
2055
2056
Simon Glassa7c97782022-08-07 16:33:25 -06002057
2058.. _etype_u_boot_spl_elf:
Simon Glass7a61c6b2018-07-17 13:25:37 -06002059
Simon Glassb1714232018-09-14 04:57:35 -06002060Entry: u-boot-spl-elf: U-Boot SPL ELF image
2061-------------------------------------------
2062
2063Properties / Entry arguments:
Simon Glass5dcc21d2019-07-08 13:18:45 -06002064 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
Simon Glassb1714232018-09-14 04:57:35 -06002065
2066This is the U-Boot SPL ELF image. It does not include a device tree but can
2067be relocated to any address for execution.
2068
Simon Glass718b5292021-03-18 20:25:07 +13002069
2070
Simon Glassa7c97782022-08-07 16:33:25 -06002071.. _etype_u_boot_spl_expanded:
2072
Simon Glass718b5292021-03-18 20:25:07 +13002073Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
2074--------------------------------------------------------------------------------------
2075
2076Properties / Entry arguments:
2077 - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2078 select)
2079
2080This is a section containing the U-Boot binary, BSS padding if needed and a
2081devicetree. Using this entry type automatically creates this section, with
2082the following entries in it:
2083
2084 u-boot-spl-nodtb
2085 u-boot-spl-bss-pad
2086 u-boot-dtb
2087
2088Having the devicetree separate allows binman to update it in the final
2089image, so that the entries positions are provided to the running U-Boot.
2090
2091This entry is selected based on the value of the 'spl-dtb' entryarg. If
2092this is non-empty (and not 'n' or '0') then this expanded entry is selected.
Simon Glassb1714232018-09-14 04:57:35 -06002093
2094
Simon Glassa7c97782022-08-07 16:33:25 -06002095
2096.. _etype_u_boot_spl_nodtb:
Simon Glass718b5292021-03-18 20:25:07 +13002097
Simon Glass7a61c6b2018-07-17 13:25:37 -06002098Entry: u-boot-spl-nodtb: SPL binary without device tree appended
2099----------------------------------------------------------------
2100
2101Properties / Entry arguments:
Simon Glass537e0062021-03-18 20:24:54 +13002102 - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002103
2104This is the U-Boot SPL binary, It does not include a device tree blob at
2105the end of it so may not be able to work without it, assuming SPL needs
Simon Glass537e0062021-03-18 20:24:54 +13002106a device tree to operate on your platform. You can add a u-boot-spl-dtb
Simon Glass718b5292021-03-18 20:25:07 +13002107entry after this one, or use a u-boot-spl entry instead' which normally
2108expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
2109u-boot-spl-dtb
Simon Glass7a61c6b2018-07-17 13:25:37 -06002110
Simon Glass18ed9962023-01-07 14:07:11 -07002111SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass31e04cb2021-03-18 20:24:56 +13002112
2113in the binman README for more information.
2114
2115The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2116binman uses that to look up symbols to write into the SPL binary.
2117
Simon Glass7a61c6b2018-07-17 13:25:37 -06002118
2119
Simon Glassa7c97782022-08-07 16:33:25 -06002120.. _etype_u_boot_spl_with_ucode_ptr:
2121
Simon Glass7a61c6b2018-07-17 13:25:37 -06002122Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
2123----------------------------------------------------------------------------
2124
Simon Glass3fb4f422018-09-14 04:57:32 -06002125This is used when SPL must set up the microcode for U-Boot.
2126
Simon Glass7a61c6b2018-07-17 13:25:37 -06002127See Entry_u_boot_ucode for full details of the entries involved in this
2128process.
2129
2130
2131
Simon Glassa7c97782022-08-07 16:33:25 -06002132.. _etype_u_boot_tpl:
2133
Simon Glass8425a1f2018-07-17 13:25:48 -06002134Entry: u-boot-tpl: U-Boot TPL binary
2135------------------------------------
2136
2137Properties / Entry arguments:
2138 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
2139
2140This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
2141binary which loads before SPL, typically into on-chip SRAM. It is
2142responsible for locating, loading and jumping to SPL, the next-stage
2143loader. Note that SPL is not relocatable so must be loaded to the correct
2144address in SRAM, or written to run from the correct address if direct
2145flash execution is possible (e.g. on x86 devices).
2146
Simon Glass18ed9962023-01-07 14:07:11 -07002147SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass8425a1f2018-07-17 13:25:48 -06002148
2149in the binman README for more information.
2150
2151The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2152binman uses that to look up symbols to write into the TPL binary.
2153
Simon Glass718b5292021-03-18 20:25:07 +13002154Note that this entry is automatically replaced with u-boot-tpl-expanded
Simon Glass7098b7f2021-03-21 18:24:30 +13002155unless --no-expanded is used or the node has a 'no-expanded' property.
Simon Glass718b5292021-03-18 20:25:07 +13002156
Simon Glass8425a1f2018-07-17 13:25:48 -06002157
2158
Simon Glassa7c97782022-08-07 16:33:25 -06002159.. _etype_u_boot_tpl_bss_pad:
2160
Simon Glass63f41d42021-03-18 20:24:58 +13002161Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
2162---------------------------------------------------------------------
2163
2164Properties / Entry arguments:
2165 None
2166
2167This holds the padding added after the TPL binary to cover the BSS (Block
2168Started by Symbol) region. This region holds the various variables used by
2169TPL. It is set to 0 by TPL when it starts up. If you want to append data to
2170the TPL image (such as a device tree file), you must pad out the BSS region
2171to avoid the data overlapping with U-Boot variables. This entry is useful in
2172that case. It automatically pads out the entry size to cover both the code,
2173data and BSS.
2174
2175The contents of this entry will a certain number of zero bytes, determined
2176by __bss_size
2177
2178The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2179binman uses that to look up the BSS address.
2180
2181
2182
Simon Glassa7c97782022-08-07 16:33:25 -06002183.. _etype_u_boot_tpl_dtb:
2184
Simon Glass8425a1f2018-07-17 13:25:48 -06002185Entry: u-boot-tpl-dtb: U-Boot TPL device tree
2186---------------------------------------------
2187
2188Properties / Entry arguments:
2189 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
2190
2191This is the TPL device tree, containing configuration information for
2192TPL. TPL needs this to know what devices are present and which drivers
2193to activate.
2194
2195
2196
Simon Glassa7c97782022-08-07 16:33:25 -06002197.. _etype_u_boot_tpl_dtb_with_ucode:
2198
Simon Glass3fb4f422018-09-14 04:57:32 -06002199Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
2200----------------------------------------------------------------------------
2201
2202This is used when TPL must set up the microcode for U-Boot.
2203
2204See Entry_u_boot_ucode for full details of the entries involved in this
2205process.
2206
2207
2208
Simon Glassa7c97782022-08-07 16:33:25 -06002209.. _etype_u_boot_tpl_elf:
2210
Simon Glassa899f712019-07-08 13:18:46 -06002211Entry: u-boot-tpl-elf: U-Boot TPL ELF image
2212-------------------------------------------
2213
2214Properties / Entry arguments:
2215 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
2216
2217This is the U-Boot TPL ELF image. It does not include a device tree but can
2218be relocated to any address for execution.
2219
2220
Simon Glassa7c97782022-08-07 16:33:25 -06002221
2222.. _etype_u_boot_tpl_expanded:
Simon Glassa899f712019-07-08 13:18:46 -06002223
Simon Glass718b5292021-03-18 20:25:07 +13002224Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
2225--------------------------------------------------------------------------------------
2226
2227Properties / Entry arguments:
2228 - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2229 select)
2230
2231This is a section containing the U-Boot binary, BSS padding if needed and a
2232devicetree. Using this entry type automatically creates this section, with
2233the following entries in it:
2234
2235 u-boot-tpl-nodtb
2236 u-boot-tpl-bss-pad
2237 u-boot-dtb
2238
2239Having the devicetree separate allows binman to update it in the final
2240image, so that the entries positions are provided to the running U-Boot.
2241
2242This entry is selected based on the value of the 'tpl-dtb' entryarg. If
2243this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2244
2245
2246
Simon Glassa7c97782022-08-07 16:33:25 -06002247.. _etype_u_boot_tpl_nodtb:
2248
Simon Glassc98de972021-03-18 20:24:57 +13002249Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
2250----------------------------------------------------------------
2251
2252Properties / Entry arguments:
2253 - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin')
2254
2255This is the U-Boot TPL binary, It does not include a device tree blob at
2256the end of it so may not be able to work without it, assuming TPL needs
2257a device tree to operate on your platform. You can add a u-boot-tpl-dtb
Simon Glass718b5292021-03-18 20:25:07 +13002258entry after this one, or use a u-boot-tpl entry instead, which normally
2259expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
2260u-boot-tpl-dtb
Simon Glassc98de972021-03-18 20:24:57 +13002261
Simon Glass18ed9962023-01-07 14:07:11 -07002262TPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassc98de972021-03-18 20:24:57 +13002263
2264in the binman README for more information.
2265
2266The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2267binman uses that to look up symbols to write into the TPL binary.
2268
2269
Simon Glassa7c97782022-08-07 16:33:25 -06002270
2271.. _etype_u_boot_tpl_with_ucode_ptr:
Simon Glassc98de972021-03-18 20:24:57 +13002272
Simon Glass3fb4f422018-09-14 04:57:32 -06002273Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
2274----------------------------------------------------------------------------
2275
2276See Entry_u_boot_ucode for full details of the entries involved in this
2277process.
2278
2279
2280
Simon Glassa7c97782022-08-07 16:33:25 -06002281.. _etype_u_boot_ucode:
2282
Simon Glass7a61c6b2018-07-17 13:25:37 -06002283Entry: u-boot-ucode: U-Boot microcode block
2284-------------------------------------------
2285
2286Properties / Entry arguments:
2287 None
2288
2289The contents of this entry are filled in automatically by other entries
2290which must also be in the image.
2291
2292U-Boot on x86 needs a single block of microcode. This is collected from
2293the various microcode update nodes in the device tree. It is also unable
2294to read the microcode from the device tree on platforms that use FSP
2295(Firmware Support Package) binaries, because the API requires that the
2296microcode is supplied before there is any SRAM available to use (i.e.
2297the FSP sets up the SRAM / cache-as-RAM but does so in the call that
2298requires the microcode!). To keep things simple, all x86 platforms handle
2299microcode the same way in U-Boot (even non-FSP platforms). This is that
2300a table is placed at _dt_ucode_base_size containing the base address and
2301size of the microcode. This is either passed to the FSP (for FSP
2302platforms), or used to set up the microcode (for non-FSP platforms).
2303This all happens in the build system since it is the only way to get
2304the microcode into a single blob and accessible without SRAM.
2305
2306There are two cases to handle. If there is only one microcode blob in
2307the device tree, then the ucode pointer it set to point to that. This
2308entry (u-boot-ucode) is empty. If there is more than one update, then
2309this entry holds the concatenation of all updates, and the device tree
2310entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
2311last step ensures that that the microcode appears in one contiguous
2312block in the image and is not unnecessarily duplicated in the device
2313tree. It is referred to as 'collation' here.
2314
2315Entry types that have a part to play in handling microcode:
2316
2317 Entry_u_boot_with_ucode_ptr:
2318 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
2319 It updates it with the address and size of the microcode so that
2320 U-Boot can find it early on start-up.
2321 Entry_u_boot_dtb_with_ucode:
2322 Contains u-boot.dtb. It stores the microcode in a
2323 'self.ucode_data' property, which is then read by this class to
2324 obtain the microcode if needed. If collation is performed, it
2325 removes the microcode from the device tree.
2326 Entry_u_boot_ucode:
2327 This class. If collation is enabled it reads the microcode from
2328 the Entry_u_boot_dtb_with_ucode entry, and uses it as the
2329 contents of this entry.
2330
2331
2332
Simon Glassda6a9082023-01-07 14:07:10 -07002333.. _etype_u_boot_vpl:
2334
2335Entry: u-boot-vpl: U-Boot VPL binary
2336------------------------------------
2337
2338Properties / Entry arguments:
2339 - filename: Filename of u-boot-vpl.bin (default 'vpl/u-boot-vpl.bin')
2340
2341This is the U-Boot VPL (Verifying Program Loader) binary. This is a small
2342binary which loads before SPL, typically into on-chip SRAM. It is
2343responsible for locating, loading and jumping to SPL, the next-stage
2344loader. Note that VPL is not relocatable so must be loaded to the correct
2345address in SRAM, or written to run from the correct address if direct
2346flash execution is possible (e.g. on x86 devices).
2347
Simon Glass18ed9962023-01-07 14:07:11 -07002348SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassda6a9082023-01-07 14:07:10 -07002349
2350in the binman README for more information.
2351
2352The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2353binman uses that to look up symbols to write into the VPL binary.
2354
2355
2356
2357.. _etype_u_boot_vpl_bss_pad:
2358
2359Entry: u-boot-vpl-bss-pad: U-Boot VPL binary padded with a BSS region
2360---------------------------------------------------------------------
2361
2362Properties / Entry arguments:
2363 None
2364
2365This holds the padding added after the VPL binary to cover the BSS (Block
2366Started by Symbol) region. This region holds the various variables used by
2367VPL. It is set to 0 by VPL when it starts up. If you want to append data to
2368the VPL image (such as a device tree file), you must pad out the BSS region
2369to avoid the data overlapping with U-Boot variables. This entry is useful in
2370that case. It automatically pads out the entry size to cover both the code,
2371data and BSS.
2372
2373The contents of this entry will a certain number of zero bytes, determined
2374by __bss_size
2375
2376The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2377binman uses that to look up the BSS address.
2378
2379
2380
2381.. _etype_u_boot_vpl_dtb:
2382
2383Entry: u-boot-vpl-dtb: U-Boot VPL device tree
2384---------------------------------------------
2385
2386Properties / Entry arguments:
2387 - filename: Filename of u-boot.dtb (default 'vpl/u-boot-vpl.dtb')
2388
2389This is the VPL device tree, containing configuration information for
2390VPL. VPL needs this to know what devices are present and which drivers
2391to activate.
2392
2393
2394
2395.. _etype_u_boot_vpl_elf:
2396
2397Entry: u-boot-vpl-elf: U-Boot VPL ELF image
2398-------------------------------------------
2399
2400Properties / Entry arguments:
2401 - filename: Filename of VPL u-boot (default 'vpl/u-boot-vpl')
2402
2403This is the U-Boot VPL ELF image. It does not include a device tree but can
2404be relocated to any address for execution.
2405
2406
2407
2408.. _etype_u_boot_vpl_expanded:
2409
2410Entry: u-boot-vpl-expanded: U-Boot VPL flat binary broken out into its component parts
2411--------------------------------------------------------------------------------------
2412
2413Properties / Entry arguments:
2414 - vpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2415 select)
2416
2417This is a section containing the U-Boot binary, BSS padding if needed and a
2418devicetree. Using this entry type automatically creates this section, with
2419the following entries in it:
2420
2421 u-boot-vpl-nodtb
2422 u-boot-vpl-bss-pad
2423 u-boot-dtb
2424
2425Having the devicetree separate allows binman to update it in the final
2426image, so that the entries positions are provided to the running U-Boot.
2427
2428This entry is selected based on the value of the 'vpl-dtb' entryarg. If
2429this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2430
2431
2432
2433.. _etype_u_boot_vpl_nodtb:
2434
2435Entry: u-boot-vpl-nodtb: VPL binary without device tree appended
2436----------------------------------------------------------------
2437
2438Properties / Entry arguments:
2439 - filename: Filename to include (default 'vpl/u-boot-vpl-nodtb.bin')
2440
2441This is the U-Boot VPL binary, It does not include a device tree blob at
2442the end of it so may not be able to work without it, assuming VPL needs
2443a device tree to operate on your platform. You can add a u_boot_vpl_dtb
2444entry after this one, or use a u_boot_vpl entry instead, which normally
2445expands to a section containing u-boot-vpl-dtb, u-boot-vpl-bss-pad and
2446u-boot-vpl-dtb
2447
Simon Glass18ed9962023-01-07 14:07:11 -07002448VPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassda6a9082023-01-07 14:07:10 -07002449
2450The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2451binman uses that to look up symbols to write into the VPL binary.
2452
2453
2454
Simon Glassa7c97782022-08-07 16:33:25 -06002455.. _etype_u_boot_with_ucode_ptr:
2456
Simon Glass7a61c6b2018-07-17 13:25:37 -06002457Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
2458--------------------------------------------------------------------
2459
2460Properties / Entry arguments:
Masahiro Yamadaa7a0ca42019-12-14 13:47:26 +09002461 - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
Simon Glassee21d3a2018-09-14 04:57:07 -06002462 - optional-ucode: boolean property to make microcode optional. If the
2463 u-boot.bin image does not include microcode, no error will
2464 be generated.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002465
2466See Entry_u_boot_ucode for full details of the three entries involved in
2467this process. This entry updates U-Boot with the offset and size of the
2468microcode, to allow early x86 boot code to find it without doing anything
Simon Glass537e0062021-03-18 20:24:54 +13002469complicated. Otherwise it is the same as the u-boot entry.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002470
2471
2472
Simon Glassa7c97782022-08-07 16:33:25 -06002473.. _etype_vblock:
2474
Simon Glass5c350162018-07-17 13:25:47 -06002475Entry: vblock: An entry which contains a Chromium OS verified boot block
2476------------------------------------------------------------------------
2477
2478Properties / Entry arguments:
Simon Glass17b84eb2019-05-17 22:00:53 -06002479 - content: List of phandles to entries to sign
Simon Glass5c350162018-07-17 13:25:47 -06002480 - keydir: Directory containing the public keys to use
2481 - keyblock: Name of the key file to use (inside keydir)
2482 - signprivate: Name of provide key file to use (inside keydir)
2483 - version: Version number of the vblock (typically 1)
2484 - kernelkey: Name of the kernel key to use (inside keydir)
2485 - preamble-flags: Value of the vboot preamble flags (typically 0)
2486
Simon Glass639505b2018-09-14 04:57:11 -06002487Output files:
2488 - input.<unique_name> - input file passed to futility
2489 - vblock.<unique_name> - output file generated by futility (which is
2490 used as the entry contents)
2491
Jagdish Gediya311d4842018-09-03 21:35:08 +05302492Chromium OS signs the read-write firmware and kernel, writing the signature
Simon Glass5c350162018-07-17 13:25:47 -06002493in this block. This allows U-Boot to verify that the next firmware stage
2494and kernel are genuine.
2495
2496
2497
Simon Glassc3fe97f2023-03-02 17:02:45 -07002498.. _etype_x509_cert:
2499
2500Entry: x509-cert: An entry which contains an X509 certificate
2501-------------------------------------------------------------
2502
2503Properties / Entry arguments:
2504 - content: List of phandles to entries to sign
2505
2506Output files:
2507 - input.<unique_name> - input file passed to openssl
2508 - cert.<unique_name> - output file generated by openssl (which is
2509 used as the entry contents)
2510
2511openssl signs the provided data, writing the signature in this entry. This
2512allows verification that the data is genuine
2513
2514
2515
Simon Glassa7c97782022-08-07 16:33:25 -06002516.. _etype_x86_reset16:
2517
Simon Glass0b074d62019-08-24 07:22:48 -06002518Entry: x86-reset16: x86 16-bit reset code for U-Boot
2519----------------------------------------------------
2520
2521Properties / Entry arguments:
2522 - filename: Filename of u-boot-x86-reset16.bin (default
2523 'u-boot-x86-reset16.bin')
2524
2525x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2526must be placed at a particular address. This entry holds that code. It is
2527typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2528for jumping to the x86-start16 code, which continues execution.
2529
2530For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
2531
2532
2533
Simon Glassa7c97782022-08-07 16:33:25 -06002534.. _etype_x86_reset16_spl:
2535
Simon Glass0b074d62019-08-24 07:22:48 -06002536Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
2537--------------------------------------------------------
2538
2539Properties / Entry arguments:
2540 - filename: Filename of u-boot-x86-reset16.bin (default
2541 'u-boot-x86-reset16.bin')
2542
2543x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2544must be placed at a particular address. This entry holds that code. It is
2545typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2546for jumping to the x86-start16 code, which continues execution.
2547
2548For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
2549
2550
2551
Simon Glassa7c97782022-08-07 16:33:25 -06002552.. _etype_x86_reset16_tpl:
2553
Simon Glass0b074d62019-08-24 07:22:48 -06002554Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
2555--------------------------------------------------------
2556
2557Properties / Entry arguments:
2558 - filename: Filename of u-boot-x86-reset16.bin (default
2559 'u-boot-x86-reset16.bin')
2560
2561x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2562must be placed at a particular address. This entry holds that code. It is
2563typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2564for jumping to the x86-start16 code, which continues execution.
2565
2566For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
2567
2568
Simon Glassa7c97782022-08-07 16:33:25 -06002569
2570.. _etype_x86_start16:
Simon Glass0b074d62019-08-24 07:22:48 -06002571
Simon Glass7a61c6b2018-07-17 13:25:37 -06002572Entry: x86-start16: x86 16-bit start-up code for U-Boot
2573-------------------------------------------------------
2574
2575Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002576 - filename: Filename of u-boot-x86-start16.bin (default
2577 'u-boot-x86-start16.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002578
2579x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
Simon Glassabab18c2019-08-24 07:22:49 -06002580must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2581entry holds that code. It is typically placed at offset
2582CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2583and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2584U-Boot).
Simon Glass7a61c6b2018-07-17 13:25:37 -06002585
2586For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
2587
2588
2589
Simon Glassa7c97782022-08-07 16:33:25 -06002590.. _etype_x86_start16_spl:
2591
Simon Glass7a61c6b2018-07-17 13:25:37 -06002592Entry: x86-start16-spl: x86 16-bit start-up code for SPL
2593--------------------------------------------------------
2594
2595Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002596 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
2597 'spl/u-boot-x86-start16-spl.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002598
Simon Glassabab18c2019-08-24 07:22:49 -06002599x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2600must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2601entry holds that code. It is typically placed at offset
2602CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2603and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2604U-Boot).
Simon Glass7a61c6b2018-07-17 13:25:37 -06002605
Simon Glassabab18c2019-08-24 07:22:49 -06002606For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002607
2608
2609
Simon Glassa7c97782022-08-07 16:33:25 -06002610.. _etype_x86_start16_tpl:
2611
Simon Glassed40e962018-09-14 04:57:10 -06002612Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
2613--------------------------------------------------------
2614
2615Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002616 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
2617 'tpl/u-boot-x86-start16-tpl.bin')
Simon Glassed40e962018-09-14 04:57:10 -06002618
Simon Glassabab18c2019-08-24 07:22:49 -06002619x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2620must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2621entry holds that code. It is typically placed at offset
2622CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2623and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2624U-Boot).
Simon Glassed40e962018-09-14 04:57:10 -06002625
Simon Glassabab18c2019-08-24 07:22:49 -06002626If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
Simon Glassed40e962018-09-14 04:57:10 -06002627may be used instead.
2628
2629
2630