blob: a6a3ee48aaf4e13d3c2a9909ba7d9381893c4f10 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001# SPDX-License-Identifier: GPL-2.0+
Simon Glassbf7fd502016-11-25 20:15:51 -07002# Copyright (c) 2016 Google, Inc
Simon Glassbf7fd502016-11-25 20:15:51 -07003
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
12So far U-Boot has not provided a way to handle creating such images in a
13general way. Each SoC does what it needs to build an image, often packing or
14concatenating images in the U-Boot build system.
15
16Binman aims to provide a mechanism for building images, from simple
17SPL + U-Boot combinations, to more complex arrangements with many parts.
18
19
20What it does
21------------
22
23Binman reads your board's device tree and finds a node which describes the
24required image layout. It uses this to work out what to place where. The
25output file normally contains the device tree, so it is in principle possible
26to read an image and extract its constituent parts.
27
28
29Features
30--------
31
32So 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
34place entries at a fixed location in the image, or fit them together with
35suitable padding and alignment. It provides a way to process binaries before
36they are included, by adding a Python plug-in. The device tree is available
37to U-Boot at run-time so that the images can be interpreted.
38
Simon Glass57460182019-07-08 14:25:25 -060039Binman can update the device tree with the final location of everything when it
40is done. Entry positions can be provided to U-Boot SPL as run-time symbols,
41avoiding device-tree code overhead.
Simon Glassbf7fd502016-11-25 20:15:51 -070042
43Binman can also support incorporating filesystems in the image if required.
44For example x86 platforms may use CBFS in some cases.
45
46Binman is intended for use with U-Boot but is designed to be general enough
47to be useful in other image-packaging situations.
48
49
50Motivation
51----------
52
53Packaging of firmware is quite a different task from building the various
54parts. In many cases the various binaries which go into the image come from
55separate build systems. For example, ARM Trusted Firmware is used on ARMv8
56devices but is not built in the U-Boot tree. If a Linux kernel is included
57in the firmware image, it is built elsewhere.
58
59It is of course possible to add more and more build rules to the U-Boot
60build system to cover these cases. It can shell out to other Makefiles and
61build scripts. But it seems better to create a clear divide between building
62software and packaging it.
63
64At present this is handled by manual instructions, different for each board,
65on how to create images that will boot. By turning these instructions into a
66standard format, we can support making valid images for any board without
67manual effort, lots of READMEs, etc.
68
69Benefits:
70- Each binary can have its own build system and tool chain without creating
71any dependencies between them
72- Avoids the need for a single-shot build: individual parts can be updated
73and brought in as needed
74- Provides for a standard image description available in the build and at
75run-time
Thomas Hebb32f2ca22019-11-13 18:18:03 -080076- SoC-specific image-signing tools can be accommodated
Simon Glassbf7fd502016-11-25 20:15:51 -070077- Avoids cluttering the U-Boot build system with image-building code
78- The image description is automatically available at run-time in U-Boot,
79SPL. It can be made available to other software also
80- The image description is easily readable (it's a text file in device-tree
81format) and permits flexible packing of binaries
82
83
84Terminology
85-----------
86
87Binman uses the following terms:
88
89- image - an output file containing a firmware image
90- binary - an input binary that goes into the image
91
92
93Relationship to FIT
94-------------------
95
96FIT is U-Boot's official image format. It supports multiple binaries with
97load / execution addresses, compression. It also supports verification
98through hashing and RSA signatures.
99
100FIT was originally designed to support booting a Linux kernel (with an
101optional ramdisk) and device tree chosen from various options in the FIT.
102Now that U-Boot supports configuration via device tree, it is possible to
103load U-Boot from a FIT, with the device tree chosen by SPL.
104
105Binman considers FIT to be one of the binaries it can place in the image.
106
107Where possible it is best to put as much as possible in the FIT, with binman
108used to deal with cases not covered by FIT. Examples include initial
109execution (since FIT itself does not have an executable header) and dealing
110with device boundaries, such as the read-only/read-write separation in SPI
111flash.
112
113For U-Boot, binman should not be used to create ad-hoc images in place of
114FIT.
115
116
117Relationship to mkimage
118-----------------------
119
120The mkimage tool provides a means to create a FIT. Traditionally it has
121needed an image description file: a device tree, like binman, but in a
122different format. More recently it has started to support a '-f auto' mode
123which can generate that automatically.
124
125More relevant to binman, mkimage also permits creation of many SoC-specific
126image types. These can be listed by running 'mkimage -T list'. Examples
127include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often
128called from the U-Boot build system for this reason.
129
130Binman considers the output files created by mkimage to be binary blobs
131which it can place in an image. Binman does not replace the mkimage tool or
Michael Heimpold383d2562018-08-22 22:01:24 +0200132this purpose. It would be possible in some situations to create a new entry
Simon Glassbf7fd502016-11-25 20:15:51 -0700133type for the images in mkimage, but this would not add functionality. It
Michael Heimpold383d2562018-08-22 22:01:24 +0200134seems better to use the mkimage tool to generate binaries and avoid blurring
Simon Glassbf7fd502016-11-25 20:15:51 -0700135the boundaries between building input files (mkimage) and packaging then
136into a final image (binman).
137
138
139Example use of binman in U-Boot
140-------------------------------
141
142Binman aims to replace some of the ad-hoc image creation in the U-Boot
143build system.
144
145Consider sunxi. It has the following steps:
146
1471. It uses a custom mksunxiboot tool to build an SPL image called
148sunxi-spl.bin. This should probably move into mkimage.
149
1502. It uses mkimage to package U-Boot into a legacy image file (so that it can
151hold the load and execution address) called u-boot.img.
152
1533. It builds a final output image called u-boot-sunxi-with-spl.bin which
154consists of sunxi-spl.bin, some padding and u-boot.img.
155
156Binman is intended to replace the last step. The U-Boot build system builds
157u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
158sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any
159case, it would then create the image from the component parts.
160
161This simplifies the U-Boot Makefile somewhat, since various pieces of logic
162can be replaced by a call to binman.
163
164
165Example use of binman for x86
166-----------------------------
167
168In most cases x86 images have a lot of binary blobs, 'black-box' code
169provided by Intel which must be run for the platform to work. Typically
170these blobs are not relocatable and must be placed at fixed areas in the
Michael Heimpold383d2562018-08-22 22:01:24 +0200171firmware image.
Simon Glassbf7fd502016-11-25 20:15:51 -0700172
173Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA
174BIOS, reference code and Intel ME binaries into a u-boot.rom file.
175
176Binman is intended to replace all of this, with ifdtool left to handle only
177the configuration of the Intel-format descriptor.
178
179
180Running binman
181--------------
182
Simon Glassd8d40742019-07-08 13:18:35 -0600183First install prerequisites, e.g.
184
Simon Glass07d9e702019-07-08 13:18:41 -0600185 sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
186 liblz4-tool
Simon Glassd8d40742019-07-08 13:18:35 -0600187
Simon Glassbf7fd502016-11-25 20:15:51 -0700188Type:
189
Simon Glass53cd5d92019-07-08 14:25:29 -0600190 binman build -b <board_name>
Simon Glassbf7fd502016-11-25 20:15:51 -0700191
192to build an image for a board. The board name is the same name used when
193configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
194Binman assumes that the input files for the build are in ../b/<board_name>.
195
196Or you can specify this explicitly:
197
Simon Glass53cd5d92019-07-08 14:25:29 -0600198 binman build -I <build_path>
Simon Glassbf7fd502016-11-25 20:15:51 -0700199
200where <build_path> is the build directory containing the output of the U-Boot
201build.
202
203(Future work will make this more configurable)
204
205In either case, binman picks up the device tree file (u-boot.dtb) and looks
206for its instructions in the 'binman' node.
207
208Binman has a few other options which you can see by running 'binman -h'.
209
210
Simon Glass9c0a8b12017-11-12 21:52:06 -0700211Enabling binman for a board
212---------------------------
213
214At present binman is invoked from a rule in the main Makefile. Typically you
215will have a rule like:
216
217ifneq ($(CONFIG_ARCH_<something>),)
218u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
219 $(call if_changed,binman)
220endif
221
222This assumes that u-boot-<your_suffix>.bin is a target, and is the final file
223that you need to produce. You can make it a target by adding it to ALL-y
224either in the main Makefile or in a config.mk file in your arch subdirectory.
225
226Once binman is executed it will pick up its instructions from a device-tree
227file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value.
228You can use other, more specific CONFIG options - see 'Automatic .dtsi
229inclusion' below.
230
231
Simon Glassbf7fd502016-11-25 20:15:51 -0700232Image description format
233------------------------
234
235The binman node is called 'binman'. An example image description is shown
236below:
237
238 binman {
239 filename = "u-boot-sunxi-with-spl.bin";
240 pad-byte = <0xff>;
241 blob {
242 filename = "spl/sunxi-spl.bin";
243 };
244 u-boot {
Simon Glass3ab95982018-08-01 15:22:37 -0600245 offset = <CONFIG_SPL_PAD_TO>;
Simon Glassbf7fd502016-11-25 20:15:51 -0700246 };
247 };
248
249
250This requests binman to create an image file called u-boot-sunxi-with-spl.bin
251consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the
252normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The
253padding comes from the fact that the second binary is placed at
254CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would
255immediately follow the SPL binary.
256
257The binman node describes an image. The sub-nodes describe entries in the
258image. Each entry represents a region within the overall image. The name of
259the entry (blob, u-boot) tells binman what to put there. For 'blob' we must
260provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'.
261
262Entries are normally placed into the image sequentially, one after the other.
263The image size is the total size of all entries. As you can see, you can
Simon Glass3ab95982018-08-01 15:22:37 -0600264specify the start offset of an entry using the 'offset' property.
Simon Glassbf7fd502016-11-25 20:15:51 -0700265
266Note that due to a device tree requirement, all entries must have a unique
267name. If you want to put the same binary in the image multiple times, you can
268use any unique name, with the 'type' property providing the type.
269
270The attributes supported for entries are described below.
271
Simon Glass3ab95982018-08-01 15:22:37 -0600272offset:
273 This sets the offset of an entry within the image or section containing
274 it. The first byte of the image is normally at offset 0. If 'offset' is
275 not provided, binman sets it to the end of the previous region, or the
276 start of the image's entry area (normally 0) if there is no previous
277 region.
Simon Glassbf7fd502016-11-25 20:15:51 -0700278
279align:
Simon Glass3ab95982018-08-01 15:22:37 -0600280 This sets the alignment of the entry. The entry offset is adjusted
Simon Glassbf7fd502016-11-25 20:15:51 -0700281 so that the entry starts on an aligned boundary within the image. For
282 example 'align = <16>' means that the entry will start on a 16-byte
283 boundary. Alignment shold be a power of 2. If 'align' is not
284 provided, no alignment is performed.
285
286size:
287 This sets the size of the entry. The contents will be padded out to
288 this size. If this is not provided, it will be set to the size of the
289 contents.
290
291pad-before:
292 Padding before the contents of the entry. Normally this is 0, meaning
293 that the contents start at the beginning of the entry. This can be
294 offset the entry contents a little. Defaults to 0.
295
296pad-after:
297 Padding after the contents of the entry. Normally this is 0, meaning
298 that the entry ends at the last byte of content (unless adjusted by
299 other properties). This allows room to be created in the image for
300 this entry to expand later. Defaults to 0.
301
302align-size:
303 This sets the alignment of the entry size. For example, to ensure
304 that the size of an entry is a multiple of 64 bytes, set this to 64.
305 If 'align-size' is not provided, no alignment is performed.
306
307align-end:
308 This sets the alignment of the end of an entry. Some entries require
309 that they end on an alignment boundary, regardless of where they
Simon Glass844e5b22018-06-01 09:38:22 -0600310 start. This does not move the start of the entry, so the contents of
311 the entry will still start at the beginning. But there may be padding
312 at the end. If 'align-end' is not provided, no alignment is performed.
Simon Glassbf7fd502016-11-25 20:15:51 -0700313
314filename:
315 For 'blob' types this provides the filename containing the binary to
316 put into the entry. If binman knows about the entry type (like
317 u-boot-bin), then there is no need to specify this.
318
319type:
320 Sets the type of an entry. This defaults to the entry name, but it is
321 possible to use any name, and then add (for example) 'type = "u-boot"'
322 to specify the type.
323
Simon Glass3ab95982018-08-01 15:22:37 -0600324offset-unset:
325 Indicates that the offset of this entry should not be set by placing
Simon Glass258fb0e2018-06-01 09:38:17 -0600326 it immediately after the entry before. Instead, is set by another
327 entry which knows where this entry should go. When this boolean
328 property is present, binman will give an error if another entry does
Simon Glass3ab95982018-08-01 15:22:37 -0600329 not set the offset (with the GetOffsets() method).
Simon Glass258fb0e2018-06-01 09:38:17 -0600330
Simon Glassdbf6be92018-08-01 15:22:42 -0600331image-pos:
332 This cannot be set on entry (or at least it is ignored if it is), but
333 with the -u option, binman will set it to the absolute image position
334 for each entry. This makes it easy to find out exactly where the entry
335 ended up in the image, regardless of parent sections, etc.
336
Simon Glassba64a0b2018-09-14 04:57:29 -0600337expand-size:
338 Expand the size of this entry to fit available space. This space is only
339 limited by the size of the image/section and the position of the next
340 entry.
Simon Glassbf7fd502016-11-25 20:15:51 -0700341
Simon Glass8287ee82019-07-08 14:25:30 -0600342compress:
343 Sets the compression algortihm to use (for blobs only). See the entry
344 documentation for details.
345
Simon Glass9c888cc2018-09-14 04:57:30 -0600346The attributes supported for images and sections are described below. Several
347are similar to those for entries.
Simon Glassbf7fd502016-11-25 20:15:51 -0700348
349size:
350 Sets the image size in bytes, for example 'size = <0x100000>' for a
351 1MB image.
352
Simon Glass9481c802019-04-25 21:58:39 -0600353offset:
354 This is similar to 'offset' in entries, setting the offset of a section
355 within the image or section containing it. The first byte of the section
356 is normally at offset 0. If 'offset' is not provided, binman sets it to
357 the end of the previous region, or the start of the image's entry area
358 (normally 0) if there is no previous region.
359
Simon Glassbf7fd502016-11-25 20:15:51 -0700360align-size:
361 This sets the alignment of the image size. For example, to ensure
362 that the image ends on a 512-byte boundary, use 'align-size = <512>'.
363 If 'align-size' is not provided, no alignment is performed.
364
365pad-before:
366 This sets the padding before the image entries. The first entry will
Simon Glass3ab95982018-08-01 15:22:37 -0600367 be positioned after the padding. This defaults to 0.
Simon Glassbf7fd502016-11-25 20:15:51 -0700368
369pad-after:
370 This sets the padding after the image entries. The padding will be
371 placed after the last entry. This defaults to 0.
372
373pad-byte:
374 This specifies the pad byte to use when padding in the image. It
375 defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
376
377filename:
378 This specifies the image filename. It defaults to 'image.bin'.
379
Simon Glass3ab95982018-08-01 15:22:37 -0600380sort-by-offset:
Simon Glassbf7fd502016-11-25 20:15:51 -0700381 This causes binman to reorder the entries as needed to make sure they
382 are in increasing positional order. This can be used when your entry
383 order may not match the positional order. A common situation is where
Simon Glass3ab95982018-08-01 15:22:37 -0600384 the 'offset' properties are set by CONFIG options, so their ordering is
Simon Glassbf7fd502016-11-25 20:15:51 -0700385 not known a priori.
386
387 This is a boolean property so needs no value. To enable it, add a
Simon Glass3ab95982018-08-01 15:22:37 -0600388 line 'sort-by-offset;' to your description.
Simon Glassbf7fd502016-11-25 20:15:51 -0700389
390multiple-images:
391 Normally only a single image is generated. To create more than one
392 image, put this property in the binman node. For example, this will
393 create image1.bin containing u-boot.bin, and image2.bin containing
394 both spl/u-boot-spl.bin and u-boot.bin:
395
396 binman {
397 multiple-images;
398 image1 {
399 u-boot {
400 };
401 };
402
403 image2 {
404 spl {
405 };
406 u-boot {
407 };
408 };
409 };
410
411end-at-4gb:
Simon Glass3ab95982018-08-01 15:22:37 -0600412 For x86 machines the ROM offsets start just before 4GB and extend
Simon Glassbf7fd502016-11-25 20:15:51 -0700413 up so that the image finished at the 4GB boundary. This boolean
414 option can be enabled to support this. The image size must be
415 provided so that binman knows when the image should start. For an
Simon Glass3ab95982018-08-01 15:22:37 -0600416 8MB ROM, the offset of the first entry would be 0xfff80000 with
Simon Glassbf7fd502016-11-25 20:15:51 -0700417 this option, instead of 0 without this option.
418
Jagdish Gediya94b57db2018-09-03 21:35:07 +0530419skip-at-start:
420 This property specifies the entry offset of the first entry.
421
422 For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry
423 offset of the first entry. It can be 0xeff40000 or 0xfff40000 for
424 nor flash boot, 0x201000 for sd boot etc.
425
426 'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
427 Image size != 4gb.
Simon Glassbf7fd502016-11-25 20:15:51 -0700428
429Examples of the above options can be found in the tests. See the
430tools/binman/test directory.
431
Simon Glassdd57c132018-06-01 09:38:11 -0600432It is possible to have the same binary appear multiple times in the image,
433either by using a unit number suffix (u-boot@0, u-boot@1) or by using a
434different name for each and specifying the type with the 'type' attribute.
435
Simon Glassbf7fd502016-11-25 20:15:51 -0700436
Michael Heimpold383d2562018-08-22 22:01:24 +0200437Sections and hierachical images
Simon Glass18546952018-06-01 09:38:16 -0600438-------------------------------
439
440Sometimes it is convenient to split an image into several pieces, each of which
441contains its own set of binaries. An example is a flash device where part of
442the image is read-only and part is read-write. We can set up sections for each
443of these, and place binaries in them independently. The image is still produced
444as a single output file.
445
446This feature provides a way of creating hierarchical images. For example here
Simon Glass7ae5f312018-06-01 09:38:19 -0600447is an example image with two copies of U-Boot. One is read-only (ro), intended
448to be written only in the factory. Another is read-write (rw), so that it can be
Simon Glass18546952018-06-01 09:38:16 -0600449upgraded in the field. The sizes are fixed so that the ro/rw boundary is known
450and can be programmed:
451
452 binman {
453 section@0 {
454 read-only;
Simon Glassc8d48ef2018-06-01 09:38:21 -0600455 name-prefix = "ro-";
Simon Glass18546952018-06-01 09:38:16 -0600456 size = <0x100000>;
457 u-boot {
458 };
459 };
460 section@1 {
Simon Glassc8d48ef2018-06-01 09:38:21 -0600461 name-prefix = "rw-";
Simon Glass18546952018-06-01 09:38:16 -0600462 size = <0x100000>;
463 u-boot {
464 };
465 };
466 };
467
468This image could be placed into a SPI flash chip, with the protection boundary
469set at 1MB.
470
471A few special properties are provided for sections:
472
473read-only:
474 Indicates that this section is read-only. This has no impact on binman's
475 operation, but his property can be read at run time.
476
Simon Glassc8d48ef2018-06-01 09:38:21 -0600477name-prefix:
478 This string is prepended to all the names of the binaries in the
479 section. In the example above, the 'u-boot' binaries which actually be
480 renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
481 distinguish binaries with otherwise identical names.
482
Simon Glass18546952018-06-01 09:38:16 -0600483
Simon Glass12bb1a92019-07-20 12:23:51 -0600484Image Properties
485----------------
486
487Image nodes act like sections but also have a few extra properties:
488
489filename:
490 Output filename for the image. This defaults to image.bin (or in the
491 case of multiple images <nodename>.bin where <nodename> is the name of
492 the image node.
493
494allow-repack:
495 Create an image that can be repacked. With this option it is possible
496 to change anything in the image after it is created, including updating
497 the position and size of image components. By default this is not
498 permitted since it is not possibly to know whether this might violate a
499 constraint in the image description. For example, if a section has to
500 increase in size to hold a larger binary, that might cause the section
501 to fall out of its allow region (e.g. read-only portion of flash).
502
503 Adding this property causes the original offset and size values in the
504 image description to be stored in the FDT and fdtmap.
505
506
Simon Glass5a5da7c2018-07-17 13:25:37 -0600507Entry Documentation
508-------------------
509
510For details on the various entry types supported by binman and how to use them,
511see README.entries. This is generated from the source code using:
512
Simon Glass53cd5d92019-07-08 14:25:29 -0600513 binman entry-docs >tools/binman/README.entries
Simon Glass5a5da7c2018-07-17 13:25:37 -0600514
515
Simon Glass61f564d2019-07-08 14:25:48 -0600516Listing images
517--------------
518
519It is possible to list the entries in an existing firmware image created by
520binman, provided that there is an 'fdtmap' entry in the image. For example:
521
522 $ binman ls -i image.bin
523 Name Image-pos Size Entry-type Offset Uncomp-size
524 ----------------------------------------------------------------------
525 main-section c00 section 0
526 u-boot 0 4 u-boot 0
527 section 5fc section 4
528 cbfs 100 400 cbfs 0
529 u-boot 138 4 u-boot 38
530 u-boot-dtb 180 108 u-boot-dtb 80 3b5
531 u-boot-dtb 500 1ff u-boot-dtb 400 3b5
532 fdtmap 6fc 381 fdtmap 6fc
533 image-header bf8 8 image-header bf8
534
535This shows the hierarchy of the image, the position, size and type of each
536entry, the offset of each entry within its parent and the uncompressed size if
537the entry is compressed.
538
539It is also possible to list just some files in an image, e.g.
540
541 $ binman ls -i image.bin section/cbfs
542 Name Image-pos Size Entry-type Offset Uncomp-size
543 --------------------------------------------------------------------
544 cbfs 100 400 cbfs 0
545 u-boot 138 4 u-boot 38
546 u-boot-dtb 180 108 u-boot-dtb 80 3b5
547
548or with wildcards:
549
550 $ binman ls -i image.bin "*cb*" "*head*"
551 Name Image-pos Size Entry-type Offset Uncomp-size
552 ----------------------------------------------------------------------
553 cbfs 100 400 cbfs 0
554 u-boot 138 4 u-boot 38
555 u-boot-dtb 180 108 u-boot-dtb 80 3b5
556 image-header bf8 8 image-header bf8
557
558
Simon Glass71ce0ba2019-07-08 14:25:52 -0600559Extracting files from images
560----------------------------
561
562You can extract files from an existing firmware image created by binman,
563provided that there is an 'fdtmap' entry in the image. For example:
564
565 $ binman extract -i image.bin section/cbfs/u-boot
566
567which will write the uncompressed contents of that entry to the file 'u-boot' in
568the current directory. You can also extract to a particular file, in this case
569u-boot.bin:
570
571 $ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin
572
573It is possible to extract all files into a destination directory, which will
574put files in subdirectories matching the entry hierarchy:
575
576 $ binman extract -i image.bin -O outdir
577
578or just a selection:
579
580 $ binman extract -i image.bin "*u-boot*" -O outdir
581
582
Simon Glass10f9d002019-07-20 12:23:50 -0600583Replacing files in an image
584---------------------------
585
586You can replace files in an existing firmware image created by binman, provided
587that there is an 'fdtmap' entry in the image. For example:
588
589 $ binman replace -i image.bin section/cbfs/u-boot
590
591which will write the contents of the file 'u-boot' from the current directory
Simon Glassa6cb9952019-07-20 12:24:15 -0600592to the that entry, compressing if necessary. If the entry size changes, you must
593add the 'allow-repack' property to the original image before generating it (see
594above), otherwise you will get an error.
595
596You can also use a particular file, in this case u-boot.bin:
597
598 $ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin
599
600It is possible to replace all files from a source directory which uses the same
601hierarchy as the entries:
602
603 $ binman replace -i image.bin -I indir
604
605Files that are missing will generate a warning.
606
607You can also replace just a selection of entries:
608
609 $ binman replace -i image.bin "*u-boot*" -I indir
Simon Glass10f9d002019-07-20 12:23:50 -0600610
611
Simon Glasseea264e2019-07-08 14:25:49 -0600612Logging
613-------
614
615Binman normally operates silently unless there is an error, in which case it
616just displays the error. The -D/--debug option can be used to create a full
617backtrace when errors occur.
618
619Internally binman logs some output while it is running. This can be displayed
620by increasing the -v/--verbosity from the default of 1:
621
622 0: silent
623 1: warnings only
624 2: notices (important messages)
625 3: info about major operations
626 4: detailed information about each operation
627 5: debug (all output)
628
629
Simon Glasse0e5df92018-09-14 04:57:31 -0600630Hashing Entries
631---------------
Simon Glasse0ff8552016-11-25 20:15:53 -0700632
Simon Glasse0e5df92018-09-14 04:57:31 -0600633It is possible to ask binman to hash the contents of an entry and write that
634value back to the device-tree node. For example:
Simon Glasse0ff8552016-11-25 20:15:53 -0700635
Simon Glasse0e5df92018-09-14 04:57:31 -0600636 binman {
637 u-boot {
638 hash {
639 algo = "sha256";
640 };
641 };
642 };
643
644Here, a new 'value' property will be written to the 'hash' node containing
645the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole
646sections can be hased if desired, by adding the 'hash' node to the section.
647
648The has value can be chcked at runtime by hashing the data actually read and
649comparing this has to the value in the device tree.
Simon Glasse0ff8552016-11-25 20:15:53 -0700650
651
Simon Glassbf7fd502016-11-25 20:15:51 -0700652Order of image creation
653-----------------------
654
655Image creation proceeds in the following order, for each entry in the image.
656
Simon Glass078ab1a2018-07-06 10:27:41 -06006571. AddMissingProperties() - binman can add calculated values to the device
Simon Glass3ab95982018-08-01 15:22:37 -0600658tree as part of its processing, for example the offset and size of each
Simon Glass078ab1a2018-07-06 10:27:41 -0600659entry. This method adds any properties associated with this, expanding the
660device tree as needed. These properties can have placeholder values which are
661set later by SetCalculatedProperties(). By that stage the size of sections
662cannot be changed (since it would cause the images to need to be repacked),
663but the correct values can be inserted.
664
6652. ProcessFdt() - process the device tree information as required by the
Simon Glassecab8972018-07-06 10:27:40 -0600666particular entry. This may involve adding or deleting properties. If the
667processing is complete, this method should return True. If the processing
668cannot complete because it needs the ProcessFdt() method of another entry to
669run first, this method should return False, in which case it will be called
670again later.
671
Simon Glass078ab1a2018-07-06 10:27:41 -06006723. GetEntryContents() - the contents of each entry are obtained, normally by
Simon Glassbf7fd502016-11-25 20:15:51 -0700673reading from a file. This calls the Entry.ObtainContents() to read the
674contents. The default version of Entry.ObtainContents() calls
675Entry.GetDefaultFilename() and then reads that file. So a common mechanism
676to select a file to read is to override that function in the subclass. The
677functions must return True when they have read the contents. Binman will
678retry calling the functions a few times if False is returned, allowing
679dependencies between the contents of different entries.
680
Simon Glass3ab95982018-08-01 15:22:37 -06006814. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can
Simon Glassbf7fd502016-11-25 20:15:51 -0700682return a dict containing entries that need updating. The key should be the
Simon Glass3ab95982018-08-01 15:22:37 -0600683entry name and the value is a tuple (offset, size). This allows an entry to
684provide the offset and size for other entries. The default implementation
685of GetEntryOffsets() returns {}.
Simon Glassbf7fd502016-11-25 20:15:51 -0700686
Simon Glass3ab95982018-08-01 15:22:37 -06006875. PackEntries() - calls Entry.Pack() which figures out the offset and
688size of an entry. The 'current' image offset is passed in, and the function
689returns the offset immediately after the entry being packed. The default
Simon Glassbf7fd502016-11-25 20:15:51 -0700690implementation of Pack() is usually sufficient.
691
Simon Glass078ab1a2018-07-06 10:27:41 -06006926. CheckSize() - checks that the contents of all the entries fits within
Simon Glassbf7fd502016-11-25 20:15:51 -0700693the image size. If the image does not have a defined size, the size is set
694large enough to hold all the entries.
695
Simon Glass078ab1a2018-07-06 10:27:41 -06006967. CheckEntries() - checks that the entries do not overlap, nor extend
Simon Glassbf7fd502016-11-25 20:15:51 -0700697outside the image.
698
Simon Glass4ab88b62019-07-20 12:23:52 -06006998. SetImagePos() - sets the image position of every entry. This is the absolute
700position 'image-pos', as opposed to 'offset' which is relative to the containing
701section. This must be done after all offsets are known, which is why it is quite
702late in the ordering.
703
7049. SetCalculatedProperties() - update any calculated properties in the device
Simon Glass3ab95982018-08-01 15:22:37 -0600705tree. This sets the correct 'offset' and 'size' vaues, for example.
Simon Glass078ab1a2018-07-06 10:27:41 -0600706
Simon Glass4ab88b62019-07-20 12:23:52 -060070710. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
Simon Glassbf7fd502016-11-25 20:15:51 -0700708The default implementatoin does nothing. This can be overriden to adjust the
709contents of an entry in some way. For example, it would be possible to create
710an entry containing a hash of the contents of some other entries. At this
Simon Glassc52c9e72019-07-08 14:25:37 -0600711stage the offset and size of entries should not be adjusted unless absolutely
712necessary, since it requires a repack (going back to PackEntries()).
Simon Glassbf7fd502016-11-25 20:15:51 -0700713
Simon Glass4ab88b62019-07-20 12:23:52 -060071411. ResetForPack() - if the ProcessEntryContents() step failed, in that an entry
715has changed its size, then there is no alternative but to go back to step 5 and
716try again, repacking the entries with the updated size. ResetForPack() removes
717the fixed offset/size values added by binman, so that the packing can start from
718scratch.
719
72012. WriteSymbols() - write the value of symbols into the U-Boot SPL binary.
Simon Glass3ab95982018-08-01 15:22:37 -0600721See 'Access to binman entry offsets at run time' below for a description of
Simon Glass0a4357c2018-07-06 10:27:39 -0600722what happens in this stage.
Simon Glass39c15022017-11-13 18:55:05 -0700723
Simon Glass4ab88b62019-07-20 12:23:52 -060072413. BuildImage() - builds the image and writes it to a file
725
72614. WriteMap() - writes a text file containing a map of the image. This is the
727final step.
Simon Glassbf7fd502016-11-25 20:15:51 -0700728
729
Simon Glass6d427c62016-11-25 20:15:59 -0700730Automatic .dtsi inclusion
731-------------------------
732
733It is sometimes inconvenient to add a 'binman' node to the .dts file for each
734board. This can be done by using #include to bring in a common file. Another
735approach supported by the U-Boot build system is to automatically include
736a common header. You can then put the binman node (and anything else that is
737specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
738file.
739
740Binman will search for the following files in arch/<arch>/dts:
741
742 <dts>-u-boot.dtsi where <dts> is the base name of the .dts file
743 <CONFIG_SYS_SOC>-u-boot.dtsi
744 <CONFIG_SYS_CPU>-u-boot.dtsi
745 <CONFIG_SYS_VENDOR>-u-boot.dtsi
746 u-boot.dtsi
747
748U-Boot will only use the first one that it finds. If you need to include a
749more general file you can do that from the more specific file using #include.
750If you are having trouble figuring out what is going on, you can uncomment
751the 'warning' line in scripts/Makefile.lib to see what it has found:
752
753 # Uncomment for debugging
Simon Glass511fd0b2017-11-12 21:52:05 -0700754 # This shows all the files that were considered and the one that we chose.
755 # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw)
Simon Glass6d427c62016-11-25 20:15:59 -0700756
757
Simon Glassdbf6be92018-08-01 15:22:42 -0600758Access to binman entry offsets at run time (symbols)
759----------------------------------------------------
Simon Glass39c15022017-11-13 18:55:05 -0700760
761Binman assembles images and determines where each entry is placed in the image.
762This information may be useful to U-Boot at run time. For example, in SPL it
763is useful to be able to find the location of U-Boot so that it can be executed
764when SPL is finished.
765
766Binman allows you to declare symbols in the SPL image which are filled in
767with their correct values during the build. For example:
768
Simon Glass7c150132019-11-06 17:22:44 -0700769 binman_sym_declare(ulong, u_boot_any, image_pos);
Simon Glass39c15022017-11-13 18:55:05 -0700770
Simon Glass7c150132019-11-06 17:22:44 -0700771declares a ulong value which will be assigned to the image-pos of any U-Boot
Simon Glass39c15022017-11-13 18:55:05 -0700772image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
773You can access this value with something like:
774
Simon Glass7c150132019-11-06 17:22:44 -0700775 ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos);
Simon Glass39c15022017-11-13 18:55:05 -0700776
Simon Glass7c150132019-11-06 17:22:44 -0700777Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming
778that the whole image has been loaded, or is available in flash. You can then
779jump to that address to start U-Boot.
Simon Glass39c15022017-11-13 18:55:05 -0700780
Simon Glass7c150132019-11-06 17:22:44 -0700781At present this feature is only supported in SPL and TPL. In principle it is
782possible to fill in such symbols in U-Boot proper, as well, but a future C
783library is planned for this instead, to read from the device tree.
784
785As well as image-pos, it is possible to read the size of an entry and its
786offset (which is the start position of the entry within its parent).
787
788A small technical note: Binman automatically adds the base address of the image
789(i.e. __image_copy_start) to the value of the image-pos symbol, so that when the
790image is loaded to its linked address, the value will be correct and actually
791point into the image.
792
793For example, say SPL is at the start of the image and linked to start at address
79480108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos
795for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded
796to 80108000, with SPL at 80108000 and U-Boot at 80110000.
797
798For x86 devices (with the end-at-4gb property) this base address is not added
799since it is assumed that images are XIP and the offsets already include the
800address.
Simon Glass39c15022017-11-13 18:55:05 -0700801
802
Simon Glassdbf6be92018-08-01 15:22:42 -0600803Access to binman entry offsets at run time (fdt)
804------------------------------------------------
805
806Binman can update the U-Boot FDT to include the final position and size of
807each entry in the images it processes. The option to enable this is -u and it
808causes binman to make sure that the 'offset', 'image-pos' and 'size' properties
809are set correctly for every entry. Since it is not necessary to specify these in
810the image definition, binman calculates the final values and writes these to
811the device tree. These can be used by U-Boot at run-time to find the location
812of each entry.
813
Simon Glass086cec92019-07-08 14:25:27 -0600814Alternatively, an FDT map entry can be used to add a special FDT containing
815just the information about the image. This is preceded by a magic string so can
Simon Glasscf228942019-07-08 14:25:28 -0600816be located anywhere in the image. An image header (typically at the start or end
817of the image) can be used to point to the FDT map. See fdtmap and image-header
818entries for more information.
Simon Glass086cec92019-07-08 14:25:27 -0600819
Simon Glassdbf6be92018-08-01 15:22:42 -0600820
Simon Glass83d73c22018-09-14 04:57:26 -0600821Compression
822-----------
823
824Binman support compression for 'blob' entries (those of type 'blob' and
Simon Glass8287ee82019-07-08 14:25:30 -0600825derivatives). To enable this for an entry, add a 'compress' property:
Simon Glass83d73c22018-09-14 04:57:26 -0600826
827 blob {
828 filename = "datafile";
Simon Glass8287ee82019-07-08 14:25:30 -0600829 compress = "lz4";
Simon Glass83d73c22018-09-14 04:57:26 -0600830 };
831
832The entry will then contain the compressed data, using the 'lz4' compression
Simon Glass8287ee82019-07-08 14:25:30 -0600833algorithm. Currently this is the only one that is supported. The uncompressed
834size is written to the node in an 'uncomp-size' property, if -u is used.
Simon Glass83d73c22018-09-14 04:57:26 -0600835
836
837
Simon Glass3b0c3822018-06-01 09:38:20 -0600838Map files
839---------
840
841The -m option causes binman to output a .map file for each image that it
Simon Glass3ab95982018-08-01 15:22:37 -0600842generates. This shows the offset and size of each entry. For example:
Simon Glass3b0c3822018-06-01 09:38:20 -0600843
Simon Glass3ab95982018-08-01 15:22:37 -0600844 Offset Size Name
Simon Glass8122f392018-07-17 13:25:28 -0600845 00000000 00000028 main-section
846 00000000 00000010 section@0
847 00000000 00000004 u-boot
848 00000010 00000010 section@1
849 00000000 00000004 u-boot
Simon Glass3b0c3822018-06-01 09:38:20 -0600850
851This shows a hierarchical image with two sections, each with a single entry. The
Simon Glass3ab95982018-08-01 15:22:37 -0600852offsets of the sections are absolute hex byte offsets within the image. The
853offsets of the entries are relative to their respective sections. The size of
Simon Glass3b0c3822018-06-01 09:38:20 -0600854each entry is also shown, in bytes (hex). The indentation shows the entries
855nested inside their sections.
856
857
Simon Glass53af22a2018-07-17 13:25:32 -0600858Passing command-line arguments to entries
859-----------------------------------------
860
861Sometimes it is useful to pass binman the value of an entry property from the
862command line. For example some entries need access to files and it is not
863always convenient to put these filenames in the image definition (device tree).
864
865The-a option supports this:
866
867 -a<prop>=<value>
868
869where
870
871 <prop> is the property to set
872 <value> is the value to set it to
873
874Not all properties can be provided this way. Only some entries support it,
875typically for filenames.
876
877
Simon Glassc7d80352019-07-08 13:18:28 -0600878External tools
879--------------
880
881Binman can make use of external command-line tools to handle processing of
882entry contents or to generate entry contents. These tools are executed using
883the 'tools' module's Run() method. The tools generally must exist on the PATH,
884but the --toolpath option can be used to specify additional search paths to
885use. This option can be specified multiple times to add more than one path.
886
887
Simon Glass6d427c62016-11-25 20:15:59 -0700888Code coverage
889-------------
890
891Binman is a critical tool and is designed to be very testable. Entry
Simon Glass53cd5d92019-07-08 14:25:29 -0600892implementations target 100% test coverage. Run 'binman test -T' to check this.
Simon Glass6d427c62016-11-25 20:15:59 -0700893
894To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
895
Simon Glass45f449b2019-07-08 13:18:26 -0600896 $ sudo apt-get install python-coverage python3-coverage python-pytest
Simon Glass6d427c62016-11-25 20:15:59 -0700897
898
Simon Glass55660d02019-05-17 22:00:52 -0600899Concurrent tests
900----------------
901
902Binman tries to run tests concurrently. This means that the tests make use of
903all available CPUs to run.
904
905 To enable this:
906
907 $ sudo apt-get install python-subunit python3-subunit
908
909Use '-P 1' to disable this. It is automatically disabled when code coverage is
910being used (-T) since they are incompatible.
911
912
Simon Glassd5164a72019-07-08 13:18:49 -0600913Debugging tests
914---------------
915
916Sometimes when debugging tests it is useful to keep the input and output
917directories so they can be examined later. Use -X or --test-preserve-dirs for
918this.
919
920
Simon Glassbf7fd502016-11-25 20:15:51 -0700921Advanced Features / Technical docs
922----------------------------------
923
924The behaviour of entries is defined by the Entry class. All other entries are
925a subclass of this. An important subclass is Entry_blob which takes binary
926data from a file and places it in the entry. In fact most entry types are
927subclasses of Entry_blob.
928
929Each entry type is a separate file in the tools/binman/etype directory. Each
930file contains a class called Entry_<type> where <type> is the entry type.
931New entry types can be supported by adding new files in that directory.
932These will automatically be detected by binman when needed.
933
934Entry properties are documented in entry.py. The entry subclasses are free
935to change the values of properties to support special behaviour. For example,
936when Entry_blob loads a file, it sets content_size to the size of the file.
937Entry classes can adjust other entries. For example, an entry that knows
Simon Glass3ab95982018-08-01 15:22:37 -0600938where other entries should be positioned can set up those entries' offsets
Simon Glassbf7fd502016-11-25 20:15:51 -0700939so they don't need to be set in the binman decription. It can also adjust
940entry contents.
941
942Most of the time such essoteric behaviour is not needed, but it can be
943essential for complex images.
944
Simon Glass3ed0de32017-12-24 12:12:07 -0700945If you need to specify a particular device-tree compiler to use, you can define
946the DTC environment variable. This can be useful when the system dtc is too
947old.
948
Simon Glassa3c00552018-11-06 15:21:31 -0700949To enable a full backtrace and other debugging features in binman, pass
950BINMAN_DEBUG=1 to your build:
951
Bin Mengc443f562019-10-02 19:07:29 -0700952 make qemu-x86_defconfig
Simon Glassa3c00552018-11-06 15:21:31 -0700953 make BINMAN_DEBUG=1
954
Simon Glass1f338e02019-09-25 08:11:11 -0600955To enable verbose logging from binman, base BINMAN_VERBOSE to your build, which
956adds a -v<level> option to the call to binman:
957
Bin Mengc443f562019-10-02 19:07:29 -0700958 make qemu-x86_defconfig
Simon Glass1f338e02019-09-25 08:11:11 -0600959 make BINMAN_VERBOSE=5
960
Simon Glassbf7fd502016-11-25 20:15:51 -0700961
962History / Credits
963-----------------
964
965Binman takes a lot of inspiration from a Chrome OS tool called
966'cros_bundle_firmware', which I wrote some years ago. That tool was based on
967a reasonably simple and sound design but has expanded greatly over the
968years. In particular its handling of x86 images is convoluted.
969
Simon Glass7ae5f312018-06-01 09:38:19 -0600970Quite a few lessons have been learned which are hopefully applied here.
Simon Glassbf7fd502016-11-25 20:15:51 -0700971
972
973Design notes
974------------
975
976On the face of it, a tool to create firmware images should be fairly simple:
977just find all the input binaries and place them at the right place in the
978image. The difficulty comes from the wide variety of input types (simple
979flat binaries containing code, packaged data with various headers), packing
980requirments (alignment, spacing, device boundaries) and other required
981features such as hierarchical images.
982
983The design challenge is to make it easy to create simple images, while
984allowing the more complex cases to be supported. For example, for most
985images we don't much care exactly where each binary ends up, so we should
986not have to specify that unnecessarily.
987
988New entry types should aim to provide simple usage where possible. If new
989core features are needed, they can be added in the Entry base class.
990
991
992To do
993-----
994
995Some ideas:
Simon Glassbf7fd502016-11-25 20:15:51 -0700996- Use of-platdata to make the information available to code that is unable
997 to use device tree (such as a very small SPL image)
Simon Glassbf7fd502016-11-25 20:15:51 -0700998- Allow easy building of images by specifying just the board name
Simon Glassbf7fd502016-11-25 20:15:51 -0700999- Support building an image for a board (-b) more completely, with a
1000 configurable build directory
Simon Glass488b2252019-07-08 14:25:24 -06001001- Support adding FITs to an image
1002- Support for ARM Trusted Firmware (ATF)
Simon Glass513c53e2019-07-20 12:24:02 -06001003- Detect invalid properties in nodes
1004- Sort the fdtmap by offset
Simon Glassbf7fd502016-11-25 20:15:51 -07001005
1006--
1007Simon Glass <sjg@chromium.org>
10087/7/2016