1.. SPDX-License-Identifier: GPL-2.0+ 2.. Copyright (c) 2016 Google, Inc 3 4Introduction 5============ 6 7Firmware often consists of several components which must be packaged together. 8For example, we may have SPL, U-Boot, a device tree and an environment area 9grouped together and placed in MMC flash. When the system starts, it must be 10able to find these pieces. 11 12Building firmware should be separate from packaging it. Many of the complexities 13of modern firmware build systems come from trying to do both at once. With 14binman, you build all the pieces that are needed, using whatever assortment of 15projects and build systems are needed, then use binman to stitch everything 16together. 17 18 19What it does 20------------ 21 22Binman reads your board's device tree and finds a node which describes the 23required image layout. It uses this to work out what to place where. 24 25Binman provides a mechanism for building images, from simple SPL + U-Boot 26combinations, to more complex arrangements with many parts. It also allows 27users to inspect images, extract and replace binaries within them, repacking if 28needed. 29 30 31Features 32-------- 33 34Apart from basic padding, alignment and positioning features, Binman supports 35hierarchical images, compression, hashing and dealing with the binary blobs 36which are a sad trend in open-source firmware at present. 37 38Executable binaries can access the location of other binaries in an image by 39using special linker symbols (zero-overhead but somewhat limited) or by reading 40the devicetree description of the image. 41 42Binman is designed primarily for use with U-Boot and associated binaries such 43as ARM Trusted Firmware, but it is suitable for use with other projects, such 44as Zephyr. Binman also provides facilities useful in Chromium OS, such as CBFS, 45vblocks and and the like. 46 47Binman provides a way to process binaries before they are included, by adding a 48Python plug-in. 49 50Binman is intended for use with U-Boot but is designed to be general enough 51to be useful in other image-packaging situations. 52 53 54Motivation 55---------- 56 57As mentioned above, packaging of firmware is quite a different task from 58building the various parts. In many cases the various binaries which go into 59the image come from separate build systems. For example, ARM Trusted Firmware 60is used on ARMv8 devices but is not built in the U-Boot tree. If a Linux kernel 61is included in the firmware image, it is built elsewhere. 62 63It is of course possible to add more and more build rules to the U-Boot 64build system to cover these cases. It can shell out to other Makefiles and 65build scripts. But it seems better to create a clear divide between building 66software and packaging it. 67 68At present this is handled by manual instructions, different for each board, 69on how to create images that will boot. By turning these instructions into a 70standard format, we can support making valid images for any board without 71manual effort, lots of READMEs, etc. 72 73Benefits: 74 75 - Each binary can have its own build system and tool chain without creating 76 any dependencies between them 77 - Avoids the need for a single-shot build: individual parts can be updated 78 and brought in as needed 79 - Provides for a standard image description available in the build and at 80 run-time 81 - SoC-specific image-signing tools can be accommodated 82 - Avoids cluttering the U-Boot build system with image-building code 83 - The image description is automatically available at run-time in U-Boot, 84 SPL. It can be made available to other software also 85 - The image description is easily readable (it's a text file in device-tree 86 format) and permits flexible packing of binaries 87 88 89Terminology 90----------- 91 92Binman uses the following terms: 93 94- image - an output file containing a firmware image 95- binary - an input binary that goes into the image 96 97 98Relationship to FIT 99------------------- 100 101FIT is U-Boot's official image format. It supports multiple binaries with 102load / execution addresses, compression. It also supports verification 103through hashing and RSA signatures. 104 105FIT was originally designed to support booting a Linux kernel (with an 106optional ramdisk) and device tree chosen from various options in the FIT. 107Now that U-Boot supports configuration via device tree, it is possible to 108load U-Boot from a FIT, with the device tree chosen by SPL. 109 110Binman considers FIT to be one of the binaries it can place in the image. 111 112Where possible it is best to put as much as possible in the FIT, with binman 113used to deal with cases not covered by FIT. Examples include initial 114execution (since FIT itself does not have an executable header) and dealing 115with device boundaries, such as the read-only/read-write separation in SPI 116flash. 117 118For U-Boot, binman should not be used to create ad-hoc images in place of 119FIT. 120 121 122Relationship to mkimage 123----------------------- 124 125The mkimage tool provides a means to create a FIT. Traditionally it has 126needed an image description file: a device tree, like binman, but in a 127different format. More recently it has started to support a '-f auto' mode 128which can generate that automatically. 129 130More relevant to binman, mkimage also permits creation of many SoC-specific 131image types. These can be listed by running 'mkimage -T list'. Examples 132include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often 133called from the U-Boot build system for this reason. 134 135Binman considers the output files created by mkimage to be binary blobs 136which it can place in an image. Binman does not replace the mkimage tool or 137this purpose. It would be possible in some situations to create a new entry 138type for the images in mkimage, but this would not add functionality. It 139seems better to use the mkimage tool to generate binaries and avoid blurring 140the boundaries between building input files (mkimage) and packaging then 141into a final image (binman). 142 143 144Using binman 145============ 146 147Example use of binman in U-Boot 148------------------------------- 149 150Binman aims to replace some of the ad-hoc image creation in the U-Boot 151build system. 152 153Consider sunxi. It has the following steps: 154 155 #. It uses a custom mksunxiboot tool to build an SPL image called 156 sunxi-spl.bin. This should probably move into mkimage. 157 158 #. It uses mkimage to package U-Boot into a legacy image file (so that it can 159 hold the load and execution address) called u-boot.img. 160 161 #. It builds a final output image called u-boot-sunxi-with-spl.bin which 162 consists of sunxi-spl.bin, some padding and u-boot.img. 163 164Binman is intended to replace the last step. The U-Boot build system builds 165u-boot.bin and sunxi-spl.bin. Binman can then take over creation of 166sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any 167case, it would then create the image from the component parts. 168 169This simplifies the U-Boot Makefile somewhat, since various pieces of logic 170can be replaced by a call to binman. 171 172 173Example use of binman for x86 174----------------------------- 175 176In most cases x86 images have a lot of binary blobs, 'black-box' code 177provided by Intel which must be run for the platform to work. Typically 178these blobs are not relocatable and must be placed at fixed areas in the 179firmware image. 180 181Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA 182BIOS, reference code and Intel ME binaries into a u-boot.rom file. 183 184Binman is intended to replace all of this, with ifdtool left to handle only 185the configuration of the Intel-format descriptor. 186 187 188Running binman 189-------------- 190 191First install prerequisites, e.g:: 192 193 sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \ 194 liblz4-tool 195 196Type:: 197 198 binman build -b <board_name> 199 200to build an image for a board. The board name is the same name used when 201configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox'). 202Binman assumes that the input files for the build are in ../b/<board_name>. 203 204Or you can specify this explicitly:: 205 206 binman build -I <build_path> 207 208where <build_path> is the build directory containing the output of the U-Boot 209build. 210 211(Future work will make this more configurable) 212 213In either case, binman picks up the device tree file (u-boot.dtb) and looks 214for its instructions in the 'binman' node. 215 216Binman has a few other options which you can see by running 'binman -h'. 217 218 219Enabling binman for a board 220--------------------------- 221 222At present binman is invoked from a rule in the main Makefile. You should be 223able to enable CONFIG_BINMAN to enable this rule. 224 225The output file is typically named image.bin and is located in the output 226directory. If input files are needed to you add these to INPUTS-y either in the 227main Makefile or in a config.mk file in your arch subdirectory. 228 229Once binman is executed it will pick up its instructions from a device-tree 230file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value. 231You can use other, more specific CONFIG options - see 'Automatic .dtsi 232inclusion' below. 233 234 235Using binman with OF_BOARD or OF_PRIOR_STAGE 236-------------------------------------------- 237 238Normally binman is used with a board configured with OF_SEPARATE or OF_EMBED. 239This is a typical scenario where a device tree source that contains the binman 240node is provided in the arch/<arch>/dts directory for a specific board. 241 242However for a board configured with OF_BOARD or OF_PRIOR_STAGE, no device tree 243blob is provided in the U-Boot build phase hence the binman node information 244is not available. In order to support such use case, a new Kconfig option 245BINMAN_STANDALONE_FDT is introduced, to tell the build system that a standalone 246device tree blob containing binman node is explicitly required. 247 248Note there is a Kconfig option BINMAN_FDT which enables U-Boot run time to 249access information about binman entries, stored in the device tree in a binman 250node. Generally speaking, this option makes sense for OF_SEPARATE or OF_EMBED. 251For the other OF_CONTROL methods, it's quite possible binman node is not 252available as binman is invoked during the build phase, thus this option is not 253turned on by default for these OF_CONTROL methods. 254 255See qemu-riscv64_spl_defconfig for an example of how binman is used with 256OF_PRIOR_STAGE to generate u-boot.itb image. 257 258 259Access to binman entry offsets at run time (symbols) 260---------------------------------------------------- 261 262Binman assembles images and determines where each entry is placed in the image. 263This information may be useful to U-Boot at run time. For example, in SPL it 264is useful to be able to find the location of U-Boot so that it can be executed 265when SPL is finished. 266 267Binman allows you to declare symbols in the SPL image which are filled in 268with their correct values during the build. For example:: 269 270 binman_sym_declare(ulong, u_boot_any, image_pos); 271 272declares a ulong value which will be assigned to the image-pos of any U-Boot 273image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image. 274You can access this value with something like:: 275 276 ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos); 277 278Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming 279that the whole image has been loaded, or is available in flash. You can then 280jump to that address to start U-Boot. 281 282At present this feature is only supported in SPL and TPL. In principle it is 283possible to fill in such symbols in U-Boot proper, as well, but a future C 284library is planned for this instead, to read from the device tree. 285 286As well as image-pos, it is possible to read the size of an entry and its 287offset (which is the start position of the entry within its parent). 288 289A small technical note: Binman automatically adds the base address of the image 290(i.e. __image_copy_start) to the value of the image-pos symbol, so that when the 291image is loaded to its linked address, the value will be correct and actually 292point into the image. 293 294For example, say SPL is at the start of the image and linked to start at address 29580108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos 296for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded 297to 80108000, with SPL at 80108000 and U-Boot at 80110000. 298 299For x86 devices (with the end-at-4gb property) this base address is not added 300since it is assumed that images are XIP and the offsets already include the 301address. 302 303 304Access to binman entry offsets at run time (fdt) 305------------------------------------------------ 306 307Binman can update the U-Boot FDT to include the final position and size of 308each entry in the images it processes. The option to enable this is -u and it 309causes binman to make sure that the 'offset', 'image-pos' and 'size' properties 310are set correctly for every entry. Since it is not necessary to specify these in 311the image definition, binman calculates the final values and writes these to 312the device tree. These can be used by U-Boot at run-time to find the location 313of each entry. 314 315Alternatively, an FDT map entry can be used to add a special FDT containing 316just the information about the image. This is preceded by a magic string so can 317be located anywhere in the image. An image header (typically at the start or end 318of the image) can be used to point to the FDT map. See fdtmap and image-header 319entries for more information. 320 321 322Map files 323--------- 324 325The -m option causes binman to output a .map file for each image that it 326generates. This shows the offset and size of each entry. For example:: 327 328 Offset Size Name 329 00000000 00000028 main-section 330 00000000 00000010 section@0 331 00000000 00000004 u-boot 332 00000010 00000010 section@1 333 00000000 00000004 u-boot 334 335This shows a hierarchical image with two sections, each with a single entry. The 336offsets of the sections are absolute hex byte offsets within the image. The 337offsets of the entries are relative to their respective sections. The size of 338each entry is also shown, in bytes (hex). The indentation shows the entries 339nested inside their sections. 340 341 342Passing command-line arguments to entries 343----------------------------------------- 344 345Sometimes it is useful to pass binman the value of an entry property from the 346command line. For example some entries need access to files and it is not 347always convenient to put these filenames in the image definition (device tree). 348 349The -a option supports this:: 350 351 -a <prop>=<value> 352 353where:: 354 355 <prop> is the property to set 356 <value> is the value to set it to 357 358Not all properties can be provided this way. Only some entries support it, 359typically for filenames. 360 361 362Image description format 363======================== 364 365The binman node is called 'binman'. An example image description is shown 366below:: 367 368 binman { 369 filename = "u-boot-sunxi-with-spl.bin"; 370 pad-byte = <0xff>; 371 blob { 372 filename = "spl/sunxi-spl.bin"; 373 }; 374 u-boot { 375 offset = <CONFIG_SPL_PAD_TO>; 376 }; 377 }; 378 379 380This requests binman to create an image file called u-boot-sunxi-with-spl.bin 381consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the 382normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The 383padding comes from the fact that the second binary is placed at 384CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would 385immediately follow the SPL binary. 386 387The binman node describes an image. The sub-nodes describe entries in the 388image. Each entry represents a region within the overall image. The name of 389the entry (blob, u-boot) tells binman what to put there. For 'blob' we must 390provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'. 391 392Entries are normally placed into the image sequentially, one after the other. 393The image size is the total size of all entries. As you can see, you can 394specify the start offset of an entry using the 'offset' property. 395 396Note that due to a device tree requirement, all entries must have a unique 397name. If you want to put the same binary in the image multiple times, you can 398use any unique name, with the 'type' property providing the type. 399 400The attributes supported for entries are described below. 401 402offset: 403 This sets the offset of an entry within the image or section containing 404 it. The first byte of the image is normally at offset 0. If 'offset' is 405 not provided, binman sets it to the end of the previous region, or the 406 start of the image's entry area (normally 0) if there is no previous 407 region. 408 409align: 410 This sets the alignment of the entry. The entry offset is adjusted 411 so that the entry starts on an aligned boundary within the containing 412 section or image. For example 'align = <16>' means that the entry will 413 start on a 16-byte boundary. This may mean that padding is added before 414 the entry. The padding is part of the containing section but is not 415 included in the entry, meaning that an empty space may be created before 416 the entry starts. Alignment should be a power of 2. If 'align' is not 417 provided, no alignment is performed. 418 419size: 420 This sets the size of the entry. The contents will be padded out to 421 this size. If this is not provided, it will be set to the size of the 422 contents. 423 424pad-before: 425 Padding before the contents of the entry. Normally this is 0, meaning 426 that the contents start at the beginning of the entry. This can be used 427 to offset the entry contents a little. While this does not affect the 428 contents of the entry within binman itself (the padding is performed 429 only when its parent section is assembled), the end result will be that 430 the entry starts with the padding bytes, so may grow. Defaults to 0. 431 432pad-after: 433 Padding after the contents of the entry. Normally this is 0, meaning 434 that the entry ends at the last byte of content (unless adjusted by 435 other properties). This allows room to be created in the image for 436 this entry to expand later. While this does not affect the contents of 437 the entry within binman itself (the padding is performed only when its 438 parent section is assembled), the end result will be that the entry ends 439 with the padding bytes, so may grow. Defaults to 0. 440 441align-size: 442 This sets the alignment of the entry size. For example, to ensure 443 that the size of an entry is a multiple of 64 bytes, set this to 64. 444 While this does not affect the contents of the entry within binman 445 itself (the padding is performed only when its parent section is 446 assembled), the end result is that the entry ends with the padding 447 bytes, so may grow. If 'align-size' is not provided, no alignment is 448 performed. 449 450align-end: 451 This sets the alignment of the end of an entry with respect to the 452 containing section. Some entries require that they end on an alignment 453 boundary, regardless of where they start. This does not move the start 454 of the entry, so the contents of the entry will still start at the 455 beginning. But there may be padding at the end. While this does not 456 affect the contents of the entry within binman itself (the padding is 457 performed only when its parent section is assembled), the end result 458 is that the entry ends with the padding bytes, so may grow. 459 If 'align-end' is not provided, no alignment is performed. 460 461filename: 462 For 'blob' types this provides the filename containing the binary to 463 put into the entry. If binman knows about the entry type (like 464 u-boot-bin), then there is no need to specify this. 465 466type: 467 Sets the type of an entry. This defaults to the entry name, but it is 468 possible to use any name, and then add (for example) 'type = "u-boot"' 469 to specify the type. 470 471offset-unset: 472 Indicates that the offset of this entry should not be set by placing 473 it immediately after the entry before. Instead, is set by another 474 entry which knows where this entry should go. When this boolean 475 property is present, binman will give an error if another entry does 476 not set the offset (with the GetOffsets() method). 477 478image-pos: 479 This cannot be set on entry (or at least it is ignored if it is), but 480 with the -u option, binman will set it to the absolute image position 481 for each entry. This makes it easy to find out exactly where the entry 482 ended up in the image, regardless of parent sections, etc. 483 484expand-size: 485 Expand the size of this entry to fit available space. This space is only 486 limited by the size of the image/section and the position of the next 487 entry. 488 489compress: 490 Sets the compression algortihm to use (for blobs only). See the entry 491 documentation for details. 492 493missing-msg: 494 Sets the tag of the message to show if this entry is missing. This is 495 used for external blobs. When they are missing it is helpful to show 496 information about what needs to be fixed. See missing-blob-help for the 497 message for each tag. 498 499no-expanded: 500 By default binman substitutes entries with expanded versions if available, 501 so that a `u-boot` entry type turns into `u-boot-expanded`, for example. The 502 `--no-expanded` command-line option disables this globally. The 503 `no-expanded` property disables this just for a single entry. Put the 504 `no-expanded` boolean property in the node to select this behaviour. 505 506The attributes supported for images and sections are described below. Several 507are similar to those for entries. 508 509size: 510 Sets the image size in bytes, for example 'size = <0x100000>' for a 511 1MB image. 512 513offset: 514 This is similar to 'offset' in entries, setting the offset of a section 515 within the image or section containing it. The first byte of the section 516 is normally at offset 0. If 'offset' is not provided, binman sets it to 517 the end of the previous region, or the start of the image's entry area 518 (normally 0) if there is no previous region. 519 520align-size: 521 This sets the alignment of the image size. For example, to ensure 522 that the image ends on a 512-byte boundary, use 'align-size = <512>'. 523 If 'align-size' is not provided, no alignment is performed. 524 525pad-before: 526 This sets the padding before the image entries. The first entry will 527 be positioned after the padding. This defaults to 0. 528 529pad-after: 530 This sets the padding after the image entries. The padding will be 531 placed after the last entry. This defaults to 0. 532 533pad-byte: 534 This specifies the pad byte to use when padding in the image. It 535 defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'. 536 537filename: 538 This specifies the image filename. It defaults to 'image.bin'. 539 540sort-by-offset: 541 This causes binman to reorder the entries as needed to make sure they 542 are in increasing positional order. This can be used when your entry 543 order may not match the positional order. A common situation is where 544 the 'offset' properties are set by CONFIG options, so their ordering is 545 not known a priori. 546 547 This is a boolean property so needs no value. To enable it, add a 548 line 'sort-by-offset;' to your description. 549 550multiple-images: 551 Normally only a single image is generated. To create more than one 552 image, put this property in the binman node. For example, this will 553 create image1.bin containing u-boot.bin, and image2.bin containing 554 both spl/u-boot-spl.bin and u-boot.bin:: 555 556 binman { 557 multiple-images; 558 image1 { 559 u-boot { 560 }; 561 }; 562 563 image2 { 564 spl { 565 }; 566 u-boot { 567 }; 568 }; 569 }; 570 571end-at-4gb: 572 For x86 machines the ROM offsets start just before 4GB and extend 573 up so that the image finished at the 4GB boundary. This boolean 574 option can be enabled to support this. The image size must be 575 provided so that binman knows when the image should start. For an 576 8MB ROM, the offset of the first entry would be 0xfff80000 with 577 this option, instead of 0 without this option. 578 579skip-at-start: 580 This property specifies the entry offset of the first entry. 581 582 For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry 583 offset of the first entry. It can be 0xeff40000 or 0xfff40000 for 584 nor flash boot, 0x201000 for sd boot etc. 585 586 'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE + 587 Image size != 4gb. 588 589align-default: 590 Specifies the default alignment for entries in this section, if they do 591 not specify an alignment. Note that this only applies to top-level entries 592 in the section (direct subentries), not any subentries of those entries. 593 This means that each section must specify its own default alignment, if 594 required. 595 596Examples of the above options can be found in the tests. See the 597tools/binman/test directory. 598 599It is possible to have the same binary appear multiple times in the image, 600either by using a unit number suffix (u-boot@0, u-boot@1) or by using a 601different name for each and specifying the type with the 'type' attribute. 602 603 604Sections and hierachical images 605------------------------------- 606 607Sometimes it is convenient to split an image into several pieces, each of which 608contains its own set of binaries. An example is a flash device where part of 609the image is read-only and part is read-write. We can set up sections for each 610of these, and place binaries in them independently. The image is still produced 611as a single output file. 612 613This feature provides a way of creating hierarchical images. For example here 614is an example image with two copies of U-Boot. One is read-only (ro), intended 615to be written only in the factory. Another is read-write (rw), so that it can be 616upgraded in the field. The sizes are fixed so that the ro/rw boundary is known 617and can be programmed:: 618 619 binman { 620 section@0 { 621 read-only; 622 name-prefix = "ro-"; 623 size = <0x100000>; 624 u-boot { 625 }; 626 }; 627 section@1 { 628 name-prefix = "rw-"; 629 size = <0x100000>; 630 u-boot { 631 }; 632 }; 633 }; 634 635This image could be placed into a SPI flash chip, with the protection boundary 636set at 1MB. 637 638A few special properties are provided for sections: 639 640read-only: 641 Indicates that this section is read-only. This has no impact on binman's 642 operation, but his property can be read at run time. 643 644name-prefix: 645 This string is prepended to all the names of the binaries in the 646 section. In the example above, the 'u-boot' binaries which actually be 647 renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to 648 distinguish binaries with otherwise identical names. 649 650 651Image Properties 652---------------- 653 654Image nodes act like sections but also have a few extra properties: 655 656filename: 657 Output filename for the image. This defaults to image.bin (or in the 658 case of multiple images <nodename>.bin where <nodename> is the name of 659 the image node. 660 661allow-repack: 662 Create an image that can be repacked. With this option it is possible 663 to change anything in the image after it is created, including updating 664 the position and size of image components. By default this is not 665 permitted since it is not possibly to know whether this might violate a 666 constraint in the image description. For example, if a section has to 667 increase in size to hold a larger binary, that might cause the section 668 to fall out of its allow region (e.g. read-only portion of flash). 669 670 Adding this property causes the original offset and size values in the 671 image description to be stored in the FDT and fdtmap. 672 673 674Hashing Entries 675--------------- 676 677It is possible to ask binman to hash the contents of an entry and write that 678value back to the device-tree node. For example:: 679 680 binman { 681 u-boot { 682 hash { 683 algo = "sha256"; 684 }; 685 }; 686 }; 687 688Here, a new 'value' property will be written to the 'hash' node containing 689the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole 690sections can be hased if desired, by adding the 'hash' node to the section. 691 692The has value can be chcked at runtime by hashing the data actually read and 693comparing this has to the value in the device tree. 694 695 696Expanded entries 697---------------- 698 699Binman automatically replaces 'u-boot' with an expanded version of that, i.e. 700'u-boot-expanded'. This means that when you write:: 701 702 u-boot { 703 }; 704 705you actually get:: 706 707 u-boot { 708 type = "u-boot-expanded'; 709 }; 710 711which in turn expands to:: 712 713 u-boot { 714 type = "section"; 715 716 u-boot-nodtb { 717 }; 718 719 u-boot-dtb { 720 }; 721 }; 722 723U-Boot's various phase binaries actually comprise two or three pieces. 724For example, u-boot.bin has the executable followed by a devicetree. 725 726With binman we want to be able to update that devicetree with full image 727information so that it is accessible to the executable. This is tricky 728if it is not clear where the devicetree starts. 729 730The above feature ensures that the devicetree is clearly separated from the 731U-Boot executable and can be updated separately by binman as needed. It can be 732disabled with the --no-expanded flag if required. 733 734The same applies for u-boot-spl and u-boot-spl. In those cases, the expansion 735includes the BSS padding, so for example:: 736 737 spl { 738 type = "u-boot-spl" 739 }; 740 741you actually get:: 742 743 spl { 744 type = "u-boot-expanded'; 745 }; 746 747which in turn expands to:: 748 749 spl { 750 type = "section"; 751 752 u-boot-spl-nodtb { 753 }; 754 755 u-boot-spl-bss-pad { 756 }; 757 758 u-boot-spl-dtb { 759 }; 760 }; 761 762Of course we should not expand SPL if it has no devicetree. Also if the BSS 763padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS), 764the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned 765entry type is controlled by the UseExpanded() method. In the SPL case it checks 766the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree. 767 768For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. All 769entry args are provided by the U-Boot Makefile. 770 771 772Compression 773----------- 774 775Binman support compression for 'blob' entries (those of type 'blob' and 776derivatives). To enable this for an entry, add a 'compress' property:: 777 778 blob { 779 filename = "datafile"; 780 compress = "lz4"; 781 }; 782 783The entry will then contain the compressed data, using the 'lz4' compression 784algorithm. Currently this is the only one that is supported. The uncompressed 785size is written to the node in an 'uncomp-size' property, if -u is used. 786 787Compression is also supported for sections. In that case the entire section is 788compressed in one block, including all its contents. This means that accessing 789an entry from the section required decompressing the entire section. Also, the 790size of a section indicates the space that it consumes in its parent section 791(and typically the image). With compression, the section may contain more data, 792and the uncomp-size property indicates that, as above. The contents of the 793section is compressed first, before any padding is added. This ensures that the 794padding itself is not compressed, which would be a waste of time. 795 796 797Automatic .dtsi inclusion 798------------------------- 799 800It is sometimes inconvenient to add a 'binman' node to the .dts file for each 801board. This can be done by using #include to bring in a common file. Another 802approach supported by the U-Boot build system is to automatically include 803a common header. You can then put the binman node (and anything else that is 804specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header 805file. 806 807Binman will search for the following files in arch/<arch>/dts:: 808 809 <dts>-u-boot.dtsi where <dts> is the base name of the .dts file 810 <CONFIG_SYS_SOC>-u-boot.dtsi 811 <CONFIG_SYS_CPU>-u-boot.dtsi 812 <CONFIG_SYS_VENDOR>-u-boot.dtsi 813 u-boot.dtsi 814 815U-Boot will only use the first one that it finds. If you need to include a 816more general file you can do that from the more specific file using #include. 817If you are having trouble figuring out what is going on, you can uncomment 818the 'warning' line in scripts/Makefile.lib to see what it has found:: 819 820 # Uncomment for debugging 821 # This shows all the files that were considered and the one that we chose. 822 # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw) 823 824 825Entry Documentation 826=================== 827 828For details on the various entry types supported by binman and how to use them, 829see entries.rst which is generated from the source code using: 830 831 binman entry-docs >tools/binman/entries.rst 832 833.. toctree:: 834 :maxdepth: 2 835 836 entries 837 838 839Managing images 840=============== 841 842Listing images 843-------------- 844 845It is possible to list the entries in an existing firmware image created by 846binman, provided that there is an 'fdtmap' entry in the image. For example:: 847 848 $ binman ls -i image.bin 849 Name Image-pos Size Entry-type Offset Uncomp-size 850 ---------------------------------------------------------------------- 851 main-section c00 section 0 852 u-boot 0 4 u-boot 0 853 section 5fc section 4 854 cbfs 100 400 cbfs 0 855 u-boot 138 4 u-boot 38 856 u-boot-dtb 180 108 u-boot-dtb 80 3b5 857 u-boot-dtb 500 1ff u-boot-dtb 400 3b5 858 fdtmap 6fc 381 fdtmap 6fc 859 image-header bf8 8 image-header bf8 860 861This shows the hierarchy of the image, the position, size and type of each 862entry, the offset of each entry within its parent and the uncompressed size if 863the entry is compressed. 864 865It is also possible to list just some files in an image, e.g.:: 866 867 $ binman ls -i image.bin section/cbfs 868 Name Image-pos Size Entry-type Offset Uncomp-size 869 -------------------------------------------------------------------- 870 cbfs 100 400 cbfs 0 871 u-boot 138 4 u-boot 38 872 u-boot-dtb 180 108 u-boot-dtb 80 3b5 873 874or with wildcards:: 875 876 $ binman ls -i image.bin "*cb*" "*head*" 877 Name Image-pos Size Entry-type Offset Uncomp-size 878 ---------------------------------------------------------------------- 879 cbfs 100 400 cbfs 0 880 u-boot 138 4 u-boot 38 881 u-boot-dtb 180 108 u-boot-dtb 80 3b5 882 image-header bf8 8 image-header bf8 883 884 885Extracting files from images 886---------------------------- 887 888You can extract files from an existing firmware image created by binman, 889provided that there is an 'fdtmap' entry in the image. For example:: 890 891 $ binman extract -i image.bin section/cbfs/u-boot 892 893which will write the uncompressed contents of that entry to the file 'u-boot' in 894the current directory. You can also extract to a particular file, in this case 895u-boot.bin:: 896 897 $ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin 898 899It is possible to extract all files into a destination directory, which will 900put files in subdirectories matching the entry hierarchy:: 901 902 $ binman extract -i image.bin -O outdir 903 904or just a selection:: 905 906 $ binman extract -i image.bin "*u-boot*" -O outdir 907 908 909Replacing files in an image 910--------------------------- 911 912You can replace files in an existing firmware image created by binman, provided 913that there is an 'fdtmap' entry in the image. For example: 914 915 $ binman replace -i image.bin section/cbfs/u-boot 916 917which will write the contents of the file 'u-boot' from the current directory 918to the that entry, compressing if necessary. If the entry size changes, you must 919add the 'allow-repack' property to the original image before generating it (see 920above), otherwise you will get an error. 921 922You can also use a particular file, in this case u-boot.bin:: 923 924 $ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin 925 926It is possible to replace all files from a source directory which uses the same 927hierarchy as the entries:: 928 929 $ binman replace -i image.bin -I indir 930 931Files that are missing will generate a warning. 932 933You can also replace just a selection of entries:: 934 935 $ binman replace -i image.bin "*u-boot*" -I indir 936 937 938Logging 939------- 940 941Binman normally operates silently unless there is an error, in which case it 942just displays the error. The -D/--debug option can be used to create a full 943backtrace when errors occur. You can use BINMAN_DEBUG=1 when building to select 944this. 945 946Internally binman logs some output while it is running. This can be displayed 947by increasing the -v/--verbosity from the default of 1: 948 949 0: silent 950 1: warnings only 951 2: notices (important messages) 952 3: info about major operations 953 4: detailed information about each operation 954 5: debug (all output) 955 956You can use BINMAN_VERBOSE=5 (for example) when building to select this. 957 958 959Technical details 960================= 961 962Order of image creation 963----------------------- 964 965Image creation proceeds in the following order, for each entry in the image. 966 9671. AddMissingProperties() - binman can add calculated values to the device 968tree as part of its processing, for example the offset and size of each 969entry. This method adds any properties associated with this, expanding the 970device tree as needed. These properties can have placeholder values which are 971set later by SetCalculatedProperties(). By that stage the size of sections 972cannot be changed (since it would cause the images to need to be repacked), 973but the correct values can be inserted. 974 9752. ProcessFdt() - process the device tree information as required by the 976particular entry. This may involve adding or deleting properties. If the 977processing is complete, this method should return True. If the processing 978cannot complete because it needs the ProcessFdt() method of another entry to 979run first, this method should return False, in which case it will be called 980again later. 981 9823. GetEntryContents() - the contents of each entry are obtained, normally by 983reading from a file. This calls the Entry.ObtainContents() to read the 984contents. The default version of Entry.ObtainContents() calls 985Entry.GetDefaultFilename() and then reads that file. So a common mechanism 986to select a file to read is to override that function in the subclass. The 987functions must return True when they have read the contents. Binman will 988retry calling the functions a few times if False is returned, allowing 989dependencies between the contents of different entries. 990 9914. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can 992return a dict containing entries that need updating. The key should be the 993entry name and the value is a tuple (offset, size). This allows an entry to 994provide the offset and size for other entries. The default implementation 995of GetEntryOffsets() returns {}. 996 9975. PackEntries() - calls Entry.Pack() which figures out the offset and 998size of an entry. The 'current' image offset is passed in, and the function 999returns the offset immediately after the entry being packed. The default 1000implementation of Pack() is usually sufficient. 1001 1002Note: for sections, this also checks that the entries do not overlap, nor extend 1003outside the section. If the section does not have a defined size, the size is 1004set large enough to hold all the entries. 1005 10066. SetImagePos() - sets the image position of every entry. This is the absolute 1007position 'image-pos', as opposed to 'offset' which is relative to the containing 1008section. This must be done after all offsets are known, which is why it is quite 1009late in the ordering. 1010 10117. SetCalculatedProperties() - update any calculated properties in the device 1012tree. This sets the correct 'offset' and 'size' vaues, for example. 1013 10148. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry. 1015The default implementatoin does nothing. This can be overriden to adjust the 1016contents of an entry in some way. For example, it would be possible to create 1017an entry containing a hash of the contents of some other entries. At this 1018stage the offset and size of entries should not be adjusted unless absolutely 1019necessary, since it requires a repack (going back to PackEntries()). 1020 10219. ResetForPack() - if the ProcessEntryContents() step failed, in that an entry 1022has changed its size, then there is no alternative but to go back to step 5 and 1023try again, repacking the entries with the updated size. ResetForPack() removes 1024the fixed offset/size values added by binman, so that the packing can start from 1025scratch. 1026 102710. WriteSymbols() - write the value of symbols into the U-Boot SPL binary. 1028See 'Access to binman entry offsets at run time' below for a description of 1029what happens in this stage. 1030 103111. BuildImage() - builds the image and writes it to a file 1032 103312. WriteMap() - writes a text file containing a map of the image. This is the 1034final step. 1035 1036 1037External tools 1038-------------- 1039 1040Binman can make use of external command-line tools to handle processing of 1041entry contents or to generate entry contents. These tools are executed using 1042the 'tools' module's Run() method. The tools generally must exist on the PATH, 1043but the --toolpath option can be used to specify additional search paths to 1044use. This option can be specified multiple times to add more than one path. 1045 1046For some compile tools binman will use the versions specified by commonly-used 1047environment variables like CC and HOSTCC for the C compiler, based on whether 1048the tool's output will be used for the target or for the host machine. If those 1049aren't given, it will also try to derive target-specific versions from the 1050CROSS_COMPILE environment variable during a cross-compilation. 1051 1052 1053Code coverage 1054------------- 1055 1056Binman is a critical tool and is designed to be very testable. Entry 1057implementations target 100% test coverage. Run 'binman test -T' to check this. 1058 1059To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):: 1060 1061 $ sudo apt-get install python-coverage python3-coverage python-pytest 1062 1063 1064Concurrent tests 1065---------------- 1066 1067Binman tries to run tests concurrently. This means that the tests make use of 1068all available CPUs to run. 1069 1070 To enable this:: 1071 1072 $ sudo apt-get install python-subunit python3-subunit 1073 1074Use '-P 1' to disable this. It is automatically disabled when code coverage is 1075being used (-T) since they are incompatible. 1076 1077 1078Debugging tests 1079--------------- 1080 1081Sometimes when debugging tests it is useful to keep the input and output 1082directories so they can be examined later. Use -X or --test-preserve-dirs for 1083this. 1084 1085 1086Running tests on non-x86 architectures 1087-------------------------------------- 1088 1089Binman's tests have been written under the assumption that they'll be run on a 1090x86-like host and there hasn't been an attempt to make them portable yet. 1091However, it's possible to run the tests by cross-compiling to x86. 1092 1093To install an x86 cross-compiler on Debian-type distributions (e.g. Ubuntu):: 1094 1095 $ sudo apt-get install gcc-x86-64-linux-gnu 1096 1097Then, you can run the tests under cross-compilation:: 1098 1099 $ CROSS_COMPILE=x86_64-linux-gnu- binman test -T 1100 1101You can also use gcc-i686-linux-gnu similar to the above. 1102 1103 1104Writing new entries and debugging 1105--------------------------------- 1106 1107The behaviour of entries is defined by the Entry class. All other entries are 1108a subclass of this. An important subclass is Entry_blob which takes binary 1109data from a file and places it in the entry. In fact most entry types are 1110subclasses of Entry_blob. 1111 1112Each entry type is a separate file in the tools/binman/etype directory. Each 1113file contains a class called Entry_<type> where <type> is the entry type. 1114New entry types can be supported by adding new files in that directory. 1115These will automatically be detected by binman when needed. 1116 1117Entry properties are documented in entry.py. The entry subclasses are free 1118to change the values of properties to support special behaviour. For example, 1119when Entry_blob loads a file, it sets content_size to the size of the file. 1120Entry classes can adjust other entries. For example, an entry that knows 1121where other entries should be positioned can set up those entries' offsets 1122so they don't need to be set in the binman decription. It can also adjust 1123entry contents. 1124 1125Most of the time such essoteric behaviour is not needed, but it can be 1126essential for complex images. 1127 1128If you need to specify a particular device-tree compiler to use, you can define 1129the DTC environment variable. This can be useful when the system dtc is too 1130old. 1131 1132To enable a full backtrace and other debugging features in binman, pass 1133BINMAN_DEBUG=1 to your build:: 1134 1135 make qemu-x86_defconfig 1136 make BINMAN_DEBUG=1 1137 1138To enable verbose logging from binman, base BINMAN_VERBOSE to your build, which 1139adds a -v<level> option to the call to binman:: 1140 1141 make qemu-x86_defconfig 1142 make BINMAN_VERBOSE=5 1143 1144 1145History / Credits 1146----------------- 1147 1148Binman takes a lot of inspiration from a Chrome OS tool called 1149'cros_bundle_firmware', which I wrote some years ago. That tool was based on 1150a reasonably simple and sound design but has expanded greatly over the 1151years. In particular its handling of x86 images is convoluted. 1152 1153Quite a few lessons have been learned which are hopefully applied here. 1154 1155 1156Design notes 1157------------ 1158 1159On the face of it, a tool to create firmware images should be fairly simple: 1160just find all the input binaries and place them at the right place in the 1161image. The difficulty comes from the wide variety of input types (simple 1162flat binaries containing code, packaged data with various headers), packing 1163requirments (alignment, spacing, device boundaries) and other required 1164features such as hierarchical images. 1165 1166The design challenge is to make it easy to create simple images, while 1167allowing the more complex cases to be supported. For example, for most 1168images we don't much care exactly where each binary ends up, so we should 1169not have to specify that unnecessarily. 1170 1171New entry types should aim to provide simple usage where possible. If new 1172core features are needed, they can be added in the Entry base class. 1173 1174 1175To do 1176----- 1177 1178Some ideas: 1179 1180- Use of-platdata to make the information available to code that is unable 1181 to use device tree (such as a very small SPL image). For now, limited info is 1182 available via linker symbols 1183- Allow easy building of images by specifying just the board name 1184- Support building an image for a board (-b) more completely, with a 1185 configurable build directory 1186- Detect invalid properties in nodes 1187- Sort the fdtmap by offset 1188- Output temporary files to a different directory 1189 1190-- 1191Simon Glass <sjg@chromium.org> 11927/7/2016 1193