blob: 801bd946742f2c38631553d77f31591b5822ebef [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
Sughosh Ganu269ee6d2023-08-22 23:09:59 +0530471.. _etype_efi_capsule:
472
473Entry: capsule: Entry for generating EFI Capsule files
474------------------------------------------------------
475
476The parameters needed for generation of the capsules can be provided
477as properties in the entry.
478
479Properties / Entry arguments:
480 - image-index: Unique number for identifying corresponding
481 payload image. Number between 1 and descriptor count, i.e.
482 the total number of firmware images that can be updated. Mandatory
483 property.
484 - image-guid: Image GUID which will be used for identifying the
485 updatable image on the board. Mandatory property.
486 - hardware-instance: Optional number for identifying unique
487 hardware instance of a device in the system. Default value of 0
488 for images where value is not to be used.
489 - fw-version: Value of image version that can be put on the capsule
490 through the Firmware Management Protocol(FMP) header.
491 - monotonic-count: Count used when signing an image.
492 - private-key: Path to PEM formatted .key private key file. Mandatory
493 property for generating signed capsules.
494 - public-key-cert: Path to PEM formatted .crt public key certificate
495 file. Mandatory property for generating signed capsules.
496 - oem-flags - OEM flags to be passed through capsule header.
497
498 Since this is a subclass of Entry_section, all properties of the parent
499 class also apply here. Except for the properties stated as mandatory, the
500 rest of the properties are optional.
501
502For more details on the description of the capsule format, and the capsule
503update functionality, refer Section 8.5 and Chapter 23 in the `UEFI
504specification`_.
505
506The capsule parameters like image index and image GUID are passed as
507properties in the entry. The payload to be used in the capsule is to be
508provided as a subnode of the capsule entry.
509
510A typical capsule entry node would then look something like this::
511
512 capsule {
513 type = "efi-capsule";
514 image-index = <0x1>;
515 /* Image GUID for testing capsule update */
516 image-guid = SANDBOX_UBOOT_IMAGE_GUID;
517 hardware-instance = <0x0>;
518 private-key = "path/to/the/private/key";
519 public-key-cert = "path/to/the/public-key-cert";
520 oem-flags = <0x8000>;
521
522 u-boot {
523 };
524 };
525
526In the above example, the capsule payload is the U-Boot image. The
527capsule entry would read the contents of the payload and put them
528into the capsule. Any external file can also be specified as the
529payload using the blob-ext subnode.
530
531.. _`UEFI specification`: https://uefi.org/sites/default/files/resources/UEFI_Spec_2_10_Aug29.pdf
532
533
534
Christian Taedckebc454362023-07-17 09:05:52 +0200535.. _etype_encrypted:
536
537Entry: encrypted: Externally built encrypted binary blob
538--------------------------------------------------------
539
540This entry provides the functionality to include information about how to
541decrypt an encrypted binary. This information is added to the
542resulting device tree by adding a new cipher node in the entry's parent
543node (i.e. the binary).
544
545The key that must be used to decrypt the binary is either directly embedded
546in the device tree or indirectly by specifying a key source. The key source
547can be used as an id of a key that is stored in an external device.
548
549Using an embedded key
550~~~~~~~~~~~~~~~~~~~~~
551
552This is an example using an embedded key::
553
554 blob-ext {
555 filename = "encrypted-blob.bin";
556 };
557
558 encrypted {
559 algo = "aes256-gcm";
560 iv-filename = "encrypted-blob.bin.iv";
561 key-filename = "encrypted-blob.bin.key";
562 };
563
564This entry generates the following device tree structure form the example
565above::
566
567 data = [...]
568 cipher {
569 algo = "aes256-gcm";
570 key = <0x...>;
571 iv = <0x...>;
572 };
573
574The data property is generated by the blob-ext etype, the cipher node and
575its content is generated by this etype.
576
577Using an external key
578~~~~~~~~~~~~~~~~~~~~~
579
580Instead of embedding the key itself into the device tree, it is also
581possible to address an externally stored key by specifying a 'key-source'
582instead of the 'key'::
583
584 blob-ext {
585 filename = "encrypted-blob.bin";
586 };
587
588 encrypted {
589 algo = "aes256-gcm";
590 iv-filename = "encrypted-blob.bin.iv";
591 key-source = "external-key-id";
592 };
593
594This entry generates the following device tree structure form the example
595above::
596
597 data = [...]
598 cipher {
599 algo = "aes256-gcm";
600 key-source = "external-key-id";
601 iv = <0x...>;
602 };
603
604Properties
605~~~~~~~~~~
606
607Properties / Entry arguments:
608 - algo: The encryption algorithm. Currently no algorithm is supported
609 out-of-the-box. Certain algorithms will be added in future
610 patches.
611 - iv-filename: The name of the file containing the initialization
612 vector (in short iv). See
613 https://en.wikipedia.org/wiki/Initialization_vector
614 - key-filename: The name of the file containing the key. Either
615 key-filename or key-source must be provided.
616 - key-source: The key that should be used. Either key-filename or
617 key-source must be provided.
618
619
620
Simon Glassa7c97782022-08-07 16:33:25 -0600621.. _etype_fdtmap:
622
Simon Glass0f621332019-07-08 14:25:27 -0600623Entry: fdtmap: An entry which contains an FDT map
624-------------------------------------------------
625
626Properties / Entry arguments:
627 None
628
629An FDT map is just a header followed by an FDT containing a list of all the
Simon Glassfb30e292019-07-20 12:23:51 -0600630entries in the image. The root node corresponds to the image node in the
631original FDT, and an image-name property indicates the image name in that
632original tree.
Simon Glass0f621332019-07-08 14:25:27 -0600633
634The header is the string _FDTMAP_ followed by 8 unused bytes.
635
636When used, this entry will be populated with an FDT map which reflects the
637entries in the current image. Hierarchy is preserved, and all offsets and
638sizes are included.
639
640Note that the -u option must be provided to ensure that binman updates the
641FDT with the position of each entry.
642
Simon Glass0ac96b62021-03-18 20:25:15 +1300643Example output for a simple image with U-Boot and an FDT map::
Simon Glass0f621332019-07-08 14:25:27 -0600644
Simon Glass0ac96b62021-03-18 20:25:15 +1300645 / {
646 image-name = "binman";
647 size = <0x00000112>;
Simon Glass0f621332019-07-08 14:25:27 -0600648 image-pos = <0x00000000>;
649 offset = <0x00000000>;
Simon Glass0ac96b62021-03-18 20:25:15 +1300650 u-boot {
651 size = <0x00000004>;
652 image-pos = <0x00000000>;
653 offset = <0x00000000>;
654 };
655 fdtmap {
656 size = <0x0000010e>;
657 image-pos = <0x00000004>;
658 offset = <0x00000004>;
659 };
Simon Glass0f621332019-07-08 14:25:27 -0600660 };
Simon Glass0f621332019-07-08 14:25:27 -0600661
Simon Glassfb30e292019-07-20 12:23:51 -0600662If allow-repack is used then 'orig-offset' and 'orig-size' properties are
663added as necessary. See the binman README.
664
Simon Glass637958f2021-11-23 21:09:50 -0700665When extracting files, an alternative 'fdt' format is available for fdtmaps.
666Use `binman extract -F fdt ...` to use this. It will export a devicetree,
667without the fdtmap header, so it can be viewed with `fdtdump`.
Simon Glass0f621332019-07-08 14:25:27 -0600668
669
Simon Glass637958f2021-11-23 21:09:50 -0700670
Simon Glassa7c97782022-08-07 16:33:25 -0600671.. _etype_files:
672
Simon Glass8911fa12021-03-18 20:25:16 +1300673Entry: files: A set of files arranged in a section
674--------------------------------------------------
Simon Glassac6328c2018-09-14 04:57:28 -0600675
676Properties / Entry arguments:
677 - pattern: Filename pattern to match the files to include
Simon Glass51d02ad2020-10-26 17:40:07 -0600678 - files-compress: Compression algorithm to use:
Simon Glassac6328c2018-09-14 04:57:28 -0600679 none: No compression
680 lz4: Use lz4 compression (via 'lz4' command-line utility)
Simon Glass3f093a32021-03-18 20:24:53 +1300681 - files-align: Align each file to the given alignment
Simon Glassac6328c2018-09-14 04:57:28 -0600682
683This entry reads a number of files and places each in a separate sub-entry
684within this entry. To access these you need to enable device-tree updates
685at run-time so you can obtain the file positions.
Simon Glass7a61c6b2018-07-17 13:25:37 -0600686
687
Simon Glassac6328c2018-09-14 04:57:28 -0600688
Simon Glassa7c97782022-08-07 16:33:25 -0600689.. _etype_fill:
690
Simon Glass53f53992018-07-17 13:25:40 -0600691Entry: fill: An entry which is filled to a particular byte value
692----------------------------------------------------------------
693
694Properties / Entry arguments:
695 - fill-byte: Byte to use to fill the entry
696
697Note that the size property must be set since otherwise this entry does not
698know how large it should be.
699
700You can often achieve the same effect using the pad-byte property of the
701overall image, in that the space between entries will then be padded with
702that byte. But this entry is sometimes useful for explicitly setting the
703byte value of a region.
704
705
Simon Glassc7b010d2020-07-09 18:39:45 -0600706
Simon Glassa7c97782022-08-07 16:33:25 -0600707.. _etype_fit:
708
Simon Glass8911fa12021-03-18 20:25:16 +1300709Entry: fit: Flat Image Tree (FIT)
710---------------------------------
Simon Glass45d556d2020-07-09 18:39:45 -0600711
712This calls mkimage to create a FIT (U-Boot Flat Image Tree) based on the
713input provided.
714
715Nodes for the FIT should be written out in the binman configuration just as
716they would be in a file passed to mkimage.
717
Simon Glass0ac96b62021-03-18 20:25:15 +1300718For example, this creates an image containing a FIT with U-Boot SPL::
Simon Glass45d556d2020-07-09 18:39:45 -0600719
720 binman {
721 fit {
722 description = "Test FIT";
Simon Glassa435cd12020-09-01 05:13:59 -0600723 fit,fdt-list = "of-list";
Simon Glass45d556d2020-07-09 18:39:45 -0600724
725 images {
726 kernel@1 {
727 description = "SPL";
728 os = "u-boot";
729 type = "rkspi";
730 arch = "arm";
731 compression = "none";
732 load = <0>;
733 entry = <0>;
734
735 u-boot-spl {
736 };
737 };
738 };
739 };
740 };
741
Simon Glass912339f2022-02-08 11:50:03 -0700742More complex setups can be created, with generated nodes, as described
743below.
744
745Properties (in the 'fit' node itself)
746~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
747
748Special properties have a `fit,` prefix, indicating that they should be
749processed but not included in the final FIT.
750
751The top-level 'fit' node supports the following special properties:
752
753 fit,external-offset
754 Indicates that the contents of the FIT are external and provides the
755 external offset. This is passed to mkimage via the -E and -p flags.
756
Jonas Karlmanc59ea892023-01-21 19:01:39 +0000757 fit,align
758 Indicates what alignment to use for the FIT and its external data,
759 and provides the alignment to use. This is passed to mkimage via
760 the -B flag.
761
Simon Glass912339f2022-02-08 11:50:03 -0700762 fit,fdt-list
763 Indicates the entry argument which provides the list of device tree
764 files for the gen-fdt-nodes operation (as below). This is often
765 `of-list` meaning that `-a of-list="dtb1 dtb2..."` should be passed
766 to binman.
767
Simon Glass2d94c422023-07-18 07:23:59 -0600768 fit,fdt-list-val
769 As an alternative to fit,fdt-list the list of device tree files
770 can be provided in this property as a string list, e.g.::
771
772 fit,fdt-list-val = "dtb1", "dtb2";
773
Simon Glass912339f2022-02-08 11:50:03 -0700774Substitutions
775~~~~~~~~~~~~~
776
777Node names and property values support a basic string-substitution feature.
778Available substitutions for '@' nodes (and property values) are:
779
780SEQ:
781 Sequence number of the generated fdt (1, 2, ...)
782NAME
783 Name of the dtb as provided (i.e. without adding '.dtb')
784
785The `default` property, if present, will be automatically set to the name
786if of configuration whose devicetree matches the `default-dt` entry
787argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.
788
789Available substitutions for property values in these nodes are:
790
791DEFAULT-SEQ:
792 Sequence number of the default fdt, as provided by the 'default-dt'
793 entry argument
794
795Available operations
796~~~~~~~~~~~~~~~~~~~~
797
798You can add an operation to an '@' node to indicate which operation is
799required::
800
801 @fdt-SEQ {
802 fit,operation = "gen-fdt-nodes";
803 ...
804 };
805
806Available operations are:
807
808gen-fdt-nodes
809 Generate FDT nodes as above. This is the default if there is no
810 `fit,operation` property.
811
Simon Glass5f423422022-03-05 20:19:12 -0700812split-elf
813 Split an ELF file into a separate node for each segment.
814
Simon Glass912339f2022-02-08 11:50:03 -0700815Generating nodes from an FDT list (gen-fdt-nodes)
816~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
817
Simon Glassa435cd12020-09-01 05:13:59 -0600818U-Boot supports creating fdt and config nodes automatically. To do this,
Simon Glass9f1c6b92022-02-08 11:50:02 -0700819pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells
820binman that you want to generates nodes for two files: `file1.dtb` and
821`file2.dtb`. The `fit,fdt-list` property (see above) indicates that
822`of-list` should be used. If the property is missing you will get an error.
Simon Glassa435cd12020-09-01 05:13:59 -0600823
Simon Glass0ac96b62021-03-18 20:25:15 +1300824Then add a 'generator node', a node with a name starting with '@'::
Simon Glassa435cd12020-09-01 05:13:59 -0600825
826 images {
827 @fdt-SEQ {
828 description = "fdt-NAME";
829 type = "flat_dt";
830 compression = "none";
831 };
832 };
833
Simon Glass9f1c6b92022-02-08 11:50:02 -0700834This tells binman to create nodes `fdt-1` and `fdt-2` for each of your two
Simon Glassa435cd12020-09-01 05:13:59 -0600835files. All the properties you specify will be included in the node. This
836node acts like a template to generate the nodes. The generator node itself
837does not appear in the output - it is replaced with what binman generates.
Simon Glass9f1c6b92022-02-08 11:50:02 -0700838A 'data' property is created with the contents of the FDT file.
Simon Glassa435cd12020-09-01 05:13:59 -0600839
Simon Glass0ac96b62021-03-18 20:25:15 +1300840You can create config nodes in a similar way::
Simon Glassa435cd12020-09-01 05:13:59 -0600841
842 configurations {
843 default = "@config-DEFAULT-SEQ";
844 @config-SEQ {
845 description = "NAME";
Samuel Holland91079ac2020-10-21 21:12:14 -0500846 firmware = "atf";
847 loadables = "uboot";
Simon Glassa435cd12020-09-01 05:13:59 -0600848 fdt = "fdt-SEQ";
849 };
850 };
851
Simon Glass9f1c6b92022-02-08 11:50:02 -0700852This tells binman to create nodes `config-1` and `config-2`, i.e. a config
853for each of your two files.
Simon Glassa435cd12020-09-01 05:13:59 -0600854
Simon Glassa435cd12020-09-01 05:13:59 -0600855Note that if no devicetree files are provided (with '-a of-list' as above)
856then no nodes will be generated.
857
Simon Glass5f423422022-03-05 20:19:12 -0700858Generating nodes from an ELF file (split-elf)
859~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
860
861This uses the node as a template to generate multiple nodes. The following
862special properties are available:
863
864split-elf
865 Split an ELF file into a separate node for each segment. This uses the
866 node as a template to generate multiple nodes. The following special
867 properties are available:
868
869 fit,load
870 Generates a `load = <...>` property with the load address of the
871 segment
872
873 fit,entry
874 Generates a `entry = <...>` property with the entry address of the
875 ELF. This is only produced for the first entry
876
877 fit,data
878 Generates a `data = <...>` property with the contents of the segment
879
Jonas Karlman490f73c2023-01-21 19:02:12 +0000880 fit,firmware
881 Generates a `firmware = <...>` property. Provides a list of possible
882 nodes to be used as the `firmware` property value. The first valid
883 node is picked as the firmware. Any remaining valid nodes is
884 prepended to the `loadable` property generated by `fit,loadables`
885
Simon Glass5f423422022-03-05 20:19:12 -0700886 fit,loadables
887 Generates a `loadable = <...>` property with a list of the generated
888 nodes (including all nodes if this operation is used multiple times)
889
890
891Here is an example showing ATF, TEE and a device tree all combined::
892
893 fit {
894 description = "test-desc";
895 #address-cells = <1>;
896 fit,fdt-list = "of-list";
897
898 images {
899 u-boot {
900 description = "U-Boot (64-bit)";
901 type = "standalone";
902 os = "U-Boot";
903 arch = "arm64";
904 compression = "none";
Simon Glass72cc5382022-10-20 18:22:39 -0600905 load = <CONFIG_TEXT_BASE>;
Simon Glass5f423422022-03-05 20:19:12 -0700906 u-boot-nodtb {
907 };
908 };
909 @fdt-SEQ {
910 description = "fdt-NAME.dtb";
911 type = "flat_dt";
912 compression = "none";
913 };
914 @atf-SEQ {
915 fit,operation = "split-elf";
916 description = "ARM Trusted Firmware";
917 type = "firmware";
918 arch = "arm64";
919 os = "arm-trusted-firmware";
920 compression = "none";
921 fit,load;
922 fit,entry;
923 fit,data;
924
925 atf-bl31 {
926 };
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000927 hash {
928 algo = "sha256";
929 };
Simon Glass5f423422022-03-05 20:19:12 -0700930 };
931
932 @tee-SEQ {
933 fit,operation = "split-elf";
934 description = "TEE";
935 type = "tee";
936 arch = "arm64";
937 os = "tee";
938 compression = "none";
939 fit,load;
940 fit,entry;
941 fit,data;
942
943 tee-os {
944 };
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000945 hash {
946 algo = "sha256";
947 };
Simon Glass5f423422022-03-05 20:19:12 -0700948 };
949 };
950
951 configurations {
952 default = "@config-DEFAULT-SEQ";
953 @config-SEQ {
954 description = "conf-NAME.dtb";
955 fdt = "fdt-SEQ";
Jonas Karlman490f73c2023-01-21 19:02:12 +0000956 fit,firmware = "atf-1", "u-boot";
Simon Glass5f423422022-03-05 20:19:12 -0700957 fit,loadables;
958 };
959 };
960 };
961
962If ATF-BL31 is available, this generates a node for each segment in the
963ELF file, for example::
964
965 images {
966 atf-1 {
967 data = <...contents of first segment...>;
968 data-offset = <0x00000000>;
969 entry = <0x00040000>;
970 load = <0x00040000>;
971 compression = "none";
972 os = "arm-trusted-firmware";
973 arch = "arm64";
974 type = "firmware";
975 description = "ARM Trusted Firmware";
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000976 hash {
977 algo = "sha256";
978 value = <...hash of first segment...>;
979 };
Simon Glass5f423422022-03-05 20:19:12 -0700980 };
981 atf-2 {
982 data = <...contents of second segment...>;
983 load = <0xff3b0000>;
984 compression = "none";
985 os = "arm-trusted-firmware";
986 arch = "arm64";
987 type = "firmware";
988 description = "ARM Trusted Firmware";
Jonas Karlmand2c7d902023-01-21 19:01:48 +0000989 hash {
990 algo = "sha256";
991 value = <...hash of second segment...>;
992 };
Simon Glass5f423422022-03-05 20:19:12 -0700993 };
994 };
995
996The same applies for OP-TEE if that is available.
997
998If each binary is not available, the relevant template node (@atf-SEQ or
999@tee-SEQ) is removed from the output.
1000
1001This also generates a `config-xxx` node for each device tree in `of-list`.
1002Note that the U-Boot build system uses `-a of-list=$(CONFIG_OF_LIST)`
1003so you can use `CONFIG_OF_LIST` to define that list. In this example it is
1004set up for `firefly-rk3399` with a single device tree and the default set
1005with `-a default-dt=$(CONFIG_DEFAULT_DEVICE_TREE)`, so the resulting output
1006is::
1007
1008 configurations {
1009 default = "config-1";
1010 config-1 {
Jonas Karlman490f73c2023-01-21 19:02:12 +00001011 loadables = "u-boot", "atf-2", "atf-3", "tee-1", "tee-2";
Simon Glass5f423422022-03-05 20:19:12 -07001012 description = "rk3399-firefly.dtb";
1013 fdt = "fdt-1";
Jonas Karlman490f73c2023-01-21 19:02:12 +00001014 firmware = "atf-1";
Simon Glass5f423422022-03-05 20:19:12 -07001015 };
1016 };
1017
Jonas Karlman490f73c2023-01-21 19:02:12 +00001018U-Boot SPL can then load the firmware (ATF) and all the loadables (U-Boot
1019proper, ATF and TEE), then proceed with the boot.
Simon Glass5f423422022-03-05 20:19:12 -07001020
Simon Glass45d556d2020-07-09 18:39:45 -06001021
Simon Glassa7c97782022-08-07 16:33:25 -06001022
1023.. _etype_fmap:
Simon Glass45d556d2020-07-09 18:39:45 -06001024
Simon Glass7a61c6b2018-07-17 13:25:37 -06001025Entry: fmap: An entry which contains an Fmap section
1026----------------------------------------------------
1027
1028Properties / Entry arguments:
1029 None
1030
1031FMAP is a simple format used by flashrom, an open-source utility for
1032reading and writing the SPI flash, typically on x86 CPUs. The format
1033provides flashrom with a list of areas, so it knows what it in the flash.
1034It can then read or write just a single area, instead of the whole flash.
1035
1036The format is defined by the flashrom project, in the file lib/fmap.h -
1037see www.flashrom.org/Flashrom for more information.
1038
1039When used, this entry will be populated with an FMAP which reflects the
1040entries in the current image. Note that any hierarchy is squashed, since
Simon Glassb1d414c2021-04-03 11:05:10 +13001041FMAP does not support this. Sections are represented as an area appearing
1042before its contents, so that it is possible to reconstruct the hierarchy
1043from the FMAP by using the offset information. This convention does not
1044seem to be documented, but is used in Chromium OS.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001045
Simon Glasscda991e2023-02-12 17:11:15 -07001046To mark an area as preserved, use the normal 'preserved' flag in the entry.
1047This will result in the corresponding FMAP area having the
1048FMAP_AREA_PRESERVE flag. This flag does not automatically propagate down to
1049child entries.
1050
Simon Glassb1d414c2021-04-03 11:05:10 +13001051CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001052
1053
Simon Glassb1d414c2021-04-03 11:05:10 +13001054
Simon Glassa7c97782022-08-07 16:33:25 -06001055.. _etype_gbb:
1056
Simon Glassc1ae83c2018-07-17 13:25:44 -06001057Entry: gbb: An entry which contains a Chromium OS Google Binary Block
1058---------------------------------------------------------------------
1059
1060Properties / Entry arguments:
1061 - hardware-id: Hardware ID to use for this build (a string)
1062 - keydir: Directory containing the public keys to use
1063 - bmpblk: Filename containing images used by recovery
1064
1065Chromium OS uses a GBB to store various pieces of information, in particular
1066the root and recovery keys that are used to verify the boot process. Some
1067more details are here:
1068
1069 https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
1070
1071but note that the page dates from 2013 so is quite out of date. See
1072README.chromium for how to obtain the required keys and tools.
1073
1074
Simon Glassa7c97782022-08-07 16:33:25 -06001075
1076.. _etype_image_header:
Simon Glassc1ae83c2018-07-17 13:25:44 -06001077
Simon Glasscec34ba2019-07-08 14:25:28 -06001078Entry: image-header: An entry which contains a pointer to the FDT map
1079---------------------------------------------------------------------
1080
1081Properties / Entry arguments:
1082 location: Location of header ("start" or "end" of image). This is
1083 optional. If omitted then the entry must have an offset property.
1084
1085This adds an 8-byte entry to the start or end of the image, pointing to the
1086location of the FDT map. The format is a magic number followed by an offset
1087from the start or end of the image, in twos-compliment format.
1088
1089This entry must be in the top-level part of the image.
1090
1091NOTE: If the location is at the start/end, you will probably need to specify
1092sort-by-offset for the image, unless you actually put the image header
1093first/last in the entry list.
1094
1095
1096
Simon Glassa7c97782022-08-07 16:33:25 -06001097.. _etype_intel_cmc:
1098
Simon Glass8911fa12021-03-18 20:25:16 +13001099Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
1100-----------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001101
1102Properties / Entry arguments:
1103 - filename: Filename of file to read into entry
1104
1105This file contains microcode for some devices in a special format. An
1106example filename is 'Microcode/C0_22211.BIN'.
1107
1108See README.x86 for information about x86 binary blobs.
1109
1110
1111
Simon Glassa7c97782022-08-07 16:33:25 -06001112.. _etype_intel_descriptor:
1113
Simon Glass7a61c6b2018-07-17 13:25:37 -06001114Entry: intel-descriptor: Intel flash descriptor block (4KB)
1115-----------------------------------------------------------
1116
1117Properties / Entry arguments:
1118 filename: Filename of file containing the descriptor. This is typically
1119 a 4KB binary file, sometimes called 'descriptor.bin'
1120
1121This entry is placed at the start of flash and provides information about
1122the SPI flash regions. In particular it provides the base address and
1123size of the ME (Management Engine) region, allowing us to place the ME
1124binary in the right place.
1125
1126With this entry in your image, the position of the 'intel-me' entry will be
1127fixed in the image, which avoids you needed to specify an offset for that
1128region. This is useful, because it is not possible to change the position
1129of the ME region without updating the descriptor.
1130
1131See README.x86 for information about x86 binary blobs.
1132
1133
1134
Simon Glassa7c97782022-08-07 16:33:25 -06001135.. _etype_intel_fit:
1136
Simon Glass232f90c2019-08-24 07:22:50 -06001137Entry: intel-fit: Intel Firmware Image Table (FIT)
1138--------------------------------------------------
1139
1140This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
1141contains information about the firmware and microcode available in the
1142image.
1143
1144At present binman only supports a basic FIT with no microcode.
1145
1146
1147
Simon Glassa7c97782022-08-07 16:33:25 -06001148.. _etype_intel_fit_ptr:
1149
Simon Glass232f90c2019-08-24 07:22:50 -06001150Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
1151--------------------------------------------------------------
1152
1153This entry contains a pointer to the FIT. It is required to be at address
11540xffffffc0 in the image.
1155
1156
1157
Simon Glassa7c97782022-08-07 16:33:25 -06001158.. _etype_intel_fsp:
1159
Simon Glass8911fa12021-03-18 20:25:16 +13001160Entry: intel-fsp: Intel Firmware Support Package (FSP) file
1161-----------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001162
1163Properties / Entry arguments:
1164 - filename: Filename of file to read into entry
1165
1166This file contains binary blobs which are used on some devices to make the
1167platform work. U-Boot executes this code since it is not possible to set up
1168the hardware using U-Boot open-source code. Documentation is typically not
1169available in sufficient detail to allow this.
1170
1171An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
1172
1173See README.x86 for information about x86 binary blobs.
1174
1175
1176
Simon Glassa7c97782022-08-07 16:33:25 -06001177.. _etype_intel_fsp_m:
1178
Simon Glass8911fa12021-03-18 20:25:16 +13001179Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
1180--------------------------------------------------------------------
Simon Glassba7985d2019-08-24 07:23:07 -06001181
1182Properties / Entry arguments:
1183 - filename: Filename of file to read into entry
1184
1185This file contains a binary blob which is used on some devices to set up
1186SDRAM. U-Boot executes this code in SPL so that it can make full use of
1187memory. Documentation is typically not available in sufficient detail to
1188allow U-Boot do this this itself..
1189
1190An example filename is 'fsp_m.bin'
1191
1192See README.x86 for information about x86 binary blobs.
1193
1194
Simon Glassa7c97782022-08-07 16:33:25 -06001195
1196.. _etype_intel_fsp_s:
Simon Glassba7985d2019-08-24 07:23:07 -06001197
Simon Glass8911fa12021-03-18 20:25:16 +13001198Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
1199---------------------------------------------------------------------
Simon Glass4d9086d2019-10-20 21:31:35 -06001200
1201Properties / Entry arguments:
1202 - filename: Filename of file to read into entry
1203
1204This file contains a binary blob which is used on some devices to set up
1205the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
1206running, so that it can make full use of memory. Documentation is typically
1207not available in sufficient detail to allow U-Boot do this this itself.
1208
1209An example filename is 'fsp_s.bin'
1210
1211See README.x86 for information about x86 binary blobs.
1212
1213
1214
Simon Glassa7c97782022-08-07 16:33:25 -06001215.. _etype_intel_fsp_t:
1216
Simon Glass8911fa12021-03-18 20:25:16 +13001217Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
1218----------------------------------------------------------------------
Simon Glass9ea87b22019-10-20 21:31:36 -06001219
1220Properties / Entry arguments:
1221 - filename: Filename of file to read into entry
1222
1223This file contains a binary blob which is used on some devices to set up
1224temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
1225that it has access to memory for its stack and initial storage.
1226
1227An example filename is 'fsp_t.bin'
1228
1229See README.x86 for information about x86 binary blobs.
1230
1231
Simon Glassa7c97782022-08-07 16:33:25 -06001232
1233.. _etype_intel_ifwi:
Simon Glass9ea87b22019-10-20 21:31:36 -06001234
Simon Glass8911fa12021-03-18 20:25:16 +13001235Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
1236--------------------------------------------------------------
Simon Glassc2f1aed2019-07-08 13:18:56 -06001237
1238Properties / Entry arguments:
1239 - filename: Filename of file to read into entry. This is either the
1240 IFWI file itself, or a file that can be converted into one using a
1241 tool
1242 - convert-fit: If present this indicates that the ifwitool should be
1243 used to convert the provided file into a IFWI.
1244
1245This file contains code and data used by the SoC that is required to make
1246it work. It includes U-Boot TPL, microcode, things related to the CSE
1247(Converged Security Engine, the microcontroller that loads all the firmware)
1248and other items beyond the wit of man.
1249
1250A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
1251file that will be converted to an IFWI.
1252
1253The position of this entry is generally set by the intel-descriptor entry.
1254
1255The contents of the IFWI are specified by the subnodes of the IFWI node.
1256Each subnode describes an entry which is placed into the IFWFI with a given
1257sub-partition (and optional entry name).
1258
Simon Glass8a5e2492019-08-24 07:22:47 -06001259Properties for subnodes:
Simon Glass0ac96b62021-03-18 20:25:15 +13001260 - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
1261 - ifwi-entry: entry name t use, e.g. "IBBL"
1262 - ifwi-replace: if present, indicates that the item should be replaced
1263 in the IFWI. Otherwise it is added.
Simon Glass8a5e2492019-08-24 07:22:47 -06001264
Simon Glassc2f1aed2019-07-08 13:18:56 -06001265See README.x86 for information about x86 binary blobs.
1266
1267
1268
Simon Glassa7c97782022-08-07 16:33:25 -06001269.. _etype_intel_me:
1270
Simon Glass8911fa12021-03-18 20:25:16 +13001271Entry: intel-me: Intel Management Engine (ME) file
1272--------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001273
1274Properties / Entry arguments:
1275 - filename: Filename of file to read into entry
1276
1277This file contains code used by the SoC that is required to make it work.
1278The Management Engine is like a background task that runs things that are
Thomas Hebbfd37f242019-11-13 18:18:03 -08001279not clearly documented, but may include keyboard, display and network
Simon Glass7a61c6b2018-07-17 13:25:37 -06001280access. For platform that use ME it is not possible to disable it. U-Boot
1281does not directly execute code in the ME binary.
1282
1283A typical filename is 'me.bin'.
1284
Simon Glassc4056b82019-07-08 13:18:38 -06001285The position of this entry is generally set by the intel-descriptor entry.
1286
Simon Glass7a61c6b2018-07-17 13:25:37 -06001287See README.x86 for information about x86 binary blobs.
1288
1289
1290
Simon Glassa7c97782022-08-07 16:33:25 -06001291.. _etype_intel_mrc:
1292
Simon Glass8911fa12021-03-18 20:25:16 +13001293Entry: intel-mrc: Intel Memory Reference Code (MRC) file
1294--------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001295
1296Properties / Entry arguments:
1297 - filename: Filename of file to read into entry
1298
1299This file contains code for setting up the SDRAM on some Intel systems. This
1300is executed by U-Boot when needed early during startup. A typical filename
1301is 'mrc.bin'.
1302
1303See README.x86 for information about x86 binary blobs.
1304
1305
1306
Simon Glassa7c97782022-08-07 16:33:25 -06001307.. _etype_intel_refcode:
1308
Simon Glass8911fa12021-03-18 20:25:16 +13001309Entry: intel-refcode: Intel Reference Code file
1310-----------------------------------------------
Simon Glass17b84eb2019-05-17 22:00:53 -06001311
1312Properties / Entry arguments:
1313 - filename: Filename of file to read into entry
1314
1315This file contains code for setting up the platform on some Intel systems.
1316This is executed by U-Boot when needed early during startup. A typical
1317filename is 'refcode.bin'.
1318
1319See README.x86 for information about x86 binary blobs.
1320
1321
1322
Simon Glassa7c97782022-08-07 16:33:25 -06001323.. _etype_intel_vbt:
1324
Simon Glass8911fa12021-03-18 20:25:16 +13001325Entry: intel-vbt: Intel Video BIOS Table (VBT) file
1326---------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001327
1328Properties / Entry arguments:
1329 - filename: Filename of file to read into entry
1330
1331This file contains code that sets up the integrated graphics subsystem on
1332some Intel SoCs. U-Boot executes this when the display is started up.
1333
1334See README.x86 for information about Intel binary blobs.
1335
1336
1337
Simon Glassa7c97782022-08-07 16:33:25 -06001338.. _etype_intel_vga:
1339
Simon Glass8911fa12021-03-18 20:25:16 +13001340Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
1341---------------------------------------------------------
Simon Glass7a61c6b2018-07-17 13:25:37 -06001342
1343Properties / Entry arguments:
1344 - filename: Filename of file to read into entry
1345
1346This file contains code that sets up the integrated graphics subsystem on
1347some Intel SoCs. U-Boot executes this when the display is started up.
1348
1349This is similar to the VBT file but in a different format.
1350
1351See README.x86 for information about Intel binary blobs.
1352
1353
1354
Simon Glassa7c97782022-08-07 16:33:25 -06001355.. _etype_mkimage:
1356
Simon Glass8911fa12021-03-18 20:25:16 +13001357Entry: mkimage: Binary produced by mkimage
1358------------------------------------------
Simon Glass48f3aad2020-07-09 18:39:31 -06001359
1360Properties / Entry arguments:
Simon Glass42074dc2022-08-13 11:40:47 -06001361 - args: Arguments to pass
Simon Glass8fbca772022-08-13 11:40:48 -06001362 - data-to-imagename: Indicates that the -d data should be passed in as
1363 the image name also (-n)
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001364 - multiple-data-files: boolean to tell binman to pass all files as
1365 datafiles to mkimage instead of creating a temporary file the result
1366 of datafiles concatenation
Simon Glassda6a9082023-01-07 14:07:10 -07001367 - filename: filename of output binary generated by mkimage
Simon Glass48f3aad2020-07-09 18:39:31 -06001368
Simon Glass42074dc2022-08-13 11:40:47 -06001369The data passed to mkimage via the -d flag is collected from subnodes of the
1370mkimage node, e.g.::
Simon Glass48f3aad2020-07-09 18:39:31 -06001371
1372 mkimage {
Simon Glassda6a9082023-01-07 14:07:10 -07001373 filename = "imximage.bin";
Simon Glass48f3aad2020-07-09 18:39:31 -06001374 args = "-n test -T imximage";
1375
1376 u-boot-spl {
1377 };
1378 };
1379
Simon Glass42074dc2022-08-13 11:40:47 -06001380This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
Simon Glassda6a9082023-01-07 14:07:10 -07001381file, with mkimage being called like this::
Simon Glass42074dc2022-08-13 11:40:47 -06001382
1383 mkimage -d <data_file> -n test -T imximage <output_file>
1384
1385The output from mkimage then becomes part of the image produced by
Simon Glassda6a9082023-01-07 14:07:10 -07001386binman but also is written into `imximage.bin` file. If you need to put
1387multiple things in the data file, you can use a section, or just multiple
1388subnodes like this::
Simon Glass42074dc2022-08-13 11:40:47 -06001389
1390 mkimage {
1391 args = "-n test -T imximage";
1392
1393 u-boot-spl {
1394 };
1395
1396 u-boot-tpl {
1397 };
1398 };
Simon Glass48f3aad2020-07-09 18:39:31 -06001399
Simon Glassda6a9082023-01-07 14:07:10 -07001400Note that binman places the contents (here SPL and TPL) into a single file
1401and passes that to mkimage using the -d option.
1402
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001403To pass all datafiles untouched to mkimage::
1404
1405 mkimage {
Simon Glassda6a9082023-01-07 14:07:10 -07001406 args = "-n rk3399 -T rkspi";
1407 multiple-data-files;
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001408
Simon Glassda6a9082023-01-07 14:07:10 -07001409 u-boot-tpl {
1410 };
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001411
Simon Glassda6a9082023-01-07 14:07:10 -07001412 u-boot-spl {
1413 };
Quentin Schulz9b5c6482022-09-02 15:10:48 +02001414 };
1415
1416This calls mkimage to create a Rockchip RK3399-specific first stage
1417bootloader, made of TPL+SPL. Since this first stage bootloader requires to
1418align the TPL and SPL but also some weird hacks that is handled by mkimage
1419directly, binman is told to not perform the concatenation of datafiles prior
1420to passing the data to mkimage.
1421
Simon Glass948dd3a2022-02-08 11:49:58 -07001422To use CONFIG options in the arguments, use a string list instead, as in
1423this example which also produces four arguments::
1424
1425 mkimage {
1426 args = "-n", CONFIG_SYS_SOC, "-T imximage";
1427
1428 u-boot-spl {
1429 };
1430 };
1431
Simon Glass8fbca772022-08-13 11:40:48 -06001432If you need to pass the input data in with the -n argument as well, then use
1433the 'data-to-imagename' property::
1434
1435 mkimage {
1436 args = "-T imximage";
Simon Glassda6a9082023-01-07 14:07:10 -07001437 data-to-imagename;
Simon Glass8fbca772022-08-13 11:40:48 -06001438
1439 u-boot-spl {
1440 };
1441 };
1442
1443That will pass the data to mkimage both as the data file (with -d) and as
Simon Glassda6a9082023-01-07 14:07:10 -07001444the image name (with -n). In both cases, a filename is passed as the
1445argument, with the actual data being in that file.
Simon Glass948dd3a2022-02-08 11:49:58 -07001446
Simon Glassda6a9082023-01-07 14:07:10 -07001447If need to pass different data in with -n, then use an `imagename` subnode::
Simon Glassb1669752022-08-13 11:40:49 -06001448
1449 mkimage {
1450 args = "-T imximage";
1451
1452 imagename {
1453 blob {
1454 filename = "spl/u-boot-spl.cfgout"
1455 };
1456 };
1457
1458 u-boot-spl {
1459 };
1460 };
1461
1462This will pass in u-boot-spl as the input data and the .cfgout file as the
1463-n data.
1464
Simon Glassa7c97782022-08-07 16:33:25 -06001465
Simon Glassda6a9082023-01-07 14:07:10 -07001466
Simon Glassa4948b22023-01-11 16:10:14 -07001467.. _etype_null:
1468
1469Entry: null: An entry which has no contents of its own
1470------------------------------------------------------
1471
1472Note that the size property must be set since otherwise this entry does not
1473know how large it should be.
1474
1475The contents are set by the containing section, e.g. the section's pad
1476byte.
1477
1478
1479
Simon Glassa7c97782022-08-07 16:33:25 -06001480.. _etype_opensbi:
Simon Glass48f3aad2020-07-09 18:39:31 -06001481
Bin Mengc0b15742021-05-10 20:23:33 +08001482Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
1483----------------------------------------------
1484
1485Properties / Entry arguments:
1486 - opensbi-path: Filename of file to read into entry. This is typically
1487 called fw_dynamic.bin
1488
1489This entry holds the run-time firmware, typically started by U-Boot SPL.
1490See the U-Boot README for your architecture or board for how to use it. See
1491https://github.com/riscv/opensbi for more information about OpenSBI.
1492
1493
1494
Simon Glassa7c97782022-08-07 16:33:25 -06001495.. _etype_powerpc_mpc85xx_bootpg_resetvec:
1496
Jagdish Gediya311d4842018-09-03 21:35:08 +05301497Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
1498-----------------------------------------------------------------------------------------
1499
1500Properties / Entry arguments:
1501 - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
1502
Thomas Hebbfd37f242019-11-13 18:18:03 -08001503This entry is valid for PowerPC mpc85xx cpus. This entry holds
Jagdish Gediya311d4842018-09-03 21:35:08 +05301504'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
1505placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
1506
Simon Glass136dd352020-10-26 17:39:59 -06001507
Simon Glassa7c97782022-08-07 16:33:25 -06001508
1509.. _etype_pre_load:
Simon Glass136dd352020-10-26 17:39:59 -06001510
Philippe Reynesebe96cb2022-03-28 22:57:04 +02001511Entry: pre-load: Pre load image header
1512--------------------------------------
1513
1514Properties / Entry arguments:
Simon Glass9f571582022-08-13 11:40:43 -06001515 - pre-load-key-path: Path of the directory that store key (provided by
1516 the environment variable PRE_LOAD_KEY_PATH)
Philippe Reynesebe96cb2022-03-28 22:57:04 +02001517 - content: List of phandles to entries to sign
1518 - algo-name: Hash and signature algo to use for the signature
1519 - padding-name: Name of the padding (pkcs-1.5 or pss)
1520 - key-name: Filename of the private key to sign
1521 - header-size: Total size of the header
1522 - version: Version of the header
1523
1524This entry creates a pre-load header that contains a global
1525image signature.
1526
1527For example, this creates an image with a pre-load header and a binary::
1528
1529 binman {
1530 image2 {
1531 filename = "sandbox.bin";
1532
1533 pre-load {
1534 content = <&image>;
1535 algo-name = "sha256,rsa2048";
1536 padding-name = "pss";
1537 key-name = "private.pem";
1538 header-size = <4096>;
1539 version = <1>;
1540 };
1541
1542 image: blob-ext {
1543 filename = "sandbox.itb";
1544 };
1545 };
1546 };
1547
1548
1549
Jonas Karlman35305492023-02-25 19:01:33 +00001550.. _etype_rockchip_tpl:
1551
1552Entry: rockchip-tpl: Rockchip TPL binary
1553----------------------------------------
1554
1555Properties / Entry arguments:
1556 - rockchip-tpl-path: Filename of file to read into the entry,
1557 typically <soc>_ddr_<version>.bin
1558
1559This entry holds an external TPL binary used by some Rockchip SoCs
1560instead of normal U-Boot TPL, typically to initialize DRAM.
1561
1562
1563
Simon Glassa7c97782022-08-07 16:33:25 -06001564.. _etype_scp:
1565
Simon Glass8911fa12021-03-18 20:25:16 +13001566Entry: scp: System Control Processor (SCP) firmware blob
1567--------------------------------------------------------
Simon Glass136dd352020-10-26 17:39:59 -06001568
1569Properties / Entry arguments:
1570 - scp-path: Filename of file to read into the entry, typically scp.bin
1571
1572This entry holds firmware for an external platform-specific coprocessor.
Jagdish Gediya311d4842018-09-03 21:35:08 +05301573
1574
Simon Glass136dd352020-10-26 17:39:59 -06001575
Simon Glassa7c97782022-08-07 16:33:25 -06001576.. _etype_section:
1577
Simon Glass7a61c6b2018-07-17 13:25:37 -06001578Entry: section: Entry that contains other entries
1579-------------------------------------------------
1580
Simon Glasscc9a41c2021-11-23 11:03:49 -07001581A section is an entry which can contain other entries, thus allowing
1582hierarchical images to be created. See 'Sections and hierarchical images'
1583in the binman README for more information.
1584
1585The base implementation simply joins the various entries together, using
1586various rules about alignment, etc.
1587
1588Subclassing
1589~~~~~~~~~~~
1590
1591This class can be subclassed to support other file formats which hold
1592multiple entries, such as CBFS. To do this, override the following
1593functions. The documentation here describes what your function should do.
1594For example code, see etypes which subclass `Entry_section`, or `cbfs.py`
1595for a more involved example::
1596
1597 $ grep -l \(Entry_section tools/binman/etype/*.py
1598
1599ReadNode()
1600 Call `super().ReadNode()`, then read any special properties for the
1601 section. Then call `self.ReadEntries()` to read the entries.
1602
1603 Binman calls this at the start when reading the image description.
1604
1605ReadEntries()
1606 Read in the subnodes of the section. This may involve creating entries
1607 of a particular etype automatically, as well as reading any special
1608 properties in the entries. For each entry, entry.ReadNode() should be
1609 called, to read the basic entry properties. The properties should be
1610 added to `self._entries[]`, in the correct order, with a suitable name.
1611
1612 Binman calls this at the start when reading the image description.
1613
1614BuildSectionData(required)
1615 Create the custom file format that you want and return it as bytes.
1616 This likely sets up a file header, then loops through the entries,
1617 adding them to the file. For each entry, call `entry.GetData()` to
1618 obtain the data. If that returns None, and `required` is False, then
1619 this method must give up and return None. But if `required` is True then
1620 it should assume that all data is valid.
1621
1622 Binman calls this when packing the image, to find out the size of
1623 everything. It is called again at the end when building the final image.
1624
1625SetImagePos(image_pos):
1626 Call `super().SetImagePos(image_pos)`, then set the `image_pos` values
1627 for each of the entries. This should use the custom file format to find
1628 the `start offset` (and `image_pos`) of each entry. If the file format
1629 uses compression in such a way that there is no offset available (other
1630 than reading the whole file and decompressing it), then the offsets for
1631 affected entries can remain unset (`None`). The size should also be set
1632 if possible.
Simon Glass0ac96b62021-03-18 20:25:15 +13001633
Simon Glasscc9a41c2021-11-23 11:03:49 -07001634 Binman calls this after the image has been packed, to update the
1635 location that all the entries ended up at.
Simon Glass0ac96b62021-03-18 20:25:15 +13001636
Simon Glass637958f2021-11-23 21:09:50 -07001637ReadChildData(child, decomp, alt_format):
Simon Glasscc9a41c2021-11-23 11:03:49 -07001638 The default version of this may be good enough, if you are able to
1639 implement SetImagePos() correctly. But that is a bit of a bypass, so
1640 you can override this method to read from your custom file format. It
1641 should read the entire entry containing the custom file using
1642 `super().ReadData(True)`, then parse the file to get the data for the
1643 given child, then return that data.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001644
Simon Glasscc9a41c2021-11-23 11:03:49 -07001645 If your file format supports compression, the `decomp` argument tells
1646 you whether to return the compressed data (`decomp` is False) or to
1647 uncompress it first, then return the uncompressed data (`decomp` is
1648 True). This is used by the `binman extract -U` option.
Simon Glass21db0ff2020-09-01 05:13:54 -06001649
Simon Glass637958f2021-11-23 21:09:50 -07001650 If your entry supports alternative formats, the alt_format provides the
1651 alternative format that the user has selected. Your function should
1652 return data in that format. This is used by the 'binman extract -l'
1653 option.
1654
Simon Glasscc9a41c2021-11-23 11:03:49 -07001655 Binman calls this when reading in an image, in order to populate all the
1656 entries with the data from that image (`binman ls`).
1657
1658WriteChildData(child):
1659 Binman calls this after `child.data` is updated, to inform the custom
1660 file format about this, in case it needs to do updates.
1661
1662 The default version of this does nothing and probably needs to be
1663 overridden for the 'binman replace' command to work. Your version should
1664 use `child.data` to update the data for that child in the custom file
1665 format.
1666
1667 Binman calls this when updating an image that has been read in and in
1668 particular to update the data for a particular entry (`binman replace`)
1669
1670Properties / Entry arguments
1671~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1672
1673See :ref:`develop/package/binman:Image description format` for more
1674information.
1675
1676align-default
1677 Default alignment for this section, if no alignment is given in the
1678 entry
1679
1680pad-byte
1681 Pad byte to use when padding
1682
1683sort-by-offset
1684 True if entries should be sorted by offset, False if they must be
1685 in-order in the device tree description
1686
1687end-at-4gb
1688 Used to build an x86 ROM which ends at 4GB (2^32)
1689
1690name-prefix
1691 Adds a prefix to the name of every entry in the section when writing out
1692 the map
1693
1694skip-at-start
1695 Number of bytes before the first entry starts. These effectively adjust
1696 the starting offset of entries. For example, if this is 16, then the
1697 first entry would start at 16. An entry with offset = 20 would in fact
1698 be written at offset 4 in the image file, since the first 16 bytes are
1699 skipped when writing.
Simon Glassb1d414c2021-04-03 11:05:10 +13001700
Simon Glassda6a9082023-01-07 14:07:10 -07001701filename
1702 filename to write the unpadded section contents to within the output
1703 directory (None to skip this).
1704
Simon Glass39dd2152019-07-08 14:25:47 -06001705Since a section is also an entry, it inherits all the properies of entries
1706too.
1707
Simon Glasscc9a41c2021-11-23 11:03:49 -07001708Note that the `allow_missing` member controls whether this section permits
1709external blobs to be missing their contents. The option will produce an
1710image but of course it will not work. It is useful to make sure that
1711Continuous Integration systems can build without the binaries being
1712available. This is set by the `SetAllowMissing()` method, if
1713`--allow-missing` is passed to binman.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001714
1715
1716
Simon Glassa7c97782022-08-07 16:33:25 -06001717.. _etype_tee_os:
1718
Roger Quadros5cdcea02022-02-19 20:50:04 +02001719Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
1720---------------------------------------------------------------
1721
1722Properties / Entry arguments:
1723 - tee-os-path: Filename of file to read into entry. This is typically
Simon Glassad5cfe12023-01-07 14:07:14 -07001724 called tee.bin or tee.elf
Roger Quadros5cdcea02022-02-19 20:50:04 +02001725
1726This entry holds the run-time firmware, typically started by U-Boot SPL.
1727See the U-Boot README for your architecture or board for how to use it. See
1728https://github.com/OP-TEE/optee_os for more information about OP-TEE.
1729
Simon Glassad5cfe12023-01-07 14:07:14 -07001730Note that if the file is in ELF format, it must go in a FIT. In that case,
1731this entry will mark itself as absent, providing the data only through the
1732read_elf_segments() method.
1733
1734Marking this entry as absent means that it if is used in the wrong context
1735it can be automatically dropped. Thus it is possible to add an OP-TEE entry
1736like this::
1737
1738 binman {
1739 tee-os {
1740 };
1741 };
1742
1743and pass either an ELF or plain binary in with -a tee-os-path <filename>
1744and have binman do the right thing:
1745
1746 - include the entry if tee.bin is provided and it does NOT have the v1
1747 header
1748 - drop it otherwise
1749
1750When used within a FIT, we can do::
1751
1752 binman {
1753 fit {
1754 tee-os {
1755 };
1756 };
1757 };
1758
1759which will split the ELF into separate nodes for each segment, if an ELF
1760file is provided (see :ref:`etype_fit`), or produce a single node if the
1761OP-TEE binary v1 format is provided (see optee_doc_) .
1762
1763.. _optee_doc: https://optee.readthedocs.io/en/latest/architecture/core.html#partitioning-of-the-binary
1764
Roger Quadros5cdcea02022-02-19 20:50:04 +02001765
1766
Simon Glassa7c97782022-08-07 16:33:25 -06001767.. _etype_text:
1768
Simon Glass7a61c6b2018-07-17 13:25:37 -06001769Entry: text: An entry which contains text
1770-----------------------------------------
1771
1772The text can be provided either in the node itself or by a command-line
1773argument. There is a level of indirection to allow multiple text strings
1774and sharing of text.
1775
1776Properties / Entry arguments:
1777 text-label: The value of this string indicates the property / entry-arg
1778 that contains the string to place in the entry
1779 <xxx> (actual name is the value of text-label): contains the string to
1780 place in the entry.
Simon Glass47f6a622019-07-08 13:18:40 -06001781 <text>: The text to place in the entry (overrides the above mechanism).
1782 This is useful when the text is constant.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001783
Simon Glass0ac96b62021-03-18 20:25:15 +13001784Example node::
Simon Glass7a61c6b2018-07-17 13:25:37 -06001785
1786 text {
1787 size = <50>;
1788 text-label = "message";
1789 };
1790
1791You can then use:
1792
1793 binman -amessage="this is my message"
1794
1795and binman will insert that string into the entry.
1796
Simon Glass0ac96b62021-03-18 20:25:15 +13001797It is also possible to put the string directly in the node::
Simon Glass7a61c6b2018-07-17 13:25:37 -06001798
1799 text {
1800 size = <8>;
1801 text-label = "message";
1802 message = "a message directly in the node"
1803 };
1804
Simon Glass0ac96b62021-03-18 20:25:15 +13001805or just::
Simon Glass47f6a622019-07-08 13:18:40 -06001806
1807 text {
1808 size = <8>;
1809 text = "some text directly in the node"
1810 };
1811
Simon Glass7a61c6b2018-07-17 13:25:37 -06001812The text is not itself nul-terminated. This can be achieved, if required,
1813by setting the size of the entry to something larger than the text.
1814
1815
1816
Neha Malcom Francis3b788942023-07-22 00:14:24 +05301817.. _etype_ti_board_config:
1818
1819Entry: ti-board-config: An entry containing a TI schema validated board config binary
1820-------------------------------------------------------------------------------------
1821
1822This etype supports generation of two kinds of board configuration
1823binaries: singular board config binary as well as combined board config
1824binary.
1825
1826Properties / Entry arguments:
1827 - config-file: File containing board configuration data in YAML
1828 - schema-file: File containing board configuration YAML schema against
1829 which the config file is validated
1830
1831Output files:
1832 - board config binary: File containing board configuration binary
1833
1834These above parameters are used only when the generated binary is
1835intended to be a single board configuration binary. Example::
1836
1837 my-ti-board-config {
1838 ti-board-config {
1839 config = "board-config.yaml";
1840 schema = "schema.yaml";
1841 };
1842 };
1843
1844To generate a combined board configuration binary, we pack the
1845needed individual binaries into a ti-board-config binary. In this case,
1846the available supported subnode names are board-cfg, pm-cfg, sec-cfg and
1847rm-cfg. The final binary is prepended with a header containing details about
1848the included board config binaries. Example::
1849
1850 my-combined-ti-board-config {
1851 ti-board-config {
1852 board-cfg {
1853 config = "board-cfg.yaml";
1854 schema = "schema.yaml";
1855 };
1856 sec-cfg {
1857 config = "sec-cfg.yaml";
1858 schema = "schema.yaml";
1859 };
1860 }
1861 }
1862
1863
1864
Neha Malcom Francis5f5f0a62023-07-22 00:14:25 +05301865.. _etype_ti_secure:
1866
1867Entry: ti-secure: Entry containing a TI x509 certificate binary
1868---------------------------------------------------------------
1869
1870Properties / Entry arguments:
1871 - content: List of phandles to entries to sign
1872 - keyfile: Filename of file containing key to sign binary with
1873 - sha: Hash function to be used for signing
1874
1875Output files:
1876 - input.<unique_name> - input file passed to openssl
1877 - config.<unique_name> - input file generated for openssl (which is
1878 used as the config file)
1879 - cert.<unique_name> - output file generated by openssl (which is
1880 used as the entry contents)
1881
1882openssl signs the provided data, using the TI templated config file and
1883writes the signature in this entry. This allows verification that the
1884data is genuine.
1885
1886
1887
1888.. _etype_ti_secure_rom:
1889
1890Entry: ti-secure-rom: Entry containing a TI x509 certificate binary for images booted by ROM
1891--------------------------------------------------------------------------------------------
1892
1893Properties / Entry arguments:
1894 - keyfile: Filename of file containing key to sign binary with
1895 - combined: boolean if device follows combined boot flow
1896 - countersign: boolean if device contains countersigned system firmware
1897 - load: load address of SPL
1898 - sw-rev: software revision
1899 - sha: Hash function to be used for signing
1900 - core: core on which bootloader runs, valid cores are 'secure' and 'public'
1901 - content: phandle of SPL in case of legacy bootflow or phandles of component binaries
1902 in case of combined bootflow
1903
1904The following properties are only for generating a combined bootflow binary:
1905 - sysfw-inner-cert: boolean if binary contains sysfw inner certificate
1906 - dm-data: boolean if binary contains dm-data binary
1907 - content-sbl: phandle of SPL binary
1908 - content-sysfw: phandle of sysfw binary
1909 - content-sysfw-data: phandle of sysfw-data or tifs-data binary
1910 - content-sysfw-inner-cert (optional): phandle of sysfw inner certificate binary
1911 - content-dm-data (optional): phandle of dm-data binary
1912 - load-sysfw: load address of sysfw binary
1913 - load-sysfw-data: load address of sysfw-data or tifs-data binary
1914 - load-sysfw-inner-cert (optional): load address of sysfw inner certificate binary
1915 - load-dm-data (optional): load address of dm-data binary
1916
1917Output files:
1918 - input.<unique_name> - input file passed to openssl
1919 - config.<unique_name> - input file generated for openssl (which is
1920 used as the config file)
1921 - cert.<unique_name> - output file generated by openssl (which is
1922 used as the entry contents)
1923
1924openssl signs the provided data, using the TI templated config file and
1925writes the signature in this entry. This allows verification that the
1926data is genuine.
1927
1928
1929
Simon Glassa7c97782022-08-07 16:33:25 -06001930.. _etype_u_boot:
1931
Simon Glass7a61c6b2018-07-17 13:25:37 -06001932Entry: u-boot: U-Boot flat binary
1933---------------------------------
1934
1935Properties / Entry arguments:
1936 - filename: Filename of u-boot.bin (default 'u-boot.bin')
1937
1938This is the U-Boot binary, containing relocation information to allow it
1939to relocate itself at runtime. The binary typically includes a device tree
Simon Glass718b5292021-03-18 20:25:07 +13001940blob at the end of it.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001941
Simon Glass18ed9962023-01-07 14:07:11 -07001942U-Boot can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001943
Simon Glass718b5292021-03-18 20:25:07 +13001944Note that this entry is automatically replaced with u-boot-expanded unless
Simon Glass7098b7f2021-03-21 18:24:30 +13001945--no-expanded is used or the node has a 'no-expanded' property.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001946
1947
Simon Glass718b5292021-03-18 20:25:07 +13001948
Simon Glassa7c97782022-08-07 16:33:25 -06001949.. _etype_u_boot_dtb:
1950
Simon Glass7a61c6b2018-07-17 13:25:37 -06001951Entry: u-boot-dtb: U-Boot device tree
1952-------------------------------------
1953
1954Properties / Entry arguments:
1955 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1956
1957This is the U-Boot device tree, containing configuration information for
1958U-Boot. U-Boot needs this to know what devices are present and which drivers
1959to activate.
1960
Simon Glasse219aa42018-09-14 04:57:24 -06001961Note: This is mostly an internal entry type, used by others. This allows
1962binman to know which entries contain a device tree.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001963
1964
Simon Glassa7c97782022-08-07 16:33:25 -06001965
1966.. _etype_u_boot_dtb_with_ucode:
Simon Glass7a61c6b2018-07-17 13:25:37 -06001967
1968Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
1969-----------------------------------------------------------------------------------
1970
1971Properties / Entry arguments:
1972 - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1973
1974See Entry_u_boot_ucode for full details of the three entries involved in
1975this process. This entry provides the U-Boot device-tree file, which
1976contains the microcode. If the microcode is not being collated into one
1977place then the offset and size of the microcode is recorded by this entry,
Simon Glass537e0062021-03-18 20:24:54 +13001978for use by u-boot-with-ucode_ptr. If it is being collated, then this
Simon Glass7a61c6b2018-07-17 13:25:37 -06001979entry deletes the microcode from the device tree (to save space) and makes
Simon Glass537e0062021-03-18 20:24:54 +13001980it available to u-boot-ucode.
Simon Glass7a61c6b2018-07-17 13:25:37 -06001981
1982
1983
Simon Glassa7c97782022-08-07 16:33:25 -06001984.. _etype_u_boot_elf:
1985
Simon Glassb1714232018-09-14 04:57:35 -06001986Entry: u-boot-elf: U-Boot ELF image
1987-----------------------------------
1988
1989Properties / Entry arguments:
1990 - filename: Filename of u-boot (default 'u-boot')
1991
1992This is the U-Boot ELF image. It does not include a device tree but can be
1993relocated to any address for execution.
1994
1995
Simon Glassa7c97782022-08-07 16:33:25 -06001996
1997.. _etype_u_boot_env:
Simon Glassb1714232018-09-14 04:57:35 -06001998
Simon Glass136dd352020-10-26 17:39:59 -06001999Entry: u-boot-env: An entry which contains a U-Boot environment
2000---------------------------------------------------------------
2001
2002Properties / Entry arguments:
2003 - filename: File containing the environment text, with each line in the
2004 form var=value
2005
2006
Simon Glass718b5292021-03-18 20:25:07 +13002007
Simon Glassa7c97782022-08-07 16:33:25 -06002008.. _etype_u_boot_expanded:
2009
Simon Glass718b5292021-03-18 20:25:07 +13002010Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
2011------------------------------------------------------------------------------
2012
2013This is a section containing the U-Boot binary and a devicetree. Using this
2014entry type automatically creates this section, with the following entries
2015in it:
2016
2017 u-boot-nodtb
2018 u-boot-dtb
2019
2020Having the devicetree separate allows binman to update it in the final
2021image, so that the entries positions are provided to the running U-Boot.
2022
2023
Simon Glass136dd352020-10-26 17:39:59 -06002024
Simon Glassa7c97782022-08-07 16:33:25 -06002025.. _etype_u_boot_img:
2026
Simon Glass7a61c6b2018-07-17 13:25:37 -06002027Entry: u-boot-img: U-Boot legacy image
2028--------------------------------------
2029
2030Properties / Entry arguments:
2031 - filename: Filename of u-boot.img (default 'u-boot.img')
2032
2033This is the U-Boot binary as a packaged image, in legacy format. It has a
2034header which allows it to be loaded at the correct address for execution.
2035
2036You should use FIT (Flat Image Tree) instead of the legacy image for new
2037applications.
2038
2039
2040
Simon Glassa7c97782022-08-07 16:33:25 -06002041.. _etype_u_boot_nodtb:
2042
Simon Glass7a61c6b2018-07-17 13:25:37 -06002043Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
2044--------------------------------------------------------------------
2045
2046Properties / Entry arguments:
Simon Glass537e0062021-03-18 20:24:54 +13002047 - filename: Filename to include (default 'u-boot-nodtb.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002048
2049This is the U-Boot binary, containing relocation information to allow it
2050to relocate itself at runtime. It does not include a device tree blob at
Simon Glass537e0062021-03-18 20:24:54 +13002051the end of it so normally cannot work without it. You can add a u-boot-dtb
Simon Glass718b5292021-03-18 20:25:07 +13002052entry after this one, or use a u-boot entry instead, normally expands to a
2053section containing u-boot and u-boot-dtb
Simon Glass7a61c6b2018-07-17 13:25:37 -06002054
2055
2056
Simon Glassa7c97782022-08-07 16:33:25 -06002057.. _etype_u_boot_spl:
2058
Simon Glass7a61c6b2018-07-17 13:25:37 -06002059Entry: u-boot-spl: U-Boot SPL binary
2060------------------------------------
2061
2062Properties / Entry arguments:
2063 - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
2064
2065This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
2066binary which loads before U-Boot proper, typically into on-chip SRAM. It is
2067responsible for locating, loading and jumping to U-Boot. Note that SPL is
2068not relocatable so must be loaded to the correct address in SRAM, or written
Simon Glass8425a1f2018-07-17 13:25:48 -06002069to run from the correct address if direct flash execution is possible (e.g.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002070on x86 devices).
2071
Simon Glass18ed9962023-01-07 14:07:11 -07002072SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002073
2074in the binman README for more information.
2075
2076The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2077binman uses that to look up symbols to write into the SPL binary.
2078
Simon Glass718b5292021-03-18 20:25:07 +13002079Note that this entry is automatically replaced with u-boot-spl-expanded
Simon Glass7098b7f2021-03-21 18:24:30 +13002080unless --no-expanded is used or the node has a 'no-expanded' property.
Simon Glass718b5292021-03-18 20:25:07 +13002081
Simon Glass7a61c6b2018-07-17 13:25:37 -06002082
2083
Simon Glassa7c97782022-08-07 16:33:25 -06002084.. _etype_u_boot_spl_bss_pad:
2085
Simon Glass7a61c6b2018-07-17 13:25:37 -06002086Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
2087---------------------------------------------------------------------
2088
2089Properties / Entry arguments:
2090 None
2091
Simon Glass308939b2021-03-18 20:24:55 +13002092This holds the padding added after the SPL binary to cover the BSS (Block
2093Started by Symbol) region. This region holds the various variables used by
2094SPL. It is set to 0 by SPL when it starts up. If you want to append data to
2095the SPL image (such as a device tree file), you must pad out the BSS region
2096to avoid the data overlapping with U-Boot variables. This entry is useful in
2097that case. It automatically pads out the entry size to cover both the code,
2098data and BSS.
2099
2100The contents of this entry will a certain number of zero bytes, determined
2101by __bss_size
Simon Glass7a61c6b2018-07-17 13:25:37 -06002102
2103The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2104binman uses that to look up the BSS address.
2105
2106
2107
Simon Glassa7c97782022-08-07 16:33:25 -06002108.. _etype_u_boot_spl_dtb:
2109
Simon Glass7a61c6b2018-07-17 13:25:37 -06002110Entry: u-boot-spl-dtb: U-Boot SPL device tree
2111---------------------------------------------
2112
2113Properties / Entry arguments:
2114 - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
2115
2116This is the SPL device tree, containing configuration information for
2117SPL. SPL needs this to know what devices are present and which drivers
2118to activate.
2119
2120
Simon Glassa7c97782022-08-07 16:33:25 -06002121
2122.. _etype_u_boot_spl_elf:
Simon Glass7a61c6b2018-07-17 13:25:37 -06002123
Simon Glassb1714232018-09-14 04:57:35 -06002124Entry: u-boot-spl-elf: U-Boot SPL ELF image
2125-------------------------------------------
2126
2127Properties / Entry arguments:
Simon Glass5dcc21d2019-07-08 13:18:45 -06002128 - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
Simon Glassb1714232018-09-14 04:57:35 -06002129
2130This is the U-Boot SPL ELF image. It does not include a device tree but can
2131be relocated to any address for execution.
2132
Simon Glass718b5292021-03-18 20:25:07 +13002133
2134
Simon Glassa7c97782022-08-07 16:33:25 -06002135.. _etype_u_boot_spl_expanded:
2136
Simon Glass718b5292021-03-18 20:25:07 +13002137Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
2138--------------------------------------------------------------------------------------
2139
2140Properties / Entry arguments:
2141 - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2142 select)
2143
2144This is a section containing the U-Boot binary, BSS padding if needed and a
2145devicetree. Using this entry type automatically creates this section, with
2146the following entries in it:
2147
2148 u-boot-spl-nodtb
2149 u-boot-spl-bss-pad
2150 u-boot-dtb
2151
2152Having the devicetree separate allows binman to update it in the final
2153image, so that the entries positions are provided to the running U-Boot.
2154
2155This entry is selected based on the value of the 'spl-dtb' entryarg. If
2156this is non-empty (and not 'n' or '0') then this expanded entry is selected.
Simon Glassb1714232018-09-14 04:57:35 -06002157
2158
Simon Glassa7c97782022-08-07 16:33:25 -06002159
2160.. _etype_u_boot_spl_nodtb:
Simon Glass718b5292021-03-18 20:25:07 +13002161
Simon Glass7a61c6b2018-07-17 13:25:37 -06002162Entry: u-boot-spl-nodtb: SPL binary without device tree appended
2163----------------------------------------------------------------
2164
2165Properties / Entry arguments:
Simon Glass537e0062021-03-18 20:24:54 +13002166 - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002167
2168This is the U-Boot SPL binary, It does not include a device tree blob at
2169the end of it so may not be able to work without it, assuming SPL needs
Simon Glass537e0062021-03-18 20:24:54 +13002170a device tree to operate on your platform. You can add a u-boot-spl-dtb
Simon Glass718b5292021-03-18 20:25:07 +13002171entry after this one, or use a u-boot-spl entry instead' which normally
2172expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
2173u-boot-spl-dtb
Simon Glass7a61c6b2018-07-17 13:25:37 -06002174
Simon Glass18ed9962023-01-07 14:07:11 -07002175SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass31e04cb2021-03-18 20:24:56 +13002176
2177in the binman README for more information.
2178
2179The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2180binman uses that to look up symbols to write into the SPL binary.
2181
Simon Glass7a61c6b2018-07-17 13:25:37 -06002182
2183
Lukas Funkeb4937da2023-07-18 13:53:15 +02002184.. _etype_u_boot_spl_pubkey_dtb:
2185
2186Entry: u-boot-spl-pubkey-dtb: U-Boot SPL device tree including public key
2187-------------------------------------------------------------------------
2188
2189Properties / Entry arguments:
2190 - key-name-hint: Public key name without extension (.crt).
2191 Default is determined by underlying
2192 bintool (fdt_add_pubkey), usually 'key'.
2193 - algo: (Optional) Algorithm used for signing. Default is determined by
2194 underlying bintool (fdt_add_pubkey), usually 'sha1,rsa2048'
2195 - required: (Optional) If present this indicates that the key must be
2196 verified for the image / configuration to be
2197 considered valid
2198
2199The following example shows an image containing an SPL which
2200is packed together with the dtb. Binman will add a signature
2201node to the dtb.
2202
2203Example node::
2204
2205 image {
2206 ...
2207 spl {
2208 filename = "spl.bin"
2209
2210 u-boot-spl-nodtb {
2211 };
2212 u-boot-spl-pubkey-dtb {
2213 algo = "sha384,rsa4096";
2214 required = "conf";
2215 key-name-hint = "dev";
2216 };
2217 };
2218 ...
2219 }
2220
2221
2222
Simon Glassa7c97782022-08-07 16:33:25 -06002223.. _etype_u_boot_spl_with_ucode_ptr:
2224
Simon Glass7a61c6b2018-07-17 13:25:37 -06002225Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
2226----------------------------------------------------------------------------
2227
Simon Glass3fb4f422018-09-14 04:57:32 -06002228This is used when SPL must set up the microcode for U-Boot.
2229
Simon Glass7a61c6b2018-07-17 13:25:37 -06002230See Entry_u_boot_ucode for full details of the entries involved in this
2231process.
2232
2233
2234
Simon Glassa7c97782022-08-07 16:33:25 -06002235.. _etype_u_boot_tpl:
2236
Simon Glass8425a1f2018-07-17 13:25:48 -06002237Entry: u-boot-tpl: U-Boot TPL binary
2238------------------------------------
2239
2240Properties / Entry arguments:
2241 - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
2242
2243This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
2244binary which loads before SPL, typically into on-chip SRAM. It is
2245responsible for locating, loading and jumping to SPL, the next-stage
2246loader. Note that SPL is not relocatable so must be loaded to the correct
2247address in SRAM, or written to run from the correct address if direct
2248flash execution is possible (e.g. on x86 devices).
2249
Simon Glass18ed9962023-01-07 14:07:11 -07002250SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glass8425a1f2018-07-17 13:25:48 -06002251
2252in the binman README for more information.
2253
2254The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2255binman uses that to look up symbols to write into the TPL binary.
2256
Simon Glass718b5292021-03-18 20:25:07 +13002257Note that this entry is automatically replaced with u-boot-tpl-expanded
Simon Glass7098b7f2021-03-21 18:24:30 +13002258unless --no-expanded is used or the node has a 'no-expanded' property.
Simon Glass718b5292021-03-18 20:25:07 +13002259
Simon Glass8425a1f2018-07-17 13:25:48 -06002260
2261
Simon Glassa7c97782022-08-07 16:33:25 -06002262.. _etype_u_boot_tpl_bss_pad:
2263
Simon Glass63f41d42021-03-18 20:24:58 +13002264Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
2265---------------------------------------------------------------------
2266
2267Properties / Entry arguments:
2268 None
2269
2270This holds the padding added after the TPL binary to cover the BSS (Block
2271Started by Symbol) region. This region holds the various variables used by
2272TPL. It is set to 0 by TPL when it starts up. If you want to append data to
2273the TPL image (such as a device tree file), you must pad out the BSS region
2274to avoid the data overlapping with U-Boot variables. This entry is useful in
2275that case. It automatically pads out the entry size to cover both the code,
2276data and BSS.
2277
2278The contents of this entry will a certain number of zero bytes, determined
2279by __bss_size
2280
2281The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2282binman uses that to look up the BSS address.
2283
2284
2285
Simon Glassa7c97782022-08-07 16:33:25 -06002286.. _etype_u_boot_tpl_dtb:
2287
Simon Glass8425a1f2018-07-17 13:25:48 -06002288Entry: u-boot-tpl-dtb: U-Boot TPL device tree
2289---------------------------------------------
2290
2291Properties / Entry arguments:
2292 - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
2293
2294This is the TPL device tree, containing configuration information for
2295TPL. TPL needs this to know what devices are present and which drivers
2296to activate.
2297
2298
2299
Simon Glassa7c97782022-08-07 16:33:25 -06002300.. _etype_u_boot_tpl_dtb_with_ucode:
2301
Simon Glass3fb4f422018-09-14 04:57:32 -06002302Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
2303----------------------------------------------------------------------------
2304
2305This is used when TPL must set up the microcode for U-Boot.
2306
2307See Entry_u_boot_ucode for full details of the entries involved in this
2308process.
2309
2310
2311
Simon Glassa7c97782022-08-07 16:33:25 -06002312.. _etype_u_boot_tpl_elf:
2313
Simon Glassa899f712019-07-08 13:18:46 -06002314Entry: u-boot-tpl-elf: U-Boot TPL ELF image
2315-------------------------------------------
2316
2317Properties / Entry arguments:
2318 - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
2319
2320This is the U-Boot TPL ELF image. It does not include a device tree but can
2321be relocated to any address for execution.
2322
2323
Simon Glassa7c97782022-08-07 16:33:25 -06002324
2325.. _etype_u_boot_tpl_expanded:
Simon Glassa899f712019-07-08 13:18:46 -06002326
Simon Glass718b5292021-03-18 20:25:07 +13002327Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
2328--------------------------------------------------------------------------------------
2329
2330Properties / Entry arguments:
2331 - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2332 select)
2333
2334This is a section containing the U-Boot binary, BSS padding if needed and a
2335devicetree. Using this entry type automatically creates this section, with
2336the following entries in it:
2337
2338 u-boot-tpl-nodtb
2339 u-boot-tpl-bss-pad
2340 u-boot-dtb
2341
2342Having the devicetree separate allows binman to update it in the final
2343image, so that the entries positions are provided to the running U-Boot.
2344
2345This entry is selected based on the value of the 'tpl-dtb' entryarg. If
2346this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2347
2348
2349
Simon Glassa7c97782022-08-07 16:33:25 -06002350.. _etype_u_boot_tpl_nodtb:
2351
Simon Glassc98de972021-03-18 20:24:57 +13002352Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
2353----------------------------------------------------------------
2354
2355Properties / Entry arguments:
2356 - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin')
2357
2358This is the U-Boot TPL binary, It does not include a device tree blob at
2359the end of it so may not be able to work without it, assuming TPL needs
2360a device tree to operate on your platform. You can add a u-boot-tpl-dtb
Simon Glass718b5292021-03-18 20:25:07 +13002361entry after this one, or use a u-boot-tpl entry instead, which normally
2362expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
2363u-boot-tpl-dtb
Simon Glassc98de972021-03-18 20:24:57 +13002364
Simon Glass18ed9962023-01-07 14:07:11 -07002365TPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassc98de972021-03-18 20:24:57 +13002366
2367in the binman README for more information.
2368
2369The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2370binman uses that to look up symbols to write into the TPL binary.
2371
2372
Simon Glassa7c97782022-08-07 16:33:25 -06002373
2374.. _etype_u_boot_tpl_with_ucode_ptr:
Simon Glassc98de972021-03-18 20:24:57 +13002375
Simon Glass3fb4f422018-09-14 04:57:32 -06002376Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
2377----------------------------------------------------------------------------
2378
2379See Entry_u_boot_ucode for full details of the entries involved in this
2380process.
2381
2382
2383
Simon Glassa7c97782022-08-07 16:33:25 -06002384.. _etype_u_boot_ucode:
2385
Simon Glass7a61c6b2018-07-17 13:25:37 -06002386Entry: u-boot-ucode: U-Boot microcode block
2387-------------------------------------------
2388
2389Properties / Entry arguments:
2390 None
2391
2392The contents of this entry are filled in automatically by other entries
2393which must also be in the image.
2394
2395U-Boot on x86 needs a single block of microcode. This is collected from
2396the various microcode update nodes in the device tree. It is also unable
2397to read the microcode from the device tree on platforms that use FSP
2398(Firmware Support Package) binaries, because the API requires that the
2399microcode is supplied before there is any SRAM available to use (i.e.
2400the FSP sets up the SRAM / cache-as-RAM but does so in the call that
2401requires the microcode!). To keep things simple, all x86 platforms handle
2402microcode the same way in U-Boot (even non-FSP platforms). This is that
2403a table is placed at _dt_ucode_base_size containing the base address and
2404size of the microcode. This is either passed to the FSP (for FSP
2405platforms), or used to set up the microcode (for non-FSP platforms).
2406This all happens in the build system since it is the only way to get
2407the microcode into a single blob and accessible without SRAM.
2408
2409There are two cases to handle. If there is only one microcode blob in
2410the device tree, then the ucode pointer it set to point to that. This
2411entry (u-boot-ucode) is empty. If there is more than one update, then
2412this entry holds the concatenation of all updates, and the device tree
2413entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
2414last step ensures that that the microcode appears in one contiguous
2415block in the image and is not unnecessarily duplicated in the device
2416tree. It is referred to as 'collation' here.
2417
2418Entry types that have a part to play in handling microcode:
2419
2420 Entry_u_boot_with_ucode_ptr:
2421 Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
2422 It updates it with the address and size of the microcode so that
2423 U-Boot can find it early on start-up.
2424 Entry_u_boot_dtb_with_ucode:
2425 Contains u-boot.dtb. It stores the microcode in a
2426 'self.ucode_data' property, which is then read by this class to
2427 obtain the microcode if needed. If collation is performed, it
2428 removes the microcode from the device tree.
2429 Entry_u_boot_ucode:
2430 This class. If collation is enabled it reads the microcode from
2431 the Entry_u_boot_dtb_with_ucode entry, and uses it as the
2432 contents of this entry.
2433
2434
2435
Simon Glassda6a9082023-01-07 14:07:10 -07002436.. _etype_u_boot_vpl:
2437
2438Entry: u-boot-vpl: U-Boot VPL binary
2439------------------------------------
2440
2441Properties / Entry arguments:
2442 - filename: Filename of u-boot-vpl.bin (default 'vpl/u-boot-vpl.bin')
2443
2444This is the U-Boot VPL (Verifying Program Loader) binary. This is a small
2445binary which loads before SPL, typically into on-chip SRAM. It is
2446responsible for locating, loading and jumping to SPL, the next-stage
2447loader. Note that VPL is not relocatable so must be loaded to the correct
2448address in SRAM, or written to run from the correct address if direct
2449flash execution is possible (e.g. on x86 devices).
2450
Simon Glass18ed9962023-01-07 14:07:11 -07002451SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassda6a9082023-01-07 14:07:10 -07002452
2453in the binman README for more information.
2454
2455The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2456binman uses that to look up symbols to write into the VPL binary.
2457
2458
2459
2460.. _etype_u_boot_vpl_bss_pad:
2461
2462Entry: u-boot-vpl-bss-pad: U-Boot VPL binary padded with a BSS region
2463---------------------------------------------------------------------
2464
2465Properties / Entry arguments:
2466 None
2467
2468This holds the padding added after the VPL binary to cover the BSS (Block
2469Started by Symbol) region. This region holds the various variables used by
2470VPL. It is set to 0 by VPL when it starts up. If you want to append data to
2471the VPL image (such as a device tree file), you must pad out the BSS region
2472to avoid the data overlapping with U-Boot variables. This entry is useful in
2473that case. It automatically pads out the entry size to cover both the code,
2474data and BSS.
2475
2476The contents of this entry will a certain number of zero bytes, determined
2477by __bss_size
2478
2479The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2480binman uses that to look up the BSS address.
2481
2482
2483
2484.. _etype_u_boot_vpl_dtb:
2485
2486Entry: u-boot-vpl-dtb: U-Boot VPL device tree
2487---------------------------------------------
2488
2489Properties / Entry arguments:
2490 - filename: Filename of u-boot.dtb (default 'vpl/u-boot-vpl.dtb')
2491
2492This is the VPL device tree, containing configuration information for
2493VPL. VPL needs this to know what devices are present and which drivers
2494to activate.
2495
2496
2497
2498.. _etype_u_boot_vpl_elf:
2499
2500Entry: u-boot-vpl-elf: U-Boot VPL ELF image
2501-------------------------------------------
2502
2503Properties / Entry arguments:
2504 - filename: Filename of VPL u-boot (default 'vpl/u-boot-vpl')
2505
2506This is the U-Boot VPL ELF image. It does not include a device tree but can
2507be relocated to any address for execution.
2508
2509
2510
2511.. _etype_u_boot_vpl_expanded:
2512
2513Entry: u-boot-vpl-expanded: U-Boot VPL flat binary broken out into its component parts
2514--------------------------------------------------------------------------------------
2515
2516Properties / Entry arguments:
2517 - vpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2518 select)
2519
2520This is a section containing the U-Boot binary, BSS padding if needed and a
2521devicetree. Using this entry type automatically creates this section, with
2522the following entries in it:
2523
2524 u-boot-vpl-nodtb
2525 u-boot-vpl-bss-pad
2526 u-boot-dtb
2527
2528Having the devicetree separate allows binman to update it in the final
2529image, so that the entries positions are provided to the running U-Boot.
2530
2531This entry is selected based on the value of the 'vpl-dtb' entryarg. If
2532this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2533
2534
2535
2536.. _etype_u_boot_vpl_nodtb:
2537
2538Entry: u-boot-vpl-nodtb: VPL binary without device tree appended
2539----------------------------------------------------------------
2540
2541Properties / Entry arguments:
2542 - filename: Filename to include (default 'vpl/u-boot-vpl-nodtb.bin')
2543
2544This is the U-Boot VPL binary, It does not include a device tree blob at
2545the end of it so may not be able to work without it, assuming VPL needs
2546a device tree to operate on your platform. You can add a u_boot_vpl_dtb
2547entry after this one, or use a u_boot_vpl entry instead, which normally
2548expands to a section containing u-boot-vpl-dtb, u-boot-vpl-bss-pad and
2549u-boot-vpl-dtb
2550
Simon Glass18ed9962023-01-07 14:07:11 -07002551VPL can access binman symbols at runtime. See :ref:`binman_fdt`.
Simon Glassda6a9082023-01-07 14:07:10 -07002552
2553The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2554binman uses that to look up symbols to write into the VPL binary.
2555
2556
2557
Simon Glassa7c97782022-08-07 16:33:25 -06002558.. _etype_u_boot_with_ucode_ptr:
2559
Simon Glass7a61c6b2018-07-17 13:25:37 -06002560Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
2561--------------------------------------------------------------------
2562
2563Properties / Entry arguments:
Masahiro Yamadaa7a0ca42019-12-14 13:47:26 +09002564 - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
Simon Glassee21d3a2018-09-14 04:57:07 -06002565 - optional-ucode: boolean property to make microcode optional. If the
2566 u-boot.bin image does not include microcode, no error will
2567 be generated.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002568
2569See Entry_u_boot_ucode for full details of the three entries involved in
2570this process. This entry updates U-Boot with the offset and size of the
2571microcode, to allow early x86 boot code to find it without doing anything
Simon Glass537e0062021-03-18 20:24:54 +13002572complicated. Otherwise it is the same as the u-boot entry.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002573
2574
2575
Simon Glassa7c97782022-08-07 16:33:25 -06002576.. _etype_vblock:
2577
Simon Glass5c350162018-07-17 13:25:47 -06002578Entry: vblock: An entry which contains a Chromium OS verified boot block
2579------------------------------------------------------------------------
2580
2581Properties / Entry arguments:
Simon Glass17b84eb2019-05-17 22:00:53 -06002582 - content: List of phandles to entries to sign
Simon Glass5c350162018-07-17 13:25:47 -06002583 - keydir: Directory containing the public keys to use
2584 - keyblock: Name of the key file to use (inside keydir)
2585 - signprivate: Name of provide key file to use (inside keydir)
2586 - version: Version number of the vblock (typically 1)
2587 - kernelkey: Name of the kernel key to use (inside keydir)
2588 - preamble-flags: Value of the vboot preamble flags (typically 0)
2589
Simon Glass639505b2018-09-14 04:57:11 -06002590Output files:
2591 - input.<unique_name> - input file passed to futility
2592 - vblock.<unique_name> - output file generated by futility (which is
2593 used as the entry contents)
2594
Jagdish Gediya311d4842018-09-03 21:35:08 +05302595Chromium OS signs the read-write firmware and kernel, writing the signature
Simon Glass5c350162018-07-17 13:25:47 -06002596in this block. This allows U-Boot to verify that the next firmware stage
2597and kernel are genuine.
2598
2599
2600
Simon Glassc3fe97f2023-03-02 17:02:45 -07002601.. _etype_x509_cert:
2602
2603Entry: x509-cert: An entry which contains an X509 certificate
2604-------------------------------------------------------------
2605
2606Properties / Entry arguments:
2607 - content: List of phandles to entries to sign
2608
2609Output files:
2610 - input.<unique_name> - input file passed to openssl
2611 - cert.<unique_name> - output file generated by openssl (which is
2612 used as the entry contents)
2613
2614openssl signs the provided data, writing the signature in this entry. This
2615allows verification that the data is genuine
2616
2617
2618
Simon Glassa7c97782022-08-07 16:33:25 -06002619.. _etype_x86_reset16:
2620
Simon Glass0b074d62019-08-24 07:22:48 -06002621Entry: x86-reset16: x86 16-bit reset code for U-Boot
2622----------------------------------------------------
2623
2624Properties / Entry arguments:
2625 - filename: Filename of u-boot-x86-reset16.bin (default
2626 'u-boot-x86-reset16.bin')
2627
2628x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2629must be placed at a particular address. This entry holds that code. It is
2630typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2631for jumping to the x86-start16 code, which continues execution.
2632
2633For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
2634
2635
2636
Simon Glassa7c97782022-08-07 16:33:25 -06002637.. _etype_x86_reset16_spl:
2638
Simon Glass0b074d62019-08-24 07:22:48 -06002639Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
2640--------------------------------------------------------
2641
2642Properties / Entry arguments:
2643 - filename: Filename of u-boot-x86-reset16.bin (default
2644 'u-boot-x86-reset16.bin')
2645
2646x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2647must be placed at a particular address. This entry holds that code. It is
2648typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2649for jumping to the x86-start16 code, which continues execution.
2650
2651For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
2652
2653
2654
Simon Glassa7c97782022-08-07 16:33:25 -06002655.. _etype_x86_reset16_tpl:
2656
Simon Glass0b074d62019-08-24 07:22:48 -06002657Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
2658--------------------------------------------------------
2659
2660Properties / Entry arguments:
2661 - filename: Filename of u-boot-x86-reset16.bin (default
2662 'u-boot-x86-reset16.bin')
2663
2664x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2665must be placed at a particular address. This entry holds that code. It is
2666typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2667for jumping to the x86-start16 code, which continues execution.
2668
2669For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
2670
2671
Simon Glassa7c97782022-08-07 16:33:25 -06002672
2673.. _etype_x86_start16:
Simon Glass0b074d62019-08-24 07:22:48 -06002674
Simon Glass7a61c6b2018-07-17 13:25:37 -06002675Entry: x86-start16: x86 16-bit start-up code for U-Boot
2676-------------------------------------------------------
2677
2678Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002679 - filename: Filename of u-boot-x86-start16.bin (default
2680 'u-boot-x86-start16.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002681
2682x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
Simon Glassabab18c2019-08-24 07:22:49 -06002683must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2684entry holds that code. It is typically placed at offset
2685CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2686and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2687U-Boot).
Simon Glass7a61c6b2018-07-17 13:25:37 -06002688
2689For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
2690
2691
2692
Simon Glassa7c97782022-08-07 16:33:25 -06002693.. _etype_x86_start16_spl:
2694
Simon Glass7a61c6b2018-07-17 13:25:37 -06002695Entry: x86-start16-spl: x86 16-bit start-up code for SPL
2696--------------------------------------------------------
2697
2698Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002699 - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
2700 'spl/u-boot-x86-start16-spl.bin')
Simon Glass7a61c6b2018-07-17 13:25:37 -06002701
Simon Glassabab18c2019-08-24 07:22:49 -06002702x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2703must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2704entry holds that code. It is typically placed at offset
2705CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2706and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2707U-Boot).
Simon Glass7a61c6b2018-07-17 13:25:37 -06002708
Simon Glassabab18c2019-08-24 07:22:49 -06002709For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
Simon Glass7a61c6b2018-07-17 13:25:37 -06002710
2711
2712
Simon Glassa7c97782022-08-07 16:33:25 -06002713.. _etype_x86_start16_tpl:
2714
Simon Glassed40e962018-09-14 04:57:10 -06002715Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
2716--------------------------------------------------------
2717
2718Properties / Entry arguments:
Simon Glassabab18c2019-08-24 07:22:49 -06002719 - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
2720 'tpl/u-boot-x86-start16-tpl.bin')
Simon Glassed40e962018-09-14 04:57:10 -06002721
Simon Glassabab18c2019-08-24 07:22:49 -06002722x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2723must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2724entry holds that code. It is typically placed at offset
2725CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2726and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2727U-Boot).
Simon Glassed40e962018-09-14 04:57:10 -06002728
Simon Glassabab18c2019-08-24 07:22:49 -06002729If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
Simon Glassed40e962018-09-14 04:57:10 -06002730may be used instead.
2731
2732
2733
Lukas Funkefebfc6d2023-08-03 17:22:15 +02002734.. _etype_xilinx_bootgen:
2735
2736Entry: xilinx-bootgen: Signed SPL boot image for Xilinx ZynqMP devices
2737----------------------------------------------------------------------
2738
2739Properties / Entry arguments:
2740 - auth-params: (Optional) Authentication parameters passed to bootgen
2741 - fsbl-config: (Optional) FSBL parameters passed to bootgen
2742 - keysrc-enc: (Optional) Key source when using decryption engine
2743 - pmufw-filename: Filename of PMU firmware. Default: pmu-firmware.elf
2744 - psk-key-name-hint: Name of primary secret key to use for signing the
2745 secondardy public key. Format: .pem file
2746 - ssk-key-name-hint: Name of secondardy secret key to use for signing
2747 the boot image. Format: .pem file
2748
2749The etype is used to create a boot image for Xilinx ZynqMP
2750devices.
2751
2752Information for signed images:
2753
2754In AMD/Xilinx SoCs, two pairs of public and secret keys are used
2755- primary and secondary. The function of the primary public/secret key pair
2756is to authenticate the secondary public/secret key pair.
2757The function of the secondary key is to sign/verify the boot image. [1]
2758
2759AMD/Xilinx uses the following terms for private/public keys [1]:
2760
2761 PSK = Primary Secret Key (Used to sign Secondary Public Key)
2762 PPK = Primary Public Key (Used to verify Secondary Public Key)
2763 SSK = Secondary Secret Key (Used to sign the boot image/partitions)
2764 SPK = Used to verify the actual boot image
2765
2766The following example builds a signed boot image. The fuses of
2767the primary public key (ppk) should be fused together with the RSA_EN flag.
2768
2769Example node::
2770
2771 spl {
2772 filename = "boot.signed.bin";
2773
2774 xilinx-bootgen {
2775 psk-key-name-hint = "psk0";
2776 ssk-key-name-hint = "ssk0";
2777 auth-params = "ppk_select=0", "spk_id=0x00000000";
2778
2779 u-boot-spl-nodtb {
2780 };
2781 u-boot-spl-pubkey-dtb {
2782 algo = "sha384,rsa4096";
2783 required = "conf";
2784 key-name-hint = "dev";
2785 };
2786 };
2787 };
2788
2789For testing purposes, e.g. if no RSA_EN should be fused, one could add
2790the "bh_auth_enable" flag in the fsbl-config field. This will skip the
2791verification of the ppk fuses and boot the image, even if ppk hash is
2792invalid.
2793
2794Example node::
2795
2796 xilinx-bootgen {
2797 psk-key-name-hint = "psk0";
2798 psk-key-name-hint = "ssk0";
2799 ...
2800 fsbl-config = "bh_auth_enable";
2801 ...
2802 };
2803
2804[1] https://docs.xilinx.com/r/en-US/ug1283-bootgen-user-guide/Using-Authentication
2805
2806
2807
2808