tools/binman/entries.rst

   1 Binman Entry Documentation
   2 ===========================
   3
   4 This file describes the entry types supported by binman. These entry types can
   5 be placed in an image one by one to build up a final firmware image. It is
   6 fairly easy to create new entry types. Just add a new file to the 'etype'
   7 directory. You can use the existing entries as examples.
   8
   9 Note that some entries are subclasses of others, using and extending their
  10 features to produce new behaviours.
  11
  12
  13
  14 .. _etype_atf_bl31:
  15
  16 Entry: atf-bl31: ARM Trusted Firmware (ATF) BL31 blob
  17 -----------------------------------------------------
  18
  19 Properties / Entry arguments:
  20     - atf-bl31-path: Filename of file to read into entry. This is typically
  21         called bl31.bin or bl31.elf
  22
  23 This entry holds the run-time firmware, typically started by U-Boot SPL.
  24 See the U-Boot README for your architecture or board for how to use it. See
  25 https://github.com/ARM-software/arm-trusted-firmware for more information
  26 about ATF.
  27
  28
  29
  30 .. _etype_atf_fip:
  31
  32 Entry: atf-fip: ARM Trusted Firmware's Firmware Image Package (FIP)
  33 -------------------------------------------------------------------
  34
  35 A FIP_ provides a way to group binaries in a firmware image, used by ARM's
  36 Trusted Firmware A (TF-A) code. It is a simple format consisting of a
  37 table of contents with information about the type, offset and size of the
  38 binaries in the FIP. It is quite similar to FMAP, with the major difference
  39 that it uses UUIDs to indicate the type of each entry.
  40
  41 Note: It is recommended to always add an fdtmap to every image, as well as
  42 any FIPs so that binman and other tools can access the entire image
  43 correctly.
  44
  45 The UUIDs correspond to useful names in `fiptool`, provided by ATF to
  46 operate on FIPs. Binman uses these names to make it easier to understand
  47 what is going on, although it is possible to provide a UUID if needed.
  48
  49 The 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
  65 This describes a FIP with three entries: soc-fw, scp-fwu-cfg and nt-fw.
  66 You can use normal (non-external) binaries like U-Boot simply by adding a
  67 FIP type, with the `fip-type` property, as above.
  68
  69 Since FIP exists to bring blobs together, Binman assumes that all FIP
  70 entries are external binaries. If a binary may not exist, you can use the
  71 `--allow-missing` flag to Binman, in which case the image is still created,
  72 even though it will not actually work.
  73
  74 The size of the FIP depends on the size of the binaries. There is currently
  75 no way to specify a fixed size. If the `atf-fip` node has a `size` entry,
  76 this affects the space taken up by the `atf-fip` entry, but the FIP itself
  77 does not expand to use that space.
  78
  79 Some other FIP features are available with Binman. The header and the
  80 entries have 64-bit flag works. The flag flags do not seem to be defined
  81 anywhere, but you can use `fip-hdr-flags` and fip-flags` to set the values
  82 of the header and entries respectively.
  83
  84 FIP entries can be aligned to a particular power-of-two boundary. Use
  85 fip-align for this.
  86
  87 Binman only understands the entry types that are included in its
  88 implementation. It is possible to specify a 16-byte UUID instead, using the
  89 fip-uuid property. In this case Binman doesn't know what its type is, so
  90 just uses the UUID. See the `u-boot` node in this example::
  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
 114 Binman allows reading and updating FIP entries after the image is created,
 115 provided that an FDPMAP is present too. Updates which change the size of a
 116 FIP entry will cause it to be expanded or contracted as needed.
 117
 118 Properties for top-level atf-fip node
 119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 120
 121 fip-hdr-flags (64 bits)
 122     Sets the flags for the FIP header.
 123
 124 Properties for subnodes
 125 ~~~~~~~~~~~~~~~~~~~~~~~
 126
 127 fip-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
 132 fip-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
 137 fip-flags (64 bits)
 138     Set the flags for a FIP entry. Use in one of the subnodes of the
 139     7atf-fip entry.
 140
 141 fip-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
 145 Adding new FIP-entry types
 146 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 147
 148 When new FIP entries are defined by TF-A they appear in the
 149 `TF-A source tree`_. You can use `fip_util.py` to update Binman to support
 150 new types, then `send a patch`_ to the U-Boot mailing list. There are two
 151 source files that the tool examples:
 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
 156 To 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
 162 If it shows there is an update, it writes a new version of `fip_util.py`
 163 to `fip_util.py.out`. You can change the output file using the `-i` flag.
 164 If you have a problem, use `-D` to enable traceback debugging.
 165
 166 FIP commentary
 167 ~~~~~~~~~~~~~~
 168
 169 As a side effect of use of UUIDs, FIP does not support multiple
 170 entries of the same type, such as might be used to store fonts or graphics
 171 icons, for example. For verified boot it could be used for each part of the
 172 image (e.g. separate FIPs for A and B) but cannot describe the whole
 173 firmware image. As with FMAP there is no hierarchy defined, although FMAP
 174 works around this by having 'section' areas which encompass others. A
 175 similar workaround would be possible with FIP but is not currently defined.
 176
 177 It is recommended to always add an fdtmap to every image, as well as any
 178 FIPs so that binman and other tools can access the entire image correctly.
 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
 186 .. _etype_blob:
 187
 188 Entry: blob: Arbitrary binary blob
 189 ----------------------------------
 190
 191 Note: This should not be used by itself. It is normally used as a parent
 192 class by other entry types.
 193
 194 Properties / Entry arguments:
 195     - filename: Filename of file to read into entry
 196     - compress: Compression algorithm to use:
 197         none: No compression
 198         lz4: Use lz4 compression (via 'lz4' command-line utility)
 199
 200 This entry reads data from a file and places it in the entry. The
 201 default filename is often specified specified by the subclass. See for
 202 example the 'u-boot' entry which provides the filename 'u-boot.bin'.
 203
 204 If compression is enabled, an extra 'uncomp-size' property is written to
 205 the node (if enabled with -u) which provides the uncompressed size of the
 206 data.
 207
 208
 209
 210 .. _etype_blob_dtb:
 211
 212 Entry: blob-dtb: A blob that holds a device tree
 213 ------------------------------------------------
 214
 215 This is a blob containing a device tree. The contents of the blob are
 216 obtained from the list of available device-tree files, managed by the
 217 'state' module.
 218
 219 Additional attributes:
 220     prepend: Header used (e.g. 'length')
 221
 222
 223
 224 .. _etype_blob_ext:
 225
 226 Entry: blob-ext: Externally built binary blob
 227 ---------------------------------------------
 228
 229 Note: This should not be used by itself. It is normally used as a parent
 230 class by other entry types.
 231
 232 If the file providing this blob is missing, binman can optionally ignore it
 233 and produce a broken image with a warning.
 234
 235 See 'blob' for Properties / Entry arguments.
 236
 237
 238
 239 .. _etype_blob_ext_list:
 240
 241 Entry: blob-ext-list: List of externally built binary blobs
 242 -----------------------------------------------------------
 243
 244 This is like blob-ext except that a number of blobs can be provided,
 245 typically with some sort of relationship, e.g. all are DDC parameters.
 246
 247 If any of the external files needed by this llist is missing, binman can
 248 optionally ignore it and produce a broken image with a warning.
 249
 250 Args:
 251     filenames: List of filenames to read and include
 252
 253
 254
 255 .. _etype_blob_named_by_arg:
 256
 257 Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass
 258 -----------------------------------------------------------------------------------------
 259
 260 Properties / Entry arguments:
 261     - <xxx>-path: Filename containing the contents of this entry (optional,
 262         defaults to None)
 263
 264 where <xxx> is the blob_fname argument to the constructor.
 265
 266 This entry cannot be used directly. Instead, it is used as a parent class
 267 for another entry, which defined blob_fname. This parameter is used to
 268 set the entry-arg or property containing the filename. The entry-arg or
 269 property is in turn used to set the actual filename.
 270
 271 See cros_ec_rw for an example of this.
 272
 273
 274
 275 .. _etype_blob_phase:
 276
 277 Entry: blob-phase: Section that holds a phase binary
 278 ----------------------------------------------------
 279
 280 This is a base class that should not normally be used directly. It is used
 281 when converting a 'u-boot' entry automatically into a 'u-boot-expanded'
 282 entry; similarly for SPL.
 283
 284
 285
 286 .. _etype_cbfs:
 287
 288 Entry: cbfs: Coreboot Filesystem (CBFS)
 289 ---------------------------------------
 290
 291 A CBFS provides a way to group files into a group. It has a simple directory
 292 structure and allows the position of individual files to be set, since it is
 293 designed to support execute-in-place in an x86 SPI-flash device. Where XIP
 294 is not used, it supports compression and storing ELF files.
 295
 296 CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
 297
 298 The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::
 299
 300     cbfs {
 301         size = <0x100000>;
 302         u-boot {
 303             cbfs-type = "raw";
 304         };
 305         u-boot-dtb {
 306             cbfs-type = "raw";
 307         };
 308     };
 309
 310 This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb.
 311 Note that the size is required since binman does not support calculating it.
 312 The contents of each entry is just what binman would normally provide if it
 313 were not a CBFS node. A blob type can be used to import arbitrary files as
 314 with the second subnode below::
 315
 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";
 328             cbfs-offset = <0x100000>;
 329         };
 330     };
 331
 332 This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and
 333 u-boot.dtb (named "dtb") and compressed with the lz4 algorithm.
 334
 335
 336 Properties supported in the top-level CBFS node:
 337
 338 cbfs-arch:
 339     Defaults to "x86", but you can specify the architecture if needed.
 340
 341
 342 Properties supported in the CBFS entry subnodes:
 343
 344 cbfs-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
 349 cbfs-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'
 360         entry::
 361
 362             cbfs {
 363                 size = <0x100000>;
 364                 u-boot-elf {
 365                     cbfs-name = "BOOT";
 366                     cbfs-type = "stage";
 367                 };
 368             };
 369
 370         You can use your own ELF file with something like::
 371
 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
 387 cbfs-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.
 396
 397 The current implementation supports only a subset of CBFS features. It does
 398 not support other file types (e.g. payload), adding multiple files (like the
 399 'files' entry with a pattern supported by binman), putting files at a
 400 particular offset in the CBFS and a few other things.
 401
 402 Of course binman can create images containing multiple CBFSs, simply by
 403 defining these in the binman config::
 404
 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
 435 This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB,
 436 both of size 1MB.
 437
 438
 439
 440 .. _etype_collection:
 441
 442 Entry: collection: An entry which contains a collection of other entries
 443 ------------------------------------------------------------------------
 444
 445 Properties / Entry arguments:
 446     - content: List of phandles to entries to include
 447
 448 This allows reusing the contents of other entries. The contents of the
 449 listed entries are combined to form this entry. This serves as a useful
 450 base class for entry types which need to process data from elsewhere in
 451 the image, not necessarily child entries.
 452
 453 The entries can generally be anywhere in the same image, even if they are in
 454 a different section from this entry.
 455
 456
 457
 458 .. _etype_cros_ec_rw:
 459
 460 Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image
 461 --------------------------------------------------------------------------------
 462
 463 Properties / Entry arguments:
 464     - cros-ec-rw-path: Filename containing the EC image
 465
 466 This entry holds a Chromium OS EC (embedded controller) image, for use in
 467 updating the EC on startup via software sync.
 468
 469
 470
 471 .. _etype_encrypted:
 472
 473 Entry: encrypted: Externally built encrypted binary blob
 474 --------------------------------------------------------
 475
 476 This entry provides the functionality to include information about how to
 477 decrypt an encrypted binary. This information is added to the
 478 resulting device tree by adding a new cipher node in the entry's parent
 479 node (i.e. the binary).
 480
 481 The key that must be used to decrypt the binary is either directly embedded
 482 in the device tree or indirectly by specifying a key source. The key source
 483 can be used as an id of a key that is stored in an external device.
 484
 485 Using an embedded key
 486 ~~~~~~~~~~~~~~~~~~~~~
 487
 488 This is an example using an embedded key::
 489
 490     blob-ext {
 491         filename = "encrypted-blob.bin";
 492     };
 493
 494     encrypted {
 495         algo = "aes256-gcm";
 496         iv-filename = "encrypted-blob.bin.iv";
 497         key-filename = "encrypted-blob.bin.key";
 498     };
 499
 500 This entry generates the following device tree structure form the example
 501 above::
 502
 503     data = [...]
 504     cipher {
 505         algo = "aes256-gcm";
 506         key = <0x...>;
 507         iv = <0x...>;
 508     };
 509
 510 The data property is generated by the blob-ext etype, the cipher node and
 511 its content is generated by this etype.
 512
 513 Using an external key
 514 ~~~~~~~~~~~~~~~~~~~~~
 515
 516 Instead of embedding the key itself into the device tree, it is also
 517 possible to address an externally stored key by specifying a 'key-source'
 518 instead of the 'key'::
 519
 520     blob-ext {
 521         filename = "encrypted-blob.bin";
 522     };
 523
 524     encrypted {
 525         algo = "aes256-gcm";
 526         iv-filename = "encrypted-blob.bin.iv";
 527         key-source = "external-key-id";
 528     };
 529
 530 This entry generates the following device tree structure form the example
 531 above::
 532
 533     data = [...]
 534     cipher {
 535         algo = "aes256-gcm";
 536         key-source = "external-key-id";
 537         iv = <0x...>;
 538     };
 539
 540 Properties
 541 ~~~~~~~~~~
 542
 543 Properties / Entry arguments:
 544     - algo: The encryption algorithm. Currently no algorithm is supported
 545             out-of-the-box. Certain algorithms will be added in future
 546             patches.
 547     - iv-filename: The name of the file containing the initialization
 548                    vector (in short iv). See
 549                    https://en.wikipedia.org/wiki/Initialization_vector
 550     - key-filename: The name of the file containing the key. Either
 551                     key-filename or key-source must be provided.
 552     - key-source: The key that should be used. Either key-filename or
 553                   key-source must be provided.
 554
 555
 556
 557 .. _etype_fdtmap:
 558
 559 Entry: fdtmap: An entry which contains an FDT map
 560 -------------------------------------------------
 561
 562 Properties / Entry arguments:
 563     None
 564
 565 An FDT map is just a header followed by an FDT containing a list of all the
 566 entries in the image. The root node corresponds to the image node in the
 567 original FDT, and an image-name property indicates the image name in that
 568 original tree.
 569
 570 The header is the string _FDTMAP_ followed by 8 unused bytes.
 571
 572 When used, this entry will be populated with an FDT map which reflects the
 573 entries in the current image. Hierarchy is preserved, and all offsets and
 574 sizes are included.
 575
 576 Note that the -u option must be provided to ensure that binman updates the
 577 FDT with the position of each entry.
 578
 579 Example output for a simple image with U-Boot and an FDT map::
 580
 581     / {
 582         image-name = "binman";
 583         size = <0x00000112>;
 584         image-pos = <0x00000000>;
 585         offset = <0x00000000>;
 586         u-boot {
 587             size = <0x00000004>;
 588             image-pos = <0x00000000>;
 589             offset = <0x00000000>;
 590         };
 591         fdtmap {
 592             size = <0x0000010e>;
 593             image-pos = <0x00000004>;
 594             offset = <0x00000004>;
 595         };
 596     };
 597
 598 If allow-repack is used then 'orig-offset' and 'orig-size' properties are
 599 added as necessary. See the binman README.
 600
 601 When extracting files, an alternative 'fdt' format is available for fdtmaps.
 602 Use `binman extract -F fdt ...` to use this. It will export a devicetree,
 603 without the fdtmap header, so it can be viewed with `fdtdump`.
 604
 605
 606
 607 .. _etype_files:
 608
 609 Entry: files: A set of files arranged in a section
 610 --------------------------------------------------
 611
 612 Properties / Entry arguments:
 613     - pattern: Filename pattern to match the files to include
 614     - files-compress: Compression algorithm to use:
 615         none: No compression
 616         lz4: Use lz4 compression (via 'lz4' command-line utility)
 617     - files-align: Align each file to the given alignment
 618
 619 This entry reads a number of files and places each in a separate sub-entry
 620 within this entry. To access these you need to enable device-tree updates
 621 at run-time so you can obtain the file positions.
 622
 623
 624
 625 .. _etype_fill:
 626
 627 Entry: fill: An entry which is filled to a particular byte value
 628 ----------------------------------------------------------------
 629
 630 Properties / Entry arguments:
 631     - fill-byte: Byte to use to fill the entry
 632
 633 Note that the size property must be set since otherwise this entry does not
 634 know how large it should be.
 635
 636 You can often achieve the same effect using the pad-byte property of the
 637 overall image, in that the space between entries will then be padded with
 638 that byte. But this entry is sometimes useful for explicitly setting the
 639 byte value of a region.
 640
 641
 642
 643 .. _etype_fit:
 644
 645 Entry: fit: Flat Image Tree (FIT)
 646 ---------------------------------
 647
 648 This calls mkimage to create a FIT (U-Boot Flat Image Tree) based on the
 649 input provided.
 650
 651 Nodes for the FIT should be written out in the binman configuration just as
 652 they would be in a file passed to mkimage.
 653
 654 For example, this creates an image containing a FIT with U-Boot SPL::
 655
 656     binman {
 657         fit {
 658             description = "Test FIT";
 659             fit,fdt-list = "of-list";
 660
 661             images {
 662                 kernel@1 {
 663                     description = "SPL";
 664                     os = "u-boot";
 665                     type = "rkspi";
 666                     arch = "arm";
 667                     compression = "none";
 668                     load = <0>;
 669                     entry = <0>;
 670
 671                     u-boot-spl {
 672                     };
 673                 };
 674             };
 675         };
 676     };
 677
 678 More complex setups can be created, with generated nodes, as described
 679 below.
 680
 681 Properties (in the 'fit' node itself)
 682 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 683
 684 Special properties have a `fit,` prefix, indicating that they should be
 685 processed but not included in the final FIT.
 686
 687 The top-level 'fit' node supports the following special properties:
 688
 689     fit,external-offset
 690         Indicates that the contents of the FIT are external and provides the
 691         external offset. This is passed to mkimage via the -E and -p flags.
 692
 693     fit,align
 694         Indicates what alignment to use for the FIT and its external data,
 695         and provides the alignment to use. This is passed to mkimage via
 696         the -B flag.
 697
 698     fit,fdt-list
 699         Indicates the entry argument which provides the list of device tree
 700         files for the gen-fdt-nodes operation (as below). This is often
 701         `of-list` meaning that `-a of-list="dtb1 dtb2..."` should be passed
 702         to binman.
 703
 704     fit,fdt-list-val
 705         As an alternative to fit,fdt-list the list of device tree files
 706         can be provided in this property as a string list, e.g.::
 707
 708             fit,fdt-list-val = "dtb1", "dtb2";
 709
 710 Substitutions
 711 ~~~~~~~~~~~~~
 712
 713 Node names and property values support a basic string-substitution feature.
 714 Available substitutions for '@' nodes (and property values) are:
 715
 716 SEQ:
 717     Sequence number of the generated fdt (1, 2, ...)
 718 NAME
 719     Name of the dtb as provided (i.e. without adding '.dtb')
 720
 721 The `default` property, if present, will be automatically set to the name
 722 if of configuration whose devicetree matches the `default-dt` entry
 723 argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.
 724
 725 Available substitutions for property values in these nodes are:
 726
 727 DEFAULT-SEQ:
 728     Sequence number of the default fdt, as provided by the 'default-dt'
 729     entry argument
 730
 731 Available operations
 732 ~~~~~~~~~~~~~~~~~~~~
 733
 734 You can add an operation to an '@' node to indicate which operation is
 735 required::
 736
 737     @fdt-SEQ {
 738         fit,operation = "gen-fdt-nodes";
 739         ...
 740     };
 741
 742 Available operations are:
 743
 744 gen-fdt-nodes
 745     Generate FDT nodes as above. This is the default if there is no
 746     `fit,operation` property.
 747
 748 split-elf
 749     Split an ELF file into a separate node for each segment.
 750
 751 Generating nodes from an FDT list (gen-fdt-nodes)
 752 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 753
 754 U-Boot supports creating fdt and config nodes automatically. To do this,
 755 pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells
 756 binman that you want to generates nodes for two files: `file1.dtb` and
 757 `file2.dtb`. The `fit,fdt-list` property (see above) indicates that
 758 `of-list` should be used. If the property is missing you will get an error.
 759
 760 Then add a 'generator node', a node with a name starting with '@'::
 761
 762     images {
 763         @fdt-SEQ {
 764             description = "fdt-NAME";
 765             type = "flat_dt";
 766             compression = "none";
 767         };
 768     };
 769
 770 This tells binman to create nodes `fdt-1` and `fdt-2` for each of your two
 771 files. All the properties you specify will be included in the node. This
 772 node acts like a template to generate the nodes. The generator node itself
 773 does not appear in the output - it is replaced with what binman generates.
 774 A 'data' property is created with the contents of the FDT file.
 775
 776 You can create config nodes in a similar way::
 777
 778     configurations {
 779         default = "@config-DEFAULT-SEQ";
 780         @config-SEQ {
 781             description = "NAME";
 782             firmware = "atf";
 783             loadables = "uboot";
 784             fdt = "fdt-SEQ";
 785         };
 786     };
 787
 788 This tells binman to create nodes `config-1` and `config-2`, i.e. a config
 789 for each of your two files.
 790
 791 Note that if no devicetree files are provided (with '-a of-list' as above)
 792 then no nodes will be generated.
 793
 794 Generating nodes from an ELF file (split-elf)
 795 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 796
 797 This uses the node as a template to generate multiple nodes. The following
 798 special properties are available:
 799
 800 split-elf
 801     Split an ELF file into a separate node for each segment. This uses the
 802     node as a template to generate multiple nodes. The following special
 803     properties are available:
 804
 805     fit,load
 806         Generates a `load = <...>` property with the load address of the
 807         segment
 808
 809     fit,entry
 810         Generates a `entry = <...>` property with the entry address of the
 811         ELF. This is only produced for the first entry
 812
 813     fit,data
 814         Generates a `data = <...>` property with the contents of the segment
 815
 816     fit,firmware
 817         Generates a `firmware = <...>` property. Provides a list of possible
 818         nodes to be used as the `firmware` property value. The first valid
 819         node is picked as the firmware. Any remaining valid nodes is
 820         prepended to the `loadable` property generated by `fit,loadables`
 821
 822     fit,loadables
 823         Generates a `loadable = <...>` property with a list of the generated
 824         nodes (including all nodes if this operation is used multiple times)
 825
 826
 827 Here is an example showing ATF, TEE and a device tree all combined::
 828
 829     fit {
 830         description = "test-desc";
 831         #address-cells = <1>;
 832         fit,fdt-list = "of-list";
 833
 834         images {
 835             u-boot {
 836                 description = "U-Boot (64-bit)";
 837                 type = "standalone";
 838                 os = "U-Boot";
 839                 arch = "arm64";
 840                 compression = "none";
 841                 load = <CONFIG_TEXT_BASE>;
 842                 u-boot-nodtb {
 843                 };
 844             };
 845             @fdt-SEQ {
 846                 description = "fdt-NAME.dtb";
 847                 type = "flat_dt";
 848                 compression = "none";
 849             };
 850             @atf-SEQ {
 851                 fit,operation = "split-elf";
 852                 description = "ARM Trusted Firmware";
 853                 type = "firmware";
 854                 arch = "arm64";
 855                 os = "arm-trusted-firmware";
 856                 compression = "none";
 857                 fit,load;
 858                 fit,entry;
 859                 fit,data;
 860
 861                 atf-bl31 {
 862                 };
 863                 hash {
 864                     algo = "sha256";
 865                 };
 866             };
 867
 868             @tee-SEQ {
 869                 fit,operation = "split-elf";
 870                 description = "TEE";
 871                 type = "tee";
 872                 arch = "arm64";
 873                 os = "tee";
 874                 compression = "none";
 875                 fit,load;
 876                 fit,entry;
 877                 fit,data;
 878
 879                 tee-os {
 880                 };
 881                 hash {
 882                     algo = "sha256";
 883                 };
 884             };
 885         };
 886
 887         configurations {
 888             default = "@config-DEFAULT-SEQ";
 889             @config-SEQ {
 890                 description = "conf-NAME.dtb";
 891                 fdt = "fdt-SEQ";
 892                 fit,firmware = "atf-1", "u-boot";
 893                 fit,loadables;
 894             };
 895         };
 896     };
 897
 898 If ATF-BL31 is available, this generates a node for each segment in the
 899 ELF file, for example::
 900
 901     images {
 902         atf-1 {
 903             data = <...contents of first segment...>;
 904             data-offset = <0x00000000>;
 905             entry = <0x00040000>;
 906             load = <0x00040000>;
 907             compression = "none";
 908             os = "arm-trusted-firmware";
 909             arch = "arm64";
 910             type = "firmware";
 911             description = "ARM Trusted Firmware";
 912             hash {
 913                 algo = "sha256";
 914                 value = <...hash of first segment...>;
 915             };
 916         };
 917         atf-2 {
 918             data = <...contents of second segment...>;
 919             load = <0xff3b0000>;
 920             compression = "none";
 921             os = "arm-trusted-firmware";
 922             arch = "arm64";
 923             type = "firmware";
 924             description = "ARM Trusted Firmware";
 925             hash {
 926                 algo = "sha256";
 927                 value = <...hash of second segment...>;
 928             };
 929         };
 930     };
 931
 932 The same applies for OP-TEE if that is available.
 933
 934 If each binary is not available, the relevant template node (@atf-SEQ or
 935 @tee-SEQ) is removed from the output.
 936
 937 This also generates a `config-xxx` node for each device tree in `of-list`.
 938 Note that the U-Boot build system uses `-a of-list=$(CONFIG_OF_LIST)`
 939 so you can use `CONFIG_OF_LIST` to define that list. In this example it is
 940 set up for `firefly-rk3399` with a single device tree and the default set
 941 with `-a default-dt=$(CONFIG_DEFAULT_DEVICE_TREE)`, so the resulting output
 942 is::
 943
 944     configurations {
 945         default = "config-1";
 946         config-1 {
 947             loadables = "u-boot", "atf-2", "atf-3", "tee-1", "tee-2";
 948             description = "rk3399-firefly.dtb";
 949             fdt = "fdt-1";
 950             firmware = "atf-1";
 951         };
 952     };
 953
 954 U-Boot SPL can then load the firmware (ATF) and all the loadables (U-Boot
 955 proper, ATF and TEE), then proceed with the boot.
 956
 957
 958
 959 .. _etype_fmap:
 960
 961 Entry: fmap: An entry which contains an Fmap section
 962 ----------------------------------------------------
 963
 964 Properties / Entry arguments:
 965     None
 966
 967 FMAP is a simple format used by flashrom, an open-source utility for
 968 reading and writing the SPI flash, typically on x86 CPUs. The format
 969 provides flashrom with a list of areas, so it knows what it in the flash.
 970 It can then read or write just a single area, instead of the whole flash.
 971
 972 The format is defined by the flashrom project, in the file lib/fmap.h -
 973 see www.flashrom.org/Flashrom for more information.
 974
 975 When used, this entry will be populated with an FMAP which reflects the
 976 entries in the current image. Note that any hierarchy is squashed, since
 977 FMAP does not support this. Sections are represented as an area appearing
 978 before its contents, so that it is possible to reconstruct the hierarchy
 979 from the FMAP by using the offset information. This convention does not
 980 seem to be documented, but is used in Chromium OS.
 981
 982 To mark an area as preserved, use the normal 'preserved' flag in the entry.
 983 This will result in the corresponding FMAP area having the
 984 FMAP_AREA_PRESERVE flag. This flag does not automatically propagate down to
 985 child entries.
 986
 987 CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
 988
 989
 990
 991 .. _etype_gbb:
 992
 993 Entry: gbb: An entry which contains a Chromium OS Google Binary Block
 994 ---------------------------------------------------------------------
 995
 996 Properties / Entry arguments:
 997     - hardware-id: Hardware ID to use for this build (a string)
 998     - keydir: Directory containing the public keys to use
 999     - bmpblk: Filename containing images used by recovery
1000
1001 Chromium OS uses a GBB to store various pieces of information, in particular
1002 the root and recovery keys that are used to verify the boot process. Some
1003 more details are here:
1004
1005     https://www.chromium.org/chromium-os/firmware-porting-guide/2-concepts
1006
1007 but note that the page dates from 2013 so is quite out of date. See
1008 README.chromium for how to obtain the required keys and tools.
1009
1010
1011
1012 .. _etype_image_header:
1013
1014 Entry: image-header: An entry which contains a pointer to the FDT map
1015 ---------------------------------------------------------------------
1016
1017 Properties / Entry arguments:
1018     location: Location of header ("start" or "end" of image). This is
1019         optional. If omitted then the entry must have an offset property.
1020
1021 This adds an 8-byte entry to the start or end of the image, pointing to the
1022 location of the FDT map. The format is a magic number followed by an offset
1023 from the start or end of the image, in twos-compliment format.
1024
1025 This entry must be in the top-level part of the image.
1026
1027 NOTE: If the location is at the start/end, you will probably need to specify
1028 sort-by-offset for the image, unless you actually put the image header
1029 first/last in the entry list.
1030
1031
1032
1033 .. _etype_intel_cmc:
1034
1035 Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
1036 -----------------------------------------------------
1037
1038 Properties / Entry arguments:
1039     - filename: Filename of file to read into entry
1040
1041 This file contains microcode for some devices in a special format. An
1042 example filename is 'Microcode/C0_22211.BIN'.
1043
1044 See README.x86 for information about x86 binary blobs.
1045
1046
1047
1048 .. _etype_intel_descriptor:
1049
1050 Entry: intel-descriptor: Intel flash descriptor block (4KB)
1051 -----------------------------------------------------------
1052
1053 Properties / Entry arguments:
1054     filename: Filename of file containing the descriptor. This is typically
1055         a 4KB binary file, sometimes called 'descriptor.bin'
1056
1057 This entry is placed at the start of flash and provides information about
1058 the SPI flash regions. In particular it provides the base address and
1059 size of the ME (Management Engine) region, allowing us to place the ME
1060 binary in the right place.
1061
1062 With this entry in your image, the position of the 'intel-me' entry will be
1063 fixed in the image, which avoids you needed to specify an offset for that
1064 region. This is useful, because it is not possible to change the position
1065 of the ME region without updating the descriptor.
1066
1067 See README.x86 for information about x86 binary blobs.
1068
1069
1070
1071 .. _etype_intel_fit:
1072
1073 Entry: intel-fit: Intel Firmware Image Table (FIT)
1074 --------------------------------------------------
1075
1076 This entry contains a dummy FIT as required by recent Intel CPUs. The FIT
1077 contains information about the firmware and microcode available in the
1078 image.
1079
1080 At present binman only supports a basic FIT with no microcode.
1081
1082
1083
1084 .. _etype_intel_fit_ptr:
1085
1086 Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
1087 --------------------------------------------------------------
1088
1089 This entry contains a pointer to the FIT. It is required to be at address
1090 0xffffffc0 in the image.
1091
1092
1093
1094 .. _etype_intel_fsp:
1095
1096 Entry: intel-fsp: Intel Firmware Support Package (FSP) file
1097 -----------------------------------------------------------
1098
1099 Properties / Entry arguments:
1100     - filename: Filename of file to read into entry
1101
1102 This file contains binary blobs which are used on some devices to make the
1103 platform work. U-Boot executes this code since it is not possible to set up
1104 the hardware using U-Boot open-source code. Documentation is typically not
1105 available in sufficient detail to allow this.
1106
1107 An example filename is 'FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd'
1108
1109 See README.x86 for information about x86 binary blobs.
1110
1111
1112
1113 .. _etype_intel_fsp_m:
1114
1115 Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
1116 --------------------------------------------------------------------
1117
1118 Properties / Entry arguments:
1119     - filename: Filename of file to read into entry
1120
1121 This file contains a binary blob which is used on some devices to set up
1122 SDRAM. U-Boot executes this code in SPL so that it can make full use of
1123 memory. Documentation is typically not available in sufficient detail to
1124 allow U-Boot do this this itself..
1125
1126 An example filename is 'fsp_m.bin'
1127
1128 See README.x86 for information about x86 binary blobs.
1129
1130
1131
1132 .. _etype_intel_fsp_s:
1133
1134 Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
1135 ---------------------------------------------------------------------
1136
1137 Properties / Entry arguments:
1138     - filename: Filename of file to read into entry
1139
1140 This file contains a binary blob which is used on some devices to set up
1141 the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
1142 running, so that it can make full use of memory. Documentation is typically
1143 not available in sufficient detail to allow U-Boot do this this itself.
1144
1145 An example filename is 'fsp_s.bin'
1146
1147 See README.x86 for information about x86 binary blobs.
1148
1149
1150
1151 .. _etype_intel_fsp_t:
1152
1153 Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
1154 ----------------------------------------------------------------------
1155
1156 Properties / Entry arguments:
1157     - filename: Filename of file to read into entry
1158
1159 This file contains a binary blob which is used on some devices to set up
1160 temporary memory (Cache-as-RAM or CAR). U-Boot executes this code in TPL so
1161 that it has access to memory for its stack and initial storage.
1162
1163 An example filename is 'fsp_t.bin'
1164
1165 See README.x86 for information about x86 binary blobs.
1166
1167
1168
1169 .. _etype_intel_ifwi:
1170
1171 Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
1172 --------------------------------------------------------------
1173
1174 Properties / Entry arguments:
1175     - filename: Filename of file to read into entry. This is either the
1176         IFWI file itself, or a file that can be converted into one using a
1177         tool
1178     - convert-fit: If present this indicates that the ifwitool should be
1179         used to convert the provided file into a IFWI.
1180
1181 This file contains code and data used by the SoC that is required to make
1182 it work. It includes U-Boot TPL, microcode, things related to the CSE
1183 (Converged Security Engine, the microcontroller that loads all the firmware)
1184 and other items beyond the wit of man.
1185
1186 A typical filename is 'ifwi.bin' for an IFWI file, or 'fitimage.bin' for a
1187 file that will be converted to an IFWI.
1188
1189 The position of this entry is generally set by the intel-descriptor entry.
1190
1191 The contents of the IFWI are specified by the subnodes of the IFWI node.
1192 Each subnode describes an entry which is placed into the IFWFI with a given
1193 sub-partition (and optional entry name).
1194
1195 Properties for subnodes:
1196     - ifwi-subpart: sub-parition to put this entry into, e.g. "IBBP"
1197     - ifwi-entry: entry name t use, e.g. "IBBL"
1198     - ifwi-replace: if present, indicates that the item should be replaced
1199       in the IFWI. Otherwise it is added.
1200
1201 See README.x86 for information about x86 binary blobs.
1202
1203
1204
1205 .. _etype_intel_me:
1206
1207 Entry: intel-me: Intel Management Engine (ME) file
1208 --------------------------------------------------
1209
1210 Properties / Entry arguments:
1211     - filename: Filename of file to read into entry
1212
1213 This file contains code used by the SoC that is required to make it work.
1214 The Management Engine is like a background task that runs things that are
1215 not clearly documented, but may include keyboard, display and network
1216 access. For platform that use ME it is not possible to disable it. U-Boot
1217 does not directly execute code in the ME binary.
1218
1219 A typical filename is 'me.bin'.
1220
1221 The position of this entry is generally set by the intel-descriptor entry.
1222
1223 See README.x86 for information about x86 binary blobs.
1224
1225
1226
1227 .. _etype_intel_mrc:
1228
1229 Entry: intel-mrc: Intel Memory Reference Code (MRC) file
1230 --------------------------------------------------------
1231
1232 Properties / Entry arguments:
1233     - filename: Filename of file to read into entry
1234
1235 This file contains code for setting up the SDRAM on some Intel systems. This
1236 is executed by U-Boot when needed early during startup. A typical filename
1237 is 'mrc.bin'.
1238
1239 See README.x86 for information about x86 binary blobs.
1240
1241
1242
1243 .. _etype_intel_refcode:
1244
1245 Entry: intel-refcode: Intel Reference Code file
1246 -----------------------------------------------
1247
1248 Properties / Entry arguments:
1249     - filename: Filename of file to read into entry
1250
1251 This file contains code for setting up the platform on some Intel systems.
1252 This is executed by U-Boot when needed early during startup. A typical
1253 filename is 'refcode.bin'.
1254
1255 See README.x86 for information about x86 binary blobs.
1256
1257
1258
1259 .. _etype_intel_vbt:
1260
1261 Entry: intel-vbt: Intel Video BIOS Table (VBT) file
1262 ---------------------------------------------------
1263
1264 Properties / Entry arguments:
1265     - filename: Filename of file to read into entry
1266
1267 This file contains code that sets up the integrated graphics subsystem on
1268 some Intel SoCs. U-Boot executes this when the display is started up.
1269
1270 See README.x86 for information about Intel binary blobs.
1271
1272
1273
1274 .. _etype_intel_vga:
1275
1276 Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
1277 ---------------------------------------------------------
1278
1279 Properties / Entry arguments:
1280     - filename: Filename of file to read into entry
1281
1282 This file contains code that sets up the integrated graphics subsystem on
1283 some Intel SoCs. U-Boot executes this when the display is started up.
1284
1285 This is similar to the VBT file but in a different format.
1286
1287 See README.x86 for information about Intel binary blobs.
1288
1289
1290
1291 .. _etype_mkimage:
1292
1293 Entry: mkimage: Binary produced by mkimage
1294 ------------------------------------------
1295
1296 Properties / Entry arguments:
1297     - args: Arguments to pass
1298     - data-to-imagename: Indicates that the -d data should be passed in as
1299       the image name also (-n)
1300     - multiple-data-files: boolean to tell binman to pass all files as
1301       datafiles to mkimage instead of creating a temporary file the result
1302       of datafiles concatenation
1303     - filename: filename of output binary generated by mkimage
1304
1305 The data passed to mkimage via the -d flag is collected from subnodes of the
1306 mkimage node, e.g.::
1307
1308     mkimage {
1309         filename = "imximage.bin";
1310         args = "-n test -T imximage";
1311
1312         u-boot-spl {
1313         };
1314     };
1315
1316 This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
1317 file, with mkimage being called like this::
1318
1319     mkimage -d <data_file> -n test -T imximage <output_file>
1320
1321 The output from mkimage then becomes part of the image produced by
1322 binman but also is written into `imximage.bin` file. If you need to put
1323 multiple things in the data file, you can use a section, or just multiple
1324 subnodes like this::
1325
1326     mkimage {
1327         args = "-n test -T imximage";
1328
1329         u-boot-spl {
1330         };
1331
1332         u-boot-tpl {
1333         };
1334     };
1335
1336 Note that binman places the contents (here SPL and TPL) into a single file
1337 and passes that to mkimage using the -d option.
1338
1339 To pass all datafiles untouched to mkimage::
1340
1341     mkimage {
1342             args = "-n rk3399 -T rkspi";
1343             multiple-data-files;
1344
1345             u-boot-tpl {
1346             };
1347
1348             u-boot-spl {
1349             };
1350     };
1351
1352 This calls mkimage to create a Rockchip RK3399-specific first stage
1353 bootloader, made of TPL+SPL. Since this first stage bootloader requires to
1354 align the TPL and SPL but also some weird hacks that is handled by mkimage
1355 directly, binman is told to not perform the concatenation of datafiles prior
1356 to passing the data to mkimage.
1357
1358 To use CONFIG options in the arguments, use a string list instead, as in
1359 this example which also produces four arguments::
1360
1361     mkimage {
1362         args = "-n", CONFIG_SYS_SOC, "-T imximage";
1363
1364         u-boot-spl {
1365         };
1366     };
1367
1368 If you need to pass the input data in with the -n argument as well, then use
1369 the 'data-to-imagename' property::
1370
1371     mkimage {
1372         args = "-T imximage";
1373         data-to-imagename;
1374
1375         u-boot-spl {
1376         };
1377     };
1378
1379 That will pass the data to mkimage both as the data file (with -d) and as
1380 the image name (with -n). In both cases, a filename is passed as the
1381 argument, with the actual data being in that file.
1382
1383 If need to pass different data in with -n, then use an `imagename` subnode::
1384
1385     mkimage {
1386         args = "-T imximage";
1387
1388         imagename {
1389             blob {
1390                 filename = "spl/u-boot-spl.cfgout"
1391             };
1392         };
1393
1394         u-boot-spl {
1395         };
1396     };
1397
1398 This will pass in u-boot-spl as the input data and the .cfgout file as the
1399 -n data.
1400
1401
1402
1403 .. _etype_null:
1404
1405 Entry: null: An entry which has no contents of its own
1406 ------------------------------------------------------
1407
1408 Note that the size property must be set since otherwise this entry does not
1409 know how large it should be.
1410
1411 The contents are set by the containing section, e.g. the section's pad
1412 byte.
1413
1414
1415
1416 .. _etype_opensbi:
1417
1418 Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
1419 ----------------------------------------------
1420
1421 Properties / Entry arguments:
1422     - opensbi-path: Filename of file to read into entry. This is typically
1423         called fw_dynamic.bin
1424
1425 This entry holds the run-time firmware, typically started by U-Boot SPL.
1426 See the U-Boot README for your architecture or board for how to use it. See
1427 https://github.com/riscv/opensbi for more information about OpenSBI.
1428
1429
1430
1431 .. _etype_powerpc_mpc85xx_bootpg_resetvec:
1432
1433 Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
1434 -----------------------------------------------------------------------------------------
1435
1436 Properties / Entry arguments:
1437     - filename: Filename of u-boot-br.bin (default 'u-boot-br.bin')
1438
1439 This entry is valid for PowerPC mpc85xx cpus. This entry holds
1440 'bootpg + resetvec' code for PowerPC mpc85xx CPUs which needs to be
1441 placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
1442
1443
1444
1445 .. _etype_pre_load:
1446
1447 Entry: pre-load: Pre load image header
1448 --------------------------------------
1449
1450 Properties / Entry arguments:
1451     - pre-load-key-path: Path of the directory that store key (provided by
1452       the environment variable PRE_LOAD_KEY_PATH)
1453     - content: List of phandles to entries to sign
1454     - algo-name: Hash and signature algo to use for the signature
1455     - padding-name: Name of the padding (pkcs-1.5 or pss)
1456     - key-name: Filename of the private key to sign
1457     - header-size: Total size of the header
1458     - version: Version of the header
1459
1460 This entry creates a pre-load header that contains a global
1461 image signature.
1462
1463 For example, this creates an image with a pre-load header and a binary::
1464
1465     binman {
1466         image2 {
1467             filename = "sandbox.bin";
1468
1469             pre-load {
1470                 content = <&image>;
1471                 algo-name = "sha256,rsa2048";
1472                 padding-name = "pss";
1473                 key-name = "private.pem";
1474                 header-size = <4096>;
1475                 version = <1>;
1476             };
1477
1478             image: blob-ext {
1479                 filename = "sandbox.itb";
1480             };
1481         };
1482     };
1483
1484
1485
1486 .. _etype_rockchip_tpl:
1487
1488 Entry: rockchip-tpl: Rockchip TPL binary
1489 ----------------------------------------
1490
1491 Properties / Entry arguments:
1492     - rockchip-tpl-path: Filename of file to read into the entry,
1493                          typically <soc>_ddr_<version>.bin
1494
1495 This entry holds an external TPL binary used by some Rockchip SoCs
1496 instead of normal U-Boot TPL, typically to initialize DRAM.
1497
1498
1499
1500 .. _etype_scp:
1501
1502 Entry: scp: System Control Processor (SCP) firmware blob
1503 --------------------------------------------------------
1504
1505 Properties / Entry arguments:
1506     - scp-path: Filename of file to read into the entry, typically scp.bin
1507
1508 This entry holds firmware for an external platform-specific coprocessor.
1509
1510
1511
1512 .. _etype_section:
1513
1514 Entry: section: Entry that contains other entries
1515 -------------------------------------------------
1516
1517 A section is an entry which can contain other entries, thus allowing
1518 hierarchical images to be created. See 'Sections and hierarchical images'
1519 in the binman README for more information.
1520
1521 The base implementation simply joins the various entries together, using
1522 various rules about alignment, etc.
1523
1524 Subclassing
1525 ~~~~~~~~~~~
1526
1527 This class can be subclassed to support other file formats which hold
1528 multiple entries, such as CBFS. To do this, override the following
1529 functions. The documentation here describes what your function should do.
1530 For example code, see etypes which subclass `Entry_section`, or `cbfs.py`
1531 for a more involved example::
1532
1533    $ grep -l \(Entry_section tools/binman/etype/*.py
1534
1535 ReadNode()
1536     Call `super().ReadNode()`, then read any special properties for the
1537     section. Then call `self.ReadEntries()` to read the entries.
1538
1539     Binman calls this at the start when reading the image description.
1540
1541 ReadEntries()
1542     Read in the subnodes of the section. This may involve creating entries
1543     of a particular etype automatically, as well as reading any special
1544     properties in the entries. For each entry, entry.ReadNode() should be
1545     called, to read the basic entry properties. The properties should be
1546     added to `self._entries[]`, in the correct order, with a suitable name.
1547
1548     Binman calls this at the start when reading the image description.
1549
1550 BuildSectionData(required)
1551     Create the custom file format that you want and return it as bytes.
1552     This likely sets up a file header, then loops through the entries,
1553     adding them to the file. For each entry, call `entry.GetData()` to
1554     obtain the data. If that returns None, and `required` is False, then
1555     this method must give up and return None. But if `required` is True then
1556     it should assume that all data is valid.
1557
1558     Binman calls this when packing the image, to find out the size of
1559     everything. It is called again at the end when building the final image.
1560
1561 SetImagePos(image_pos):
1562     Call `super().SetImagePos(image_pos)`, then set the `image_pos` values
1563     for each of the entries. This should use the custom file format to find
1564     the `start offset` (and `image_pos`) of each entry. If the file format
1565     uses compression in such a way that there is no offset available (other
1566     than reading the whole file and decompressing it), then the offsets for
1567     affected entries can remain unset (`None`). The size should also be set
1568     if possible.
1569
1570     Binman calls this after the image has been packed, to update the
1571     location that all the entries ended up at.
1572
1573 ReadChildData(child, decomp, alt_format):
1574     The default version of this may be good enough, if you are able to
1575     implement SetImagePos() correctly. But that is a bit of a bypass, so
1576     you can override this method to read from your custom file format. It
1577     should read the entire entry containing the custom file using
1578     `super().ReadData(True)`, then parse the file to get the data for the
1579     given child, then return that data.
1580
1581     If your file format supports compression, the `decomp` argument tells
1582     you whether to return the compressed data (`decomp` is False) or to
1583     uncompress it first, then return the uncompressed data (`decomp` is
1584     True). This is used by the `binman extract -U` option.
1585
1586     If your entry supports alternative formats, the alt_format provides the
1587     alternative format that the user has selected. Your function should
1588     return data in that format. This is used by the 'binman extract -l'
1589     option.
1590
1591     Binman calls this when reading in an image, in order to populate all the
1592     entries with the data from that image (`binman ls`).
1593
1594 WriteChildData(child):
1595     Binman calls this after `child.data` is updated, to inform the custom
1596     file format about this, in case it needs to do updates.
1597
1598     The default version of this does nothing and probably needs to be
1599     overridden for the 'binman replace' command to work. Your version should
1600     use `child.data` to update the data for that child in the custom file
1601     format.
1602
1603     Binman calls this when updating an image that has been read in and in
1604     particular to update the data for a particular entry (`binman replace`)
1605
1606 Properties / Entry arguments
1607 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1608
1609 See :ref:`develop/package/binman:Image description format` for more
1610 information.
1611
1612 align-default
1613     Default alignment for this section, if no alignment is given in the
1614     entry
1615
1616 pad-byte
1617     Pad byte to use when padding
1618
1619 sort-by-offset
1620     True if entries should be sorted by offset, False if they must be
1621     in-order in the device tree description
1622
1623 end-at-4gb
1624     Used to build an x86 ROM which ends at 4GB (2^32)
1625
1626 name-prefix
1627     Adds a prefix to the name of every entry in the section when writing out
1628     the map
1629
1630 skip-at-start
1631     Number of bytes before the first entry starts. These effectively adjust
1632     the starting offset of entries. For example, if this is 16, then the
1633     first entry would start at 16. An entry with offset = 20 would in fact
1634     be written at offset 4 in the image file, since the first 16 bytes are
1635     skipped when writing.
1636
1637 filename
1638     filename to write the unpadded section contents to within the output
1639     directory (None to skip this).
1640
1641 Since a section is also an entry, it inherits all the properies of entries
1642 too.
1643
1644 Note that the `allow_missing` member controls whether this section permits
1645 external blobs to be missing their contents. The option will produce an
1646 image but of course it will not work. It is useful to make sure that
1647 Continuous Integration systems can build without the binaries being
1648 available. This is set by the `SetAllowMissing()` method, if
1649 `--allow-missing` is passed to binman.
1650
1651
1652
1653 .. _etype_tee_os:
1654
1655 Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
1656 ---------------------------------------------------------------
1657
1658 Properties / Entry arguments:
1659     - tee-os-path: Filename of file to read into entry. This is typically
1660         called tee.bin or tee.elf
1661
1662 This entry holds the run-time firmware, typically started by U-Boot SPL.
1663 See the U-Boot README for your architecture or board for how to use it. See
1664 https://github.com/OP-TEE/optee_os for more information about OP-TEE.
1665
1666 Note that if the file is in ELF format, it must go in a FIT. In that case,
1667 this entry will mark itself as absent, providing the data only through the
1668 read_elf_segments() method.
1669
1670 Marking this entry as absent means that it if is used in the wrong context
1671 it can be automatically dropped. Thus it is possible to add an OP-TEE entry
1672 like this::
1673
1674     binman {
1675         tee-os {
1676         };
1677     };
1678
1679 and pass either an ELF or plain binary in with -a tee-os-path <filename>
1680 and have binman do the right thing:
1681
1682    - include the entry if tee.bin is provided and it does NOT have the v1
1683      header
1684    - drop it otherwise
1685
1686 When used within a FIT, we can do::
1687
1688     binman {
1689         fit {
1690             tee-os {
1691             };
1692         };
1693     };
1694
1695 which will split the ELF into separate nodes for each segment, if an ELF
1696 file is provided (see :ref:`etype_fit`), or produce a single node if the
1697 OP-TEE binary v1 format is provided (see optee_doc_) .
1698
1699 .. _optee_doc: https://optee.readthedocs.io/en/latest/architecture/core.html#partitioning-of-the-binary
1700
1701
1702
1703 .. _etype_text:
1704
1705 Entry: text: An entry which contains text
1706 -----------------------------------------
1707
1708 The text can be provided either in the node itself or by a command-line
1709 argument. There is a level of indirection to allow multiple text strings
1710 and sharing of text.
1711
1712 Properties / Entry arguments:
1713     text-label: The value of this string indicates the property / entry-arg
1714         that contains the string to place in the entry
1715     <xxx> (actual name is the value of text-label): contains the string to
1716         place in the entry.
1717     <text>: The text to place in the entry (overrides the above mechanism).
1718         This is useful when the text is constant.
1719
1720 Example node::
1721
1722     text {
1723         size = <50>;
1724         text-label = "message";
1725     };
1726
1727 You can then use:
1728
1729     binman -amessage="this is my message"
1730
1731 and binman will insert that string into the entry.
1732
1733 It is also possible to put the string directly in the node::
1734
1735     text {
1736         size = <8>;
1737         text-label = "message";
1738         message = "a message directly in the node"
1739     };
1740
1741 or just::
1742
1743     text {
1744         size = <8>;
1745         text = "some text directly in the node"
1746     };
1747
1748 The text is not itself nul-terminated. This can be achieved, if required,
1749 by setting the size of the entry to something larger than the text.
1750
1751
1752
1753 .. _etype_ti_board_config:
1754
1755 Entry: ti-board-config: An entry containing a TI schema validated board config binary
1756 -------------------------------------------------------------------------------------
1757
1758 This etype supports generation of two kinds of board configuration
1759 binaries: singular board config binary as well as combined board config
1760 binary.
1761
1762 Properties / Entry arguments:
1763     - config-file: File containing board configuration data in YAML
1764     - schema-file: File containing board configuration YAML schema against
1765       which the config file is validated
1766
1767 Output files:
1768     - board config binary: File containing board configuration binary
1769
1770 These above parameters are used only when the generated binary is
1771 intended to be a single board configuration binary. Example::
1772
1773     my-ti-board-config {
1774         ti-board-config {
1775             config = "board-config.yaml";
1776             schema = "schema.yaml";
1777         };
1778     };
1779
1780 To generate a combined board configuration binary, we pack the
1781 needed individual binaries into a ti-board-config binary. In this case,
1782 the available supported subnode names are board-cfg, pm-cfg, sec-cfg and
1783 rm-cfg. The final binary is prepended with a header containing details about
1784 the included board config binaries. Example::
1785
1786     my-combined-ti-board-config {
1787         ti-board-config {
1788             board-cfg {
1789                 config = "board-cfg.yaml";
1790                 schema = "schema.yaml";
1791             };
1792             sec-cfg {
1793                 config = "sec-cfg.yaml";
1794                 schema = "schema.yaml";
1795             };
1796         }
1797     }
1798
1799
1800
1801 .. _etype_ti_secure:
1802
1803 Entry: ti-secure: Entry containing a TI x509 certificate binary
1804 ---------------------------------------------------------------
1805
1806 Properties / Entry arguments:
1807     - content: List of phandles to entries to sign
1808     - keyfile: Filename of file containing key to sign binary with
1809     - sha: Hash function to be used for signing
1810
1811 Output files:
1812     - input.<unique_name> - input file passed to openssl
1813     - config.<unique_name> - input file generated for openssl (which is
1814       used as the config file)
1815     - cert.<unique_name> - output file generated by openssl (which is
1816       used as the entry contents)
1817
1818 openssl signs the provided data, using the TI templated config file and
1819 writes the signature in this entry. This allows verification that the
1820 data is genuine.
1821
1822
1823
1824 .. _etype_ti_secure_rom:
1825
1826 Entry: ti-secure-rom: Entry containing a TI x509 certificate binary for images booted by ROM
1827 --------------------------------------------------------------------------------------------
1828
1829 Properties / Entry arguments:
1830     - keyfile: Filename of file containing key to sign binary with
1831     - combined: boolean if device follows combined boot flow
1832     - countersign: boolean if device contains countersigned system firmware
1833     - load: load address of SPL
1834     - sw-rev: software revision
1835     - sha: Hash function to be used for signing
1836     - core: core on which bootloader runs, valid cores are 'secure' and 'public'
1837     - content: phandle of SPL in case of legacy bootflow or phandles of component binaries
1838       in case of combined bootflow
1839
1840 The following properties are only for generating a combined bootflow binary:
1841     - sysfw-inner-cert: boolean if binary contains sysfw inner certificate
1842     - dm-data: boolean if binary contains dm-data binary
1843     - content-sbl: phandle of SPL binary
1844     - content-sysfw: phandle of sysfw binary
1845     - content-sysfw-data: phandle of sysfw-data or tifs-data binary
1846     - content-sysfw-inner-cert (optional): phandle of sysfw inner certificate binary
1847     - content-dm-data (optional): phandle of dm-data binary
1848     - load-sysfw: load address of sysfw binary
1849     - load-sysfw-data: load address of sysfw-data or tifs-data binary
1850     - load-sysfw-inner-cert (optional): load address of sysfw inner certificate binary
1851     - load-dm-data (optional): load address of dm-data binary
1852
1853 Output files:
1854     - input.<unique_name> - input file passed to openssl
1855     - config.<unique_name> - input file generated for openssl (which is
1856       used as the config file)
1857     - cert.<unique_name> - output file generated by openssl (which is
1858       used as the entry contents)
1859
1860 openssl signs the provided data, using the TI templated config file and
1861 writes the signature in this entry. This allows verification that the
1862 data is genuine.
1863
1864
1865
1866 .. _etype_u_boot:
1867
1868 Entry: u-boot: U-Boot flat binary
1869 ---------------------------------
1870
1871 Properties / Entry arguments:
1872     - filename: Filename of u-boot.bin (default 'u-boot.bin')
1873
1874 This is the U-Boot binary, containing relocation information to allow it
1875 to relocate itself at runtime. The binary typically includes a device tree
1876 blob at the end of it.
1877
1878 U-Boot can access binman symbols at runtime. See :ref:`binman_fdt`.
1879
1880 Note that this entry is automatically replaced with u-boot-expanded unless
1881 --no-expanded is used or the node has a 'no-expanded' property.
1882
1883
1884
1885 .. _etype_u_boot_dtb:
1886
1887 Entry: u-boot-dtb: U-Boot device tree
1888 -------------------------------------
1889
1890 Properties / Entry arguments:
1891     - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1892
1893 This is the U-Boot device tree, containing configuration information for
1894 U-Boot. U-Boot needs this to know what devices are present and which drivers
1895 to activate.
1896
1897 Note: This is mostly an internal entry type, used by others. This allows
1898 binman to know which entries contain a device tree.
1899
1900
1901
1902 .. _etype_u_boot_dtb_with_ucode:
1903
1904 Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
1905 -----------------------------------------------------------------------------------
1906
1907 Properties / Entry arguments:
1908     - filename: Filename of u-boot.dtb (default 'u-boot.dtb')
1909
1910 See Entry_u_boot_ucode for full details of the three entries involved in
1911 this process. This entry provides the U-Boot device-tree file, which
1912 contains the microcode. If the microcode is not being collated into one
1913 place then the offset and size of the microcode is recorded by this entry,
1914 for use by u-boot-with-ucode_ptr. If it is being collated, then this
1915 entry deletes the microcode from the device tree (to save space) and makes
1916 it available to u-boot-ucode.
1917
1918
1919
1920 .. _etype_u_boot_elf:
1921
1922 Entry: u-boot-elf: U-Boot ELF image
1923 -----------------------------------
1924
1925 Properties / Entry arguments:
1926     - filename: Filename of u-boot (default 'u-boot')
1927
1928 This is the U-Boot ELF image. It does not include a device tree but can be
1929 relocated to any address for execution.
1930
1931
1932
1933 .. _etype_u_boot_env:
1934
1935 Entry: u-boot-env: An entry which contains a U-Boot environment
1936 ---------------------------------------------------------------
1937
1938 Properties / Entry arguments:
1939     - filename: File containing the environment text, with each line in the
1940         form var=value
1941
1942
1943
1944 .. _etype_u_boot_expanded:
1945
1946 Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
1947 ------------------------------------------------------------------------------
1948
1949 This is a section containing the U-Boot binary and a devicetree. Using this
1950 entry type automatically creates this section, with the following entries
1951 in it:
1952
1953    u-boot-nodtb
1954    u-boot-dtb
1955
1956 Having the devicetree separate allows binman to update it in the final
1957 image, so that the entries positions are provided to the running U-Boot.
1958
1959
1960
1961 .. _etype_u_boot_img:
1962
1963 Entry: u-boot-img: U-Boot legacy image
1964 --------------------------------------
1965
1966 Properties / Entry arguments:
1967     - filename: Filename of u-boot.img (default 'u-boot.img')
1968
1969 This is the U-Boot binary as a packaged image, in legacy format. It has a
1970 header which allows it to be loaded at the correct address for execution.
1971
1972 You should use FIT (Flat Image Tree) instead of the legacy image for new
1973 applications.
1974
1975
1976
1977 .. _etype_u_boot_nodtb:
1978
1979 Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
1980 --------------------------------------------------------------------
1981
1982 Properties / Entry arguments:
1983     - filename: Filename to include (default 'u-boot-nodtb.bin')
1984
1985 This is the U-Boot binary, containing relocation information to allow it
1986 to relocate itself at runtime. It does not include a device tree blob at
1987 the end of it so normally cannot work without it. You can add a u-boot-dtb
1988 entry after this one, or use a u-boot entry instead, normally expands to a
1989 section containing u-boot and u-boot-dtb
1990
1991
1992
1993 .. _etype_u_boot_spl:
1994
1995 Entry: u-boot-spl: U-Boot SPL binary
1996 ------------------------------------
1997
1998 Properties / Entry arguments:
1999     - filename: Filename of u-boot-spl.bin (default 'spl/u-boot-spl.bin')
2000
2001 This is the U-Boot SPL (Secondary Program Loader) binary. This is a small
2002 binary which loads before U-Boot proper, typically into on-chip SRAM. It is
2003 responsible for locating, loading and jumping to U-Boot. Note that SPL is
2004 not relocatable so must be loaded to the correct address in SRAM, or written
2005 to run from the correct address if direct flash execution is possible (e.g.
2006 on x86 devices).
2007
2008 SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2009
2010 in the binman README for more information.
2011
2012 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2013 binman uses that to look up symbols to write into the SPL binary.
2014
2015 Note that this entry is automatically replaced with u-boot-spl-expanded
2016 unless --no-expanded is used or the node has a 'no-expanded' property.
2017
2018
2019
2020 .. _etype_u_boot_spl_bss_pad:
2021
2022 Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
2023 ---------------------------------------------------------------------
2024
2025 Properties / Entry arguments:
2026     None
2027
2028 This holds the padding added after the SPL binary to cover the BSS (Block
2029 Started by Symbol) region. This region holds the various variables used by
2030 SPL. It is set to 0 by SPL when it starts up. If you want to append data to
2031 the SPL image (such as a device tree file), you must pad out the BSS region
2032 to avoid the data overlapping with U-Boot variables. This entry is useful in
2033 that case. It automatically pads out the entry size to cover both the code,
2034 data and BSS.
2035
2036 The contents of this entry will a certain number of zero bytes, determined
2037 by __bss_size
2038
2039 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2040 binman uses that to look up the BSS address.
2041
2042
2043
2044 .. _etype_u_boot_spl_dtb:
2045
2046 Entry: u-boot-spl-dtb: U-Boot SPL device tree
2047 ---------------------------------------------
2048
2049 Properties / Entry arguments:
2050     - filename: Filename of u-boot.dtb (default 'spl/u-boot-spl.dtb')
2051
2052 This is the SPL device tree, containing configuration information for
2053 SPL. SPL needs this to know what devices are present and which drivers
2054 to activate.
2055
2056
2057
2058 .. _etype_u_boot_spl_elf:
2059
2060 Entry: u-boot-spl-elf: U-Boot SPL ELF image
2061 -------------------------------------------
2062
2063 Properties / Entry arguments:
2064     - filename: Filename of SPL u-boot (default 'spl/u-boot-spl')
2065
2066 This is the U-Boot SPL ELF image. It does not include a device tree but can
2067 be relocated to any address for execution.
2068
2069
2070
2071 .. _etype_u_boot_spl_expanded:
2072
2073 Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
2074 --------------------------------------------------------------------------------------
2075
2076 Properties / Entry arguments:
2077     - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2078         select)
2079
2080 This is a section containing the U-Boot binary, BSS padding if needed and a
2081 devicetree. Using this entry type automatically creates this section, with
2082 the following entries in it:
2083
2084    u-boot-spl-nodtb
2085    u-boot-spl-bss-pad
2086    u-boot-dtb
2087
2088 Having the devicetree separate allows binman to update it in the final
2089 image, so that the entries positions are provided to the running U-Boot.
2090
2091 This entry is selected based on the value of the 'spl-dtb' entryarg. If
2092 this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2093
2094
2095
2096 .. _etype_u_boot_spl_nodtb:
2097
2098 Entry: u-boot-spl-nodtb: SPL binary without device tree appended
2099 ----------------------------------------------------------------
2100
2101 Properties / Entry arguments:
2102     - filename: Filename to include (default 'spl/u-boot-spl-nodtb.bin')
2103
2104 This is the U-Boot SPL binary, It does not include a device tree blob at
2105 the end of it so may not be able to work without it, assuming SPL needs
2106 a device tree to operate on your platform. You can add a u-boot-spl-dtb
2107 entry after this one, or use a u-boot-spl entry instead' which normally
2108 expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
2109 u-boot-spl-dtb
2110
2111 SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2112
2113 in the binman README for more information.
2114
2115 The ELF file 'spl/u-boot-spl' must also be available for this to work, since
2116 binman uses that to look up symbols to write into the SPL binary.
2117
2118
2119
2120 .. _etype_u_boot_spl_pubkey_dtb:
2121
2122 Entry: u-boot-spl-pubkey-dtb: U-Boot SPL device tree including public key
2123 -------------------------------------------------------------------------
2124
2125 Properties / Entry arguments:
2126     - key-name-hint: Public key name without extension (.crt).
2127                 Default is determined by underlying
2128                 bintool (fdt_add_pubkey), usually 'key'.
2129     - algo: (Optional) Algorithm used for signing. Default is determined by
2130             underlying bintool (fdt_add_pubkey), usually 'sha1,rsa2048'
2131     - required: (Optional) If present this indicates that the key must be
2132                 verified for the image / configuration to be
2133                 considered valid
2134
2135 The following example shows an image containing an SPL which
2136 is packed together with the dtb. Binman will add a signature
2137 node to the dtb.
2138
2139 Example node::
2140
2141     image {
2142     ...
2143         spl {
2144             filename = "spl.bin"
2145
2146             u-boot-spl-nodtb {
2147             };
2148             u-boot-spl-pubkey-dtb {
2149                 algo = "sha384,rsa4096";
2150                 required = "conf";
2151                 key-name-hint = "dev";
2152             };
2153         };
2154     ...
2155     }
2156
2157
2158
2159 .. _etype_u_boot_spl_with_ucode_ptr:
2160
2161 Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
2162 ----------------------------------------------------------------------------
2163
2164 This is used when SPL must set up the microcode for U-Boot.
2165
2166 See Entry_u_boot_ucode for full details of the entries involved in this
2167 process.
2168
2169
2170
2171 .. _etype_u_boot_tpl:
2172
2173 Entry: u-boot-tpl: U-Boot TPL binary
2174 ------------------------------------
2175
2176 Properties / Entry arguments:
2177     - filename: Filename of u-boot-tpl.bin (default 'tpl/u-boot-tpl.bin')
2178
2179 This is the U-Boot TPL (Tertiary Program Loader) binary. This is a small
2180 binary which loads before SPL, typically into on-chip SRAM. It is
2181 responsible for locating, loading and jumping to SPL, the next-stage
2182 loader. Note that SPL is not relocatable so must be loaded to the correct
2183 address in SRAM, or written to run from the correct address if direct
2184 flash execution is possible (e.g. on x86 devices).
2185
2186 SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2187
2188 in the binman README for more information.
2189
2190 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2191 binman uses that to look up symbols to write into the TPL binary.
2192
2193 Note that this entry is automatically replaced with u-boot-tpl-expanded
2194 unless --no-expanded is used or the node has a 'no-expanded' property.
2195
2196
2197
2198 .. _etype_u_boot_tpl_bss_pad:
2199
2200 Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
2201 ---------------------------------------------------------------------
2202
2203 Properties / Entry arguments:
2204     None
2205
2206 This holds the padding added after the TPL binary to cover the BSS (Block
2207 Started by Symbol) region. This region holds the various variables used by
2208 TPL. It is set to 0 by TPL when it starts up. If you want to append data to
2209 the TPL image (such as a device tree file), you must pad out the BSS region
2210 to avoid the data overlapping with U-Boot variables. This entry is useful in
2211 that case. It automatically pads out the entry size to cover both the code,
2212 data and BSS.
2213
2214 The contents of this entry will a certain number of zero bytes, determined
2215 by __bss_size
2216
2217 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2218 binman uses that to look up the BSS address.
2219
2220
2221
2222 .. _etype_u_boot_tpl_dtb:
2223
2224 Entry: u-boot-tpl-dtb: U-Boot TPL device tree
2225 ---------------------------------------------
2226
2227 Properties / Entry arguments:
2228     - filename: Filename of u-boot.dtb (default 'tpl/u-boot-tpl.dtb')
2229
2230 This is the TPL device tree, containing configuration information for
2231 TPL. TPL needs this to know what devices are present and which drivers
2232 to activate.
2233
2234
2235
2236 .. _etype_u_boot_tpl_dtb_with_ucode:
2237
2238 Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
2239 ----------------------------------------------------------------------------
2240
2241 This is used when TPL must set up the microcode for U-Boot.
2242
2243 See Entry_u_boot_ucode for full details of the entries involved in this
2244 process.
2245
2246
2247
2248 .. _etype_u_boot_tpl_elf:
2249
2250 Entry: u-boot-tpl-elf: U-Boot TPL ELF image
2251 -------------------------------------------
2252
2253 Properties / Entry arguments:
2254     - filename: Filename of TPL u-boot (default 'tpl/u-boot-tpl')
2255
2256 This is the U-Boot TPL ELF image. It does not include a device tree but can
2257 be relocated to any address for execution.
2258
2259
2260
2261 .. _etype_u_boot_tpl_expanded:
2262
2263 Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
2264 --------------------------------------------------------------------------------------
2265
2266 Properties / Entry arguments:
2267     - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2268         select)
2269
2270 This is a section containing the U-Boot binary, BSS padding if needed and a
2271 devicetree. Using this entry type automatically creates this section, with
2272 the following entries in it:
2273
2274    u-boot-tpl-nodtb
2275    u-boot-tpl-bss-pad
2276    u-boot-dtb
2277
2278 Having the devicetree separate allows binman to update it in the final
2279 image, so that the entries positions are provided to the running U-Boot.
2280
2281 This entry is selected based on the value of the 'tpl-dtb' entryarg. If
2282 this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2283
2284
2285
2286 .. _etype_u_boot_tpl_nodtb:
2287
2288 Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
2289 ----------------------------------------------------------------
2290
2291 Properties / Entry arguments:
2292     - filename: Filename to include (default 'tpl/u-boot-tpl-nodtb.bin')
2293
2294 This is the U-Boot TPL binary, It does not include a device tree blob at
2295 the end of it so may not be able to work without it, assuming TPL needs
2296 a device tree to operate on your platform. You can add a u-boot-tpl-dtb
2297 entry after this one, or use a u-boot-tpl entry instead, which normally
2298 expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
2299 u-boot-tpl-dtb
2300
2301 TPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2302
2303 in the binman README for more information.
2304
2305 The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
2306 binman uses that to look up symbols to write into the TPL binary.
2307
2308
2309
2310 .. _etype_u_boot_tpl_with_ucode_ptr:
2311
2312 Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
2313 ----------------------------------------------------------------------------
2314
2315 See Entry_u_boot_ucode for full details of the entries involved in this
2316 process.
2317
2318
2319
2320 .. _etype_u_boot_ucode:
2321
2322 Entry: u-boot-ucode: U-Boot microcode block
2323 -------------------------------------------
2324
2325 Properties / Entry arguments:
2326     None
2327
2328 The contents of this entry are filled in automatically by other entries
2329 which must also be in the image.
2330
2331 U-Boot on x86 needs a single block of microcode. This is collected from
2332 the various microcode update nodes in the device tree. It is also unable
2333 to read the microcode from the device tree on platforms that use FSP
2334 (Firmware Support Package) binaries, because the API requires that the
2335 microcode is supplied before there is any SRAM available to use (i.e.
2336 the FSP sets up the SRAM / cache-as-RAM but does so in the call that
2337 requires the microcode!). To keep things simple, all x86 platforms handle
2338 microcode the same way in U-Boot (even non-FSP platforms). This is that
2339 a table is placed at _dt_ucode_base_size containing the base address and
2340 size of the microcode. This is either passed to the FSP (for FSP
2341 platforms), or used to set up the microcode (for non-FSP platforms).
2342 This all happens in the build system since it is the only way to get
2343 the microcode into a single blob and accessible without SRAM.
2344
2345 There are two cases to handle. If there is only one microcode blob in
2346 the device tree, then the ucode pointer it set to point to that. This
2347 entry (u-boot-ucode) is empty. If there is more than one update, then
2348 this entry holds the concatenation of all updates, and the device tree
2349 entry (u-boot-dtb-with-ucode) is updated to remove the microcode. This
2350 last step ensures that that the microcode appears in one contiguous
2351 block in the image and is not unnecessarily duplicated in the device
2352 tree. It is referred to as 'collation' here.
2353
2354 Entry types that have a part to play in handling microcode:
2355
2356     Entry_u_boot_with_ucode_ptr:
2357         Contains u-boot-nodtb.bin (i.e. U-Boot without the device tree).
2358         It updates it with the address and size of the microcode so that
2359         U-Boot can find it early on start-up.
2360     Entry_u_boot_dtb_with_ucode:
2361         Contains u-boot.dtb. It stores the microcode in a
2362         'self.ucode_data' property, which is then read by this class to
2363         obtain the microcode if needed. If collation is performed, it
2364         removes the microcode from the device tree.
2365     Entry_u_boot_ucode:
2366         This class. If collation is enabled it reads the microcode from
2367         the Entry_u_boot_dtb_with_ucode entry, and uses it as the
2368         contents of this entry.
2369
2370
2371
2372 .. _etype_u_boot_vpl:
2373
2374 Entry: u-boot-vpl: U-Boot VPL binary
2375 ------------------------------------
2376
2377 Properties / Entry arguments:
2378     - filename: Filename of u-boot-vpl.bin (default 'vpl/u-boot-vpl.bin')
2379
2380 This is the U-Boot VPL (Verifying Program Loader) binary. This is a small
2381 binary which loads before SPL, typically into on-chip SRAM. It is
2382 responsible for locating, loading and jumping to SPL, the next-stage
2383 loader. Note that VPL is not relocatable so must be loaded to the correct
2384 address in SRAM, or written to run from the correct address if direct
2385 flash execution is possible (e.g. on x86 devices).
2386
2387 SPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2388
2389 in the binman README for more information.
2390
2391 The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2392 binman uses that to look up symbols to write into the VPL binary.
2393
2394
2395
2396 .. _etype_u_boot_vpl_bss_pad:
2397
2398 Entry: u-boot-vpl-bss-pad: U-Boot VPL binary padded with a BSS region
2399 ---------------------------------------------------------------------
2400
2401 Properties / Entry arguments:
2402     None
2403
2404 This holds the padding added after the VPL binary to cover the BSS (Block
2405 Started by Symbol) region. This region holds the various variables used by
2406 VPL. It is set to 0 by VPL when it starts up. If you want to append data to
2407 the VPL image (such as a device tree file), you must pad out the BSS region
2408 to avoid the data overlapping with U-Boot variables. This entry is useful in
2409 that case. It automatically pads out the entry size to cover both the code,
2410 data and BSS.
2411
2412 The contents of this entry will a certain number of zero bytes, determined
2413 by __bss_size
2414
2415 The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2416 binman uses that to look up the BSS address.
2417
2418
2419
2420 .. _etype_u_boot_vpl_dtb:
2421
2422 Entry: u-boot-vpl-dtb: U-Boot VPL device tree
2423 ---------------------------------------------
2424
2425 Properties / Entry arguments:
2426     - filename: Filename of u-boot.dtb (default 'vpl/u-boot-vpl.dtb')
2427
2428 This is the VPL device tree, containing configuration information for
2429 VPL. VPL needs this to know what devices are present and which drivers
2430 to activate.
2431
2432
2433
2434 .. _etype_u_boot_vpl_elf:
2435
2436 Entry: u-boot-vpl-elf: U-Boot VPL ELF image
2437 -------------------------------------------
2438
2439 Properties / Entry arguments:
2440     - filename: Filename of VPL u-boot (default 'vpl/u-boot-vpl')
2441
2442 This is the U-Boot VPL ELF image. It does not include a device tree but can
2443 be relocated to any address for execution.
2444
2445
2446
2447 .. _etype_u_boot_vpl_expanded:
2448
2449 Entry: u-boot-vpl-expanded: U-Boot VPL flat binary broken out into its component parts
2450 --------------------------------------------------------------------------------------
2451
2452 Properties / Entry arguments:
2453     - vpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
2454         select)
2455
2456 This is a section containing the U-Boot binary, BSS padding if needed and a
2457 devicetree. Using this entry type automatically creates this section, with
2458 the following entries in it:
2459
2460    u-boot-vpl-nodtb
2461    u-boot-vpl-bss-pad
2462    u-boot-dtb
2463
2464 Having the devicetree separate allows binman to update it in the final
2465 image, so that the entries positions are provided to the running U-Boot.
2466
2467 This entry is selected based on the value of the 'vpl-dtb' entryarg. If
2468 this is non-empty (and not 'n' or '0') then this expanded entry is selected.
2469
2470
2471
2472 .. _etype_u_boot_vpl_nodtb:
2473
2474 Entry: u-boot-vpl-nodtb: VPL binary without device tree appended
2475 ----------------------------------------------------------------
2476
2477 Properties / Entry arguments:
2478     - filename: Filename to include (default 'vpl/u-boot-vpl-nodtb.bin')
2479
2480 This is the U-Boot VPL binary, It does not include a device tree blob at
2481 the end of it so may not be able to work without it, assuming VPL needs
2482 a device tree to operate on your platform. You can add a u_boot_vpl_dtb
2483 entry after this one, or use a u_boot_vpl entry instead, which normally
2484 expands to a section containing u-boot-vpl-dtb, u-boot-vpl-bss-pad and
2485 u-boot-vpl-dtb
2486
2487 VPL can access binman symbols at runtime. See :ref:`binman_fdt`.
2488
2489 The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
2490 binman uses that to look up symbols to write into the VPL binary.
2491
2492
2493
2494 .. _etype_u_boot_with_ucode_ptr:
2495
2496 Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
2497 --------------------------------------------------------------------
2498
2499 Properties / Entry arguments:
2500     - filename: Filename of u-boot-nodtb.bin (default 'u-boot-nodtb.bin')
2501     - optional-ucode: boolean property to make microcode optional. If the
2502         u-boot.bin image does not include microcode, no error will
2503         be generated.
2504
2505 See Entry_u_boot_ucode for full details of the three entries involved in
2506 this process. This entry updates U-Boot with the offset and size of the
2507 microcode, to allow early x86 boot code to find it without doing anything
2508 complicated. Otherwise it is the same as the u-boot entry.
2509
2510
2511
2512 .. _etype_vblock:
2513
2514 Entry: vblock: An entry which contains a Chromium OS verified boot block
2515 ------------------------------------------------------------------------
2516
2517 Properties / Entry arguments:
2518     - content: List of phandles to entries to sign
2519     - keydir: Directory containing the public keys to use
2520     - keyblock: Name of the key file to use (inside keydir)
2521     - signprivate: Name of provide key file to use (inside keydir)
2522     - version: Version number of the vblock (typically 1)
2523     - kernelkey: Name of the kernel key to use (inside keydir)
2524     - preamble-flags: Value of the vboot preamble flags (typically 0)
2525
2526 Output files:
2527     - input.<unique_name> - input file passed to futility
2528     - vblock.<unique_name> - output file generated by futility (which is
2529         used as the entry contents)
2530
2531 Chromium OS signs the read-write firmware and kernel, writing the signature
2532 in this block. This allows U-Boot to verify that the next firmware stage
2533 and kernel are genuine.
2534
2535
2536
2537 .. _etype_x509_cert:
2538
2539 Entry: x509-cert: An entry which contains an X509 certificate
2540 -------------------------------------------------------------
2541
2542 Properties / Entry arguments:
2543     - content: List of phandles to entries to sign
2544
2545 Output files:
2546     - input.<unique_name> - input file passed to openssl
2547     - cert.<unique_name> - output file generated by openssl (which is
2548         used as the entry contents)
2549
2550 openssl signs the provided data, writing the signature in this entry. This
2551 allows verification that the data is genuine
2552
2553
2554
2555 .. _etype_x86_reset16:
2556
2557 Entry: x86-reset16: x86 16-bit reset code for U-Boot
2558 ----------------------------------------------------
2559
2560 Properties / Entry arguments:
2561     - filename: Filename of u-boot-x86-reset16.bin (default
2562         'u-boot-x86-reset16.bin')
2563
2564 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2565 must be placed at a particular address. This entry holds that code. It is
2566 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2567 for jumping to the x86-start16 code, which continues execution.
2568
2569 For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
2570
2571
2572
2573 .. _etype_x86_reset16_spl:
2574
2575 Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
2576 --------------------------------------------------------
2577
2578 Properties / Entry arguments:
2579     - filename: Filename of u-boot-x86-reset16.bin (default
2580         'u-boot-x86-reset16.bin')
2581
2582 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2583 must be placed at a particular address. This entry holds that code. It is
2584 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2585 for jumping to the x86-start16 code, which continues execution.
2586
2587 For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
2588
2589
2590
2591 .. _etype_x86_reset16_tpl:
2592
2593 Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
2594 --------------------------------------------------------
2595
2596 Properties / Entry arguments:
2597     - filename: Filename of u-boot-x86-reset16.bin (default
2598         'u-boot-x86-reset16.bin')
2599
2600 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2601 must be placed at a particular address. This entry holds that code. It is
2602 typically placed at offset CONFIG_RESET_VEC_LOC. The code is responsible
2603 for jumping to the x86-start16 code, which continues execution.
2604
2605 For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
2606
2607
2608
2609 .. _etype_x86_start16:
2610
2611 Entry: x86-start16: x86 16-bit start-up code for U-Boot
2612 -------------------------------------------------------
2613
2614 Properties / Entry arguments:
2615     - filename: Filename of u-boot-x86-start16.bin (default
2616         'u-boot-x86-start16.bin')
2617
2618 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2619 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2620 entry holds that code. It is typically placed at offset
2621 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2622 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2623 U-Boot).
2624
2625 For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
2626
2627
2628
2629 .. _etype_x86_start16_spl:
2630
2631 Entry: x86-start16-spl: x86 16-bit start-up code for SPL
2632 --------------------------------------------------------
2633
2634 Properties / Entry arguments:
2635     - filename: Filename of spl/u-boot-x86-start16-spl.bin (default
2636         'spl/u-boot-x86-start16-spl.bin')
2637
2638 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2639 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2640 entry holds that code. It is typically placed at offset
2641 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2642 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2643 U-Boot).
2644
2645 For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
2646
2647
2648
2649 .. _etype_x86_start16_tpl:
2650
2651 Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
2652 --------------------------------------------------------
2653
2654 Properties / Entry arguments:
2655     - filename: Filename of tpl/u-boot-x86-start16-tpl.bin (default
2656         'tpl/u-boot-x86-start16-tpl.bin')
2657
2658 x86 CPUs start up in 16-bit mode, even if they are 32-bit CPUs. This code
2659 must be placed in the top 64KB of the ROM. The reset code jumps to it. This
2660 entry holds that code. It is typically placed at offset
2661 CONFIG_SYS_X86_START16. The code is responsible for changing to 32-bit mode
2662 and jumping to U-Boot's entry point, which requires 32-bit mode (for 32-bit
2663 U-Boot).
2664
2665 If TPL is not being used, the 'x86-start16-spl or 'x86-start16' entry types
2666 may be used instead.
2667
2668
2669
2670 .. _etype_xilinx_bootgen:
2671
2672 Entry: xilinx-bootgen: Signed SPL boot image for Xilinx ZynqMP devices
2673 ----------------------------------------------------------------------
2674
2675 Properties / Entry arguments:
2676     - auth-params: (Optional) Authentication parameters passed to bootgen
2677     - fsbl-config: (Optional) FSBL parameters passed to bootgen
2678     - keysrc-enc: (Optional) Key source when using decryption engine
2679     - pmufw-filename: Filename of PMU firmware. Default: pmu-firmware.elf
2680     - psk-key-name-hint: Name of primary secret key to use for signing the
2681                          secondardy public key. Format: .pem file
2682     - ssk-key-name-hint: Name of secondardy secret key to use for signing
2683                          the boot image. Format: .pem file
2684
2685 The etype is used to create a boot image for Xilinx ZynqMP
2686 devices.
2687
2688 Information for signed images:
2689
2690 In AMD/Xilinx SoCs, two pairs of public and secret keys are used
2691 - primary and secondary. The function of the primary public/secret key pair
2692 is to authenticate the secondary public/secret key pair.
2693 The function of the secondary key is to sign/verify the boot image. [1]
2694
2695 AMD/Xilinx uses the following terms for private/public keys [1]:
2696
2697     PSK = Primary Secret Key (Used to sign Secondary Public Key)
2698     PPK = Primary Public Key (Used to verify Secondary Public Key)
2699     SSK = Secondary Secret Key (Used to sign the boot image/partitions)
2700     SPK = Used to verify the actual boot image
2701
2702 The following example builds a signed boot image. The fuses of
2703 the primary public key (ppk) should be fused together with the RSA_EN flag.
2704
2705 Example node::
2706
2707     spl {
2708         filename = "boot.signed.bin";
2709
2710         xilinx-bootgen {
2711             psk-key-name-hint = "psk0";
2712             ssk-key-name-hint = "ssk0";
2713             auth-params = "ppk_select=0", "spk_id=0x00000000";
2714
2715             u-boot-spl-nodtb {
2716             };
2717             u-boot-spl-pubkey-dtb {
2718                 algo = "sha384,rsa4096";
2719                 required = "conf";
2720                 key-name-hint = "dev";
2721             };
2722         };
2723     };
2724
2725 For testing purposes, e.g. if no RSA_EN should be fused, one could add
2726 the "bh_auth_enable" flag in the fsbl-config field. This will skip the
2727 verification of the ppk fuses and boot the image, even if ppk hash is
2728 invalid.
2729
2730 Example node::
2731
2732     xilinx-bootgen {
2733         psk-key-name-hint = "psk0";
2734         psk-key-name-hint = "ssk0";
2735         ...
2736         fsbl-config = "bh_auth_enable";
2737         ...
2738     };
2739
2740 [1] https://docs.xilinx.com/r/en-US/ug1283-bootgen-user-guide/Using-Authentication
2741
2742
2743
2744