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