Home | History | Annotate | only in /external/u-boot/tools/binman
Up to higher level directory
NameDateSize
binman22-Oct-20204.5K
binman.py22-Oct-20204.5K
bsection.py22-Oct-202012K
cmdline.py22-Oct-20202.2K
control.py22-Oct-20203.7K
elf.py22-Oct-20204.3K
elf_test.py22-Oct-20203.9K
entry.py22-Oct-20208.8K
entry_test.py22-Oct-20201.7K
etype/22-Oct-2020
fdt_test.py22-Oct-20202.7K
ftest.py22-Oct-202038.6K
image.py22-Oct-20203.5K
image_test.py22-Oct-20201.8K
README22-Oct-202025K
test/22-Oct-2020

README

      1 # SPDX-License-Identifier: GPL-2.0+
      2 # Copyright (c) 2016 Google, Inc
      3 
      4 Introduction
      5 ------------
      6 
      7 Firmware often consists of several components which must be packaged together.
      8 For example, we may have SPL, U-Boot, a device tree and an environment area
      9 grouped together and placed in MMC flash. When the system starts, it must be
     10 able to find these pieces.
     11 
     12 So far U-Boot has not provided a way to handle creating such images in a
     13 general way. Each SoC does what it needs to build an image, often packing or
     14 concatenating images in the U-Boot build system.
     15 
     16 Binman aims to provide a mechanism for building images, from simple
     17 SPL + U-Boot combinations, to more complex arrangements with many parts.
     18 
     19 
     20 What it does
     21 ------------
     22 
     23 Binman reads your board's device tree and finds a node which describes the
     24 required image layout. It uses this to work out what to place where. The
     25 output file normally contains the device tree, so it is in principle possible
     26 to read an image and extract its constituent parts.
     27 
     28 
     29 Features
     30 --------
     31 
     32 So far binman is pretty simple. It supports binary blobs, such as 'u-boot',
     33 'spl' and 'fdt'. It supports empty entries (such as setting to 0xff). It can
     34 place entries at a fixed location in the image, or fit them together with
     35 suitable padding and alignment. It provides a way to process binaries before
     36 they are included, by adding a Python plug-in. The device tree is available
     37 to U-Boot at run-time so that the images can be interpreted.
     38 
     39 Binman does not yet update the device tree with the final location of
     40 everything when it is done. A simple C structure could be generated for
     41 constrained environments like SPL (using dtoc) but this is also not
     42 implemented.
     43 
     44 Binman can also support incorporating filesystems in the image if required.
     45 For example x86 platforms may use CBFS in some cases.
     46 
     47 Binman is intended for use with U-Boot but is designed to be general enough
     48 to be useful in other image-packaging situations.
     49 
     50 
     51 Motivation
     52 ----------
     53 
     54 Packaging of firmware is quite a different task from building the various
     55 parts. In many cases the various binaries which go into the image come from
     56 separate build systems. For example, ARM Trusted Firmware is used on ARMv8
     57 devices but is not built in the U-Boot tree. If a Linux kernel is included
     58 in the firmware image, it is built elsewhere.
     59 
     60 It is of course possible to add more and more build rules to the U-Boot
     61 build system to cover these cases. It can shell out to other Makefiles and
     62 build scripts. But it seems better to create a clear divide between building
     63 software and packaging it.
     64 
     65 At present this is handled by manual instructions, different for each board,
     66 on how to create images that will boot. By turning these instructions into a
     67 standard format, we can support making valid images for any board without
     68 manual effort, lots of READMEs, etc.
     69 
     70 Benefits:
     71 - Each binary can have its own build system and tool chain without creating
     72 any dependencies between them
     73 - Avoids the need for a single-shot build: individual parts can be updated
     74 and brought in as needed
     75 - Provides for a standard image description available in the build and at
     76 run-time
     77 - SoC-specific image-signing tools can be accomodated
     78 - Avoids cluttering the U-Boot build system with image-building code
     79 - The image description is automatically available at run-time in U-Boot,
     80 SPL. It can be made available to other software also
     81 - The image description is easily readable (it's a text file in device-tree
     82 format) and permits flexible packing of binaries
     83 
     84 
     85 Terminology
     86 -----------
     87 
     88 Binman uses the following terms:
     89 
     90 - image - an output file containing a firmware image
     91 - binary - an input binary that goes into the image
     92 
     93 
     94 Relationship to FIT
     95 -------------------
     96 
     97 FIT is U-Boot's official image format. It supports multiple binaries with
     98 load / execution addresses, compression. It also supports verification
     99 through hashing and RSA signatures.
    100 
    101 FIT was originally designed to support booting a Linux kernel (with an
    102 optional ramdisk) and device tree chosen from various options in the FIT.
    103 Now that U-Boot supports configuration via device tree, it is possible to
    104 load U-Boot from a FIT, with the device tree chosen by SPL.
    105 
    106 Binman considers FIT to be one of the binaries it can place in the image.
    107 
    108 Where possible it is best to put as much as possible in the FIT, with binman
    109 used to deal with cases not covered by FIT. Examples include initial
    110 execution (since FIT itself does not have an executable header) and dealing
    111 with device boundaries, such as the read-only/read-write separation in SPI
    112 flash.
    113 
    114 For U-Boot, binman should not be used to create ad-hoc images in place of
    115 FIT.
    116 
    117 
    118 Relationship to mkimage
    119 -----------------------
    120 
    121 The mkimage tool provides a means to create a FIT. Traditionally it has
    122 needed an image description file: a device tree, like binman, but in a
    123 different format. More recently it has started to support a '-f auto' mode
    124 which can generate that automatically.
    125 
    126 More relevant to binman, mkimage also permits creation of many SoC-specific
    127 image types. These can be listed by running 'mkimage -T list'. Examples
    128 include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often
    129 called from the U-Boot build system for this reason.
    130 
    131 Binman considers the output files created by mkimage to be binary blobs
    132 which it can place in an image. Binman does not replace the mkimage tool or
    133 this purpose. It would be possible in some situtions to create a new entry
    134 type for the images in mkimage, but this would not add functionality. It
    135 seems better to use the mkiamge tool to generate binaries and avoid blurring
    136 the boundaries between building input files (mkimage) and packaging then
    137 into a final image (binman).
    138 
    139 
    140 Example use of binman in U-Boot
    141 -------------------------------
    142 
    143 Binman aims to replace some of the ad-hoc image creation in the U-Boot
    144 build system.
    145 
    146 Consider sunxi. It has the following steps:
    147 
    148 1. It uses a custom mksunxiboot tool to build an SPL image called
    149 sunxi-spl.bin. This should probably move into mkimage.
    150 
    151 2. It uses mkimage to package U-Boot into a legacy image file (so that it can
    152 hold the load and execution address) called u-boot.img.
    153 
    154 3. It builds a final output image called u-boot-sunxi-with-spl.bin which
    155 consists of sunxi-spl.bin, some padding and u-boot.img.
    156 
    157 Binman is intended to replace the last step. The U-Boot build system builds
    158 u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
    159 sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any
    160 case, it would then create the image from the component parts.
    161 
    162 This simplifies the U-Boot Makefile somewhat, since various pieces of logic
    163 can be replaced by a call to binman.
    164 
    165 
    166 Example use of binman for x86
    167 -----------------------------
    168 
    169 In most cases x86 images have a lot of binary blobs, 'black-box' code
    170 provided by Intel which must be run for the platform to work. Typically
    171 these blobs are not relocatable and must be placed at fixed areas in the
    172 firmare image.
    173 
    174 Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA
    175 BIOS, reference code and Intel ME binaries into a u-boot.rom file.
    176 
    177 Binman is intended to replace all of this, with ifdtool left to handle only
    178 the configuration of the Intel-format descriptor.
    179 
    180 
    181 Running binman
    182 --------------
    183 
    184 Type:
    185 
    186 	binman -b <board_name>
    187 
    188 to build an image for a board. The board name is the same name used when
    189 configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
    190 Binman assumes that the input files for the build are in ../b/<board_name>.
    191 
    192 Or you can specify this explicitly:
    193 
    194 	binman -I <build_path>
    195 
    196 where <build_path> is the build directory containing the output of the U-Boot
    197 build.
    198 
    199 (Future work will make this more configurable)
    200 
    201 In either case, binman picks up the device tree file (u-boot.dtb) and looks
    202 for its instructions in the 'binman' node.
    203 
    204 Binman has a few other options which you can see by running 'binman -h'.
    205 
    206 
    207 Enabling binman for a board
    208 ---------------------------
    209 
    210 At present binman is invoked from a rule in the main Makefile. Typically you
    211 will have a rule like:
    212 
    213 ifneq ($(CONFIG_ARCH_<something>),)
    214 u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
    215 	$(call if_changed,binman)
    216 endif
    217 
    218 This assumes that u-boot-<your_suffix>.bin is a target, and is the final file
    219 that you need to produce. You can make it a target by adding it to ALL-y
    220 either in the main Makefile or in a config.mk file in your arch subdirectory.
    221 
    222 Once binman is executed it will pick up its instructions from a device-tree
    223 file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value.
    224 You can use other, more specific CONFIG options - see 'Automatic .dtsi
    225 inclusion' below.
    226 
    227 
    228 Image description format
    229 ------------------------
    230 
    231 The binman node is called 'binman'. An example image description is shown
    232 below:
    233 
    234 	binman {
    235 		filename = "u-boot-sunxi-with-spl.bin";
    236 		pad-byte = <0xff>;
    237 		blob {
    238 			filename = "spl/sunxi-spl.bin";
    239 		};
    240 		u-boot {
    241 			pos = <CONFIG_SPL_PAD_TO>;
    242 		};
    243 	};
    244 
    245 
    246 This requests binman to create an image file called u-boot-sunxi-with-spl.bin
    247 consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the
    248 normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The
    249 padding comes from the fact that the second binary is placed at
    250 CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would
    251 immediately follow the SPL binary.
    252 
    253 The binman node describes an image. The sub-nodes describe entries in the
    254 image. Each entry represents a region within the overall image. The name of
    255 the entry (blob, u-boot) tells binman what to put there. For 'blob' we must
    256 provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'.
    257 
    258 Entries are normally placed into the image sequentially, one after the other.
    259 The image size is the total size of all entries. As you can see, you can
    260 specify the start position of an entry using the 'pos' property.
    261 
    262 Note that due to a device tree requirement, all entries must have a unique
    263 name. If you want to put the same binary in the image multiple times, you can
    264 use any unique name, with the 'type' property providing the type.
    265 
    266 The attributes supported for entries are described below.
    267 
    268 pos:
    269 	This sets the position of an entry within the image. The first byte
    270 	of the image is normally at position 0. If 'pos' is not provided,
    271 	binman sets it to the end of the previous region, or the start of
    272 	the image's entry area (normally 0) if there is no previous region.
    273 
    274 align:
    275 	This sets the alignment of the entry. The entry position is adjusted
    276 	so that the entry starts on an aligned boundary within the image. For
    277 	example 'align = <16>' means that the entry will start on a 16-byte
    278 	boundary. Alignment shold be a power of 2. If 'align' is not
    279 	provided, no alignment is performed.
    280 
    281 size:
    282 	This sets the size of the entry. The contents will be padded out to
    283 	this size. If this is not provided, it will be set to the size of the
    284 	contents.
    285 
    286 pad-before:
    287 	Padding before the contents of the entry. Normally this is 0, meaning
    288 	that the contents start at the beginning of the entry. This can be
    289 	offset the entry contents a little. Defaults to 0.
    290 
    291 pad-after:
    292 	Padding after the contents of the entry. Normally this is 0, meaning
    293 	that the entry ends at the last byte of content (unless adjusted by
    294 	other properties). This allows room to be created in the image for
    295 	this entry to expand later. Defaults to 0.
    296 
    297 align-size:
    298 	This sets the alignment of the entry size. For example, to ensure
    299 	that the size of an entry is a multiple of 64 bytes, set this to 64.
    300 	If 'align-size' is not provided, no alignment is performed.
    301 
    302 align-end:
    303 	This sets the alignment of the end of an entry. Some entries require
    304 	that they end on an alignment boundary, regardless of where they
    305 	start. This does not move the start of the entry, so the contents of
    306 	the entry will still start at the beginning. But there may be padding
    307 	at the end. If 'align-end' is not provided, no alignment is performed.
    308 
    309 filename:
    310 	For 'blob' types this provides the filename containing the binary to
    311 	put into the entry. If binman knows about the entry type (like
    312 	u-boot-bin), then there is no need to specify this.
    313 
    314 type:
    315 	Sets the type of an entry. This defaults to the entry name, but it is
    316 	possible to use any name, and then add (for example) 'type = "u-boot"'
    317 	to specify the type.
    318 
    319 pos-unset:
    320 	Indicates that the position of this entry should not be set by placing
    321 	it immediately after the entry before. Instead, is set by another
    322 	entry which knows where this entry should go. When this boolean
    323 	property is present, binman will give an error if another entry does
    324 	not set the position (with the GetPositions() method).
    325 
    326 
    327 The attributes supported for images are described below. Several are similar
    328 to those for entries.
    329 
    330 size:
    331 	Sets the image size in bytes, for example 'size = <0x100000>' for a
    332 	1MB image.
    333 
    334 align-size:
    335 	This sets the alignment of the image size. For example, to ensure
    336 	that the image ends on a 512-byte boundary, use 'align-size = <512>'.
    337 	If 'align-size' is not provided, no alignment is performed.
    338 
    339 pad-before:
    340 	This sets the padding before the image entries. The first entry will
    341 	be positionad after the padding. This defaults to 0.
    342 
    343 pad-after:
    344 	This sets the padding after the image entries. The padding will be
    345 	placed after the last entry. This defaults to 0.
    346 
    347 pad-byte:
    348 	This specifies the pad byte to use when padding in the image. It
    349 	defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
    350 
    351 filename:
    352 	This specifies the image filename. It defaults to 'image.bin'.
    353 
    354 sort-by-pos:
    355 	This causes binman to reorder the entries as needed to make sure they
    356 	are in increasing positional order. This can be used when your entry
    357 	order may not match the positional order. A common situation is where
    358 	the 'pos' properties are set by CONFIG options, so their ordering is
    359 	not known a priori.
    360 
    361 	This is a boolean property so needs no value. To enable it, add a
    362 	line 'sort-by-pos;' to your description.
    363 
    364 multiple-images:
    365 	Normally only a single image is generated. To create more than one
    366 	image, put this property in the binman node. For example, this will
    367 	create image1.bin containing u-boot.bin, and image2.bin containing
    368 	both spl/u-boot-spl.bin and u-boot.bin:
    369 
    370 	binman {
    371 		multiple-images;
    372 		image1 {
    373 			u-boot {
    374 			};
    375 		};
    376 
    377 		image2 {
    378 			spl {
    379 			};
    380 			u-boot {
    381 			};
    382 		};
    383 	};
    384 
    385 end-at-4gb:
    386 	For x86 machines the ROM positions start just before 4GB and extend
    387 	up so that the image finished at the 4GB boundary. This boolean
    388 	option can be enabled to support this. The image size must be
    389 	provided so that binman knows when the image should start. For an
    390 	8MB ROM, the position of the first entry would be 0xfff80000 with
    391 	this option, instead of 0 without this option.
    392 
    393 
    394 Examples of the above options can be found in the tests. See the
    395 tools/binman/test directory.
    396 
    397 It is possible to have the same binary appear multiple times in the image,
    398 either by using a unit number suffix (u-boot@0, u-boot@1) or by using a
    399 different name for each and specifying the type with the 'type' attribute.
    400 
    401 
    402 Sections and hiearchical images
    403 -------------------------------
    404 
    405 Sometimes it is convenient to split an image into several pieces, each of which
    406 contains its own set of binaries. An example is a flash device where part of
    407 the image is read-only and part is read-write. We can set up sections for each
    408 of these, and place binaries in them independently. The image is still produced
    409 as a single output file.
    410 
    411 This feature provides a way of creating hierarchical images. For example here
    412 is an example image with two copies of U-Boot. One is read-only (ro), intended
    413 to be written only in the factory. Another is read-write (rw), so that it can be
    414 upgraded in the field. The sizes are fixed so that the ro/rw boundary is known
    415 and can be programmed:
    416 
    417 	binman {
    418 		section@0 {
    419 			read-only;
    420 			name-prefix = "ro-";
    421 			size = <0x100000>;
    422 			u-boot {
    423 			};
    424 		};
    425 		section@1 {
    426 			name-prefix = "rw-";
    427 			size = <0x100000>;
    428 			u-boot {
    429 			};
    430 		};
    431 	};
    432 
    433 This image could be placed into a SPI flash chip, with the protection boundary
    434 set at 1MB.
    435 
    436 A few special properties are provided for sections:
    437 
    438 read-only:
    439 	Indicates that this section is read-only. This has no impact on binman's
    440 	operation, but his property can be read at run time.
    441 
    442 name-prefix:
    443 	This string is prepended to all the names of the binaries in the
    444 	section. In the example above, the 'u-boot' binaries which actually be
    445 	renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
    446 	distinguish binaries with otherwise identical names.
    447 
    448 
    449 Special properties
    450 ------------------
    451 
    452 Some entries support special properties, documented here:
    453 
    454 u-boot-with-ucode-ptr:
    455 	optional-ucode: boolean property to make microcode optional. If the
    456 		u-boot.bin image does not include microcode, no error will
    457 		be generated.
    458 
    459 
    460 Order of image creation
    461 -----------------------
    462 
    463 Image creation proceeds in the following order, for each entry in the image.
    464 
    465 1. GetEntryContents() - the contents of each entry are obtained, normally by
    466 reading from a file. This calls the Entry.ObtainContents() to read the
    467 contents. The default version of Entry.ObtainContents() calls
    468 Entry.GetDefaultFilename() and then reads that file. So a common mechanism
    469 to select a file to read is to override that function in the subclass. The
    470 functions must return True when they have read the contents. Binman will
    471 retry calling the functions a few times if False is returned, allowing
    472 dependencies between the contents of different entries.
    473 
    474 2. GetEntryPositions() - calls Entry.GetPositions() for each entry. This can
    475 return a dict containing entries that need updating. The key should be the
    476 entry name and the value is a tuple (pos, size). This allows an entry to
    477 provide the position and size for other entries. The default implementation
    478 of GetEntryPositions() returns {}.
    479 
    480 3. PackEntries() - calls Entry.Pack() which figures out the position and
    481 size of an entry. The 'current' image position is passed in, and the function
    482 returns the position immediately after the entry being packed. The default
    483 implementation of Pack() is usually sufficient.
    484 
    485 4. CheckSize() - checks that the contents of all the entries fits within
    486 the image size. If the image does not have a defined size, the size is set
    487 large enough to hold all the entries.
    488 
    489 5. CheckEntries() - checks that the entries do not overlap, nor extend
    490 outside the image.
    491 
    492 6. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
    493 The default implementatoin does nothing. This can be overriden to adjust the
    494 contents of an entry in some way. For example, it would be possible to create
    495 an entry containing a hash of the contents of some other entries. At this
    496 stage the position and size of entries should not be adjusted.
    497 
    498 6. WriteEntryInfo()
    499 
    500 7. BuildImage() - builds the image and writes it to a file. This is the final
    501 step.
    502 
    503 
    504 Automatic .dtsi inclusion
    505 -------------------------
    506 
    507 It is sometimes inconvenient to add a 'binman' node to the .dts file for each
    508 board. This can be done by using #include to bring in a common file. Another
    509 approach supported by the U-Boot build system is to automatically include
    510 a common header. You can then put the binman node (and anything else that is
    511 specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
    512 file.
    513 
    514 Binman will search for the following files in arch/<arch>/dts:
    515 
    516    <dts>-u-boot.dtsi where <dts> is the base name of the .dts file
    517    <CONFIG_SYS_SOC>-u-boot.dtsi
    518    <CONFIG_SYS_CPU>-u-boot.dtsi
    519    <CONFIG_SYS_VENDOR>-u-boot.dtsi
    520    u-boot.dtsi
    521 
    522 U-Boot will only use the first one that it finds. If you need to include a
    523 more general file you can do that from the more specific file using #include.
    524 If you are having trouble figuring out what is going on, you can uncomment
    525 the 'warning' line in scripts/Makefile.lib to see what it has found:
    526 
    527    # Uncomment for debugging
    528    # This shows all the files that were considered and the one that we chose.
    529    # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw)
    530 
    531 
    532 Access to binman entry positions at run time
    533 --------------------------------------------
    534 
    535 Binman assembles images and determines where each entry is placed in the image.
    536 This information may be useful to U-Boot at run time. For example, in SPL it
    537 is useful to be able to find the location of U-Boot so that it can be executed
    538 when SPL is finished.
    539 
    540 Binman allows you to declare symbols in the SPL image which are filled in
    541 with their correct values during the build. For example:
    542 
    543     binman_sym_declare(ulong, u_boot_any, pos);
    544 
    545 declares a ulong value which will be assigned to the position of any U-Boot
    546 image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
    547 You can access this value with something like:
    548 
    549     ulong u_boot_pos = binman_sym(ulong, u_boot_any, pos);
    550 
    551 Thus u_boot_pos will be set to the position of U-Boot in memory, assuming that
    552 the whole image has been loaded, or is available in flash. You can then jump to
    553 that address to start U-Boot.
    554 
    555 At present this feature is only supported in SPL. In principle it is possible
    556 to fill in such symbols in U-Boot proper, as well.
    557 
    558 
    559 Map files
    560 ---------
    561 
    562 The -m option causes binman to output a .map file for each image that it
    563 generates. This shows the position and size of each entry. For example:
    564 
    565     Position      Size  Name
    566     00000000  00000010  section@0
    567      00000000  00000004  u-boot
    568     00000010  00000010  section@1
    569      00000000  00000004  u-boot
    570 
    571 This shows a hierarchical image with two sections, each with a single entry. The
    572 positions of the sections are absolute hex byte offsets within the image. The
    573 positions of the entries are relative to their respective sections. The size of
    574 each entry is also shown, in bytes (hex). The indentation shows the entries
    575 nested inside their sections.
    576 
    577 
    578 Code coverage
    579 -------------
    580 
    581 Binman is a critical tool and is designed to be very testable. Entry
    582 implementations target 100% test coverage. Run 'binman -T' to check this.
    583 
    584 To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
    585 
    586    $ sudo apt-get install python-pip python-pytest
    587    $ sudo pip install coverage
    588 
    589 
    590 Advanced Features / Technical docs
    591 ----------------------------------
    592 
    593 The behaviour of entries is defined by the Entry class. All other entries are
    594 a subclass of this. An important subclass is Entry_blob which takes binary
    595 data from a file and places it in the entry. In fact most entry types are
    596 subclasses of Entry_blob.
    597 
    598 Each entry type is a separate file in the tools/binman/etype directory. Each
    599 file contains a class called Entry_<type> where <type> is the entry type.
    600 New entry types can be supported by adding new files in that directory.
    601 These will automatically be detected by binman when needed.
    602 
    603 Entry properties are documented in entry.py. The entry subclasses are free
    604 to change the values of properties to support special behaviour. For example,
    605 when Entry_blob loads a file, it sets content_size to the size of the file.
    606 Entry classes can adjust other entries. For example, an entry that knows
    607 where other entries should be positioned can set up those entries' positions
    608 so they don't need to be set in the binman decription. It can also adjust
    609 entry contents.
    610 
    611 Most of the time such essoteric behaviour is not needed, but it can be
    612 essential for complex images.
    613 
    614 If you need to specify a particular device-tree compiler to use, you can define
    615 the DTC environment variable. This can be useful when the system dtc is too
    616 old.
    617 
    618 
    619 History / Credits
    620 -----------------
    621 
    622 Binman takes a lot of inspiration from a Chrome OS tool called
    623 'cros_bundle_firmware', which I wrote some years ago. That tool was based on
    624 a reasonably simple and sound design but has expanded greatly over the
    625 years. In particular its handling of x86 images is convoluted.
    626 
    627 Quite a few lessons have been learned which are hopefully applied here.
    628 
    629 
    630 Design notes
    631 ------------
    632 
    633 On the face of it, a tool to create firmware images should be fairly simple:
    634 just find all the input binaries and place them at the right place in the
    635 image. The difficulty comes from the wide variety of input types (simple
    636 flat binaries containing code, packaged data with various headers), packing
    637 requirments (alignment, spacing, device boundaries) and other required
    638 features such as hierarchical images.
    639 
    640 The design challenge is to make it easy to create simple images, while
    641 allowing the more complex cases to be supported. For example, for most
    642 images we don't much care exactly where each binary ends up, so we should
    643 not have to specify that unnecessarily.
    644 
    645 New entry types should aim to provide simple usage where possible. If new
    646 core features are needed, they can be added in the Entry base class.
    647 
    648 
    649 To do
    650 -----
    651 
    652 Some ideas:
    653 - Fill out the device tree to include the final position and size of each
    654   entry (since the input file may not always specify these). See also
    655   'Access to binman entry positions at run time' above
    656 - Use of-platdata to make the information available to code that is unable
    657   to use device tree (such as a very small SPL image)
    658 - Allow easy building of images by specifying just the board name
    659 - Produce a full Python binding for libfdt (for upstream)
    660 - Add an option to decode an image into the constituent binaries
    661 - Support building an image for a board (-b) more completely, with a
    662   configurable build directory
    663 - Consider making binman work with buildman, although if it is used in the
    664   Makefile, this will be automatic
    665 
    666 --
    667 Simon Glass <sjg (a] chromium.org>
    668 7/7/2016
    669