blob: e7b231e0712048dc2bd53f70c7eca67d1586bfa9 [file] [log] [blame]
Simon Glass75ead662021-03-18 20:25:13 +13001.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright (c) 2016 Google, Inc
Simon Glass2574ef62016-11-25 20:15:51 -07003
4Introduction
Simon Glassfa888282021-03-18 20:25:14 +13005============
Simon Glass2574ef62016-11-25 20:15:51 -07006
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
Simon Glass774b23f2021-03-18 20:25:17 +130012Building 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.
Simon Glass2574ef62016-11-25 20:15:51 -070017
Simon Glass2574ef62016-11-25 20:15:51 -070018
19What it does
20------------
21
22Binman reads your board's device tree and finds a node which describes the
Simon Glass774b23f2021-03-18 20:25:17 +130023required 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.
Simon Glass2574ef62016-11-25 20:15:51 -070029
30
31Features
32--------
33
Simon Glass774b23f2021-03-18 20:25:17 +130034Apart 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.
Simon Glass2574ef62016-11-25 20:15:51 -070037
Simon Glass774b23f2021-03-18 20:25:17 +130038Executable 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.
Simon Glass2574ef62016-11-25 20:15:51 -070041
Simon Glass774b23f2021-03-18 20:25:17 +130042Binman 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,
Simon Glass76d71b02022-08-07 16:33:26 -060045vblocks and the like.
Simon Glass774b23f2021-03-18 20:25:17 +130046
47Binman provides a way to process binaries before they are included, by adding a
48Python plug-in.
Simon Glass2574ef62016-11-25 20:15:51 -070049
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
Simon Glass774b23f2021-03-18 20:25:17 +130057As 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.
Simon Glass2574ef62016-11-25 20:15:51 -070062
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:
Simon Glass2574ef62016-11-25 20:15:51 -070074
Simon Glass75ead662021-03-18 20:25:13 +130075 - 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
Simon Glass2574ef62016-11-25 20:15:51 -070088
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
Simon Glass76d71b02022-08-07 16:33:26 -0600121Note that binman can itself create a FIT. This helps to move mkimage
122invocations out of the Makefile and into binman image descriptions. It also
123helps by removing the need for ad-hoc tools like `make_fit_atf.py`.
124
Simon Glass2574ef62016-11-25 20:15:51 -0700125
126Relationship to mkimage
127-----------------------
128
129The mkimage tool provides a means to create a FIT. Traditionally it has
130needed an image description file: a device tree, like binman, but in a
131different format. More recently it has started to support a '-f auto' mode
132which can generate that automatically.
133
134More relevant to binman, mkimage also permits creation of many SoC-specific
135image types. These can be listed by running 'mkimage -T list'. Examples
136include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often
137called from the U-Boot build system for this reason.
138
139Binman considers the output files created by mkimage to be binary blobs
140which it can place in an image. Binman does not replace the mkimage tool or
Michael Heimpold55c822d2018-08-22 22:01:24 +0200141this purpose. It would be possible in some situations to create a new entry
Simon Glass2574ef62016-11-25 20:15:51 -0700142type for the images in mkimage, but this would not add functionality. It
Michael Heimpold55c822d2018-08-22 22:01:24 +0200143seems better to use the mkimage tool to generate binaries and avoid blurring
Simon Glass2574ef62016-11-25 20:15:51 -0700144the boundaries between building input files (mkimage) and packaging then
145into a final image (binman).
146
Simon Glass76d71b02022-08-07 16:33:26 -0600147Note that binman can itself invoke mkimage. This helps to move mkimage
148invocations out of the Makefile and into binman image descriptions.
149
Simon Glassfa888282021-03-18 20:25:14 +1300150
151Using binman
152============
Simon Glass2574ef62016-11-25 20:15:51 -0700153
154Example use of binman in U-Boot
155-------------------------------
156
157Binman aims to replace some of the ad-hoc image creation in the U-Boot
158build system.
159
160Consider sunxi. It has the following steps:
161
Simon Glass75ead662021-03-18 20:25:13 +1300162 #. It uses a custom mksunxiboot tool to build an SPL image called
163 sunxi-spl.bin. This should probably move into mkimage.
Simon Glass2574ef62016-11-25 20:15:51 -0700164
Simon Glass75ead662021-03-18 20:25:13 +1300165 #. It uses mkimage to package U-Boot into a legacy image file (so that it can
166 hold the load and execution address) called u-boot.img.
Simon Glass2574ef62016-11-25 20:15:51 -0700167
Simon Glass75ead662021-03-18 20:25:13 +1300168 #. It builds a final output image called u-boot-sunxi-with-spl.bin which
169 consists of sunxi-spl.bin, some padding and u-boot.img.
Simon Glass2574ef62016-11-25 20:15:51 -0700170
171Binman is intended to replace the last step. The U-Boot build system builds
172u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
Simon Glass243c2c12022-02-08 11:49:54 -0700173sunxi-spl.bin by calling mksunxiboot or mkimage. In any case, it would then
174create the image from the component parts.
Simon Glass2574ef62016-11-25 20:15:51 -0700175
176This simplifies the U-Boot Makefile somewhat, since various pieces of logic
177can be replaced by a call to binman.
178
Simon Glass76d71b02022-08-07 16:33:26 -0600179
180Invoking binman within U-Boot
181-----------------------------
182
183Within U-Boot, binman is invoked by the build system, i.e. when you type 'make'
184or use buildman to build U-Boot. There is no need to run binman independently
185during development. Everything happens automatically and is set up for your
186SoC or board so that binman produced the right things.
187
188The general policy is that the Makefile builds all the binaries in INPUTS-y
189(the 'inputs' rule), then binman is run to produce the final images (the 'all'
190rule).
191
192There should be only one invocation of binman in Makefile, the very last step
193that pulls everything together. At present there are some arch-specific
194invocations as well, but these should be dropped when those architectures are
195converted to use binman properly.
196
197As above, the term 'binary' is used for something in INPUTS-y and 'image' is
198used for the things that binman creates. So the binaries are inputs to the
199image(s) and it is the image that is actually loaded on the board.
200
201Again, at present, there are a number of things created in Makefile which should
202be done by binman (when we get around to it), like `u-boot-ivt.img`,
203`lpc32xx-spl.img`, `u-boot-with-nand-spl.imx`, `u-boot-spl-padx4.sfp` and
204`u-boot-mtk.bin`, just to pick on a few. When completed this will remove about
205400 lines from `Makefile`.
206
207Since binman is invoked only once, it must of course create all the images that
208are needed, in that one invocation. It does this by working through the image
209descriptions one by one, collecting the input binaries, processing them as
210needed and producing the final images.
211
212The same binaries may be used by multiple images. For example binman may be used
213to produce an SD-card image and a SPI-flash image. In this case the binaries
214going into the process are the same, but binman produces slightly different
215images in each case.
216
217For some SoCs, U-Boot is not the only project that produces the necessary
218binaries. For example, ARM Trusted Firmware (ATF) is a project that produces
219binaries which must be incorporate, such as `bl31.elf` or `bl31.bin`. For this
220to work you must have built ATF before you build U-Boot and you must tell U-Boot
221where to find the bl31 image, using the BL31 environment variable.
222
223How do you know how to incorporate ATF? It is handled by the atf-bl31 entry type
224(etype). An etype is an implementation of reading a binary into binman, in this
225case the `bl31.bin` file. When you build U-Boot but do not set the BL31
226environment variable, binman provides a help message, which comes from
227`missing-blob-help`::
228
229 See the documentation for your board. You may need to build ARM Trusted
230 Firmware and build with BL31=/path/to/bl31.bin
231
232The mechanism by which binman is advised of this is also in the Makefile. See
233the `-a atf-bl31-path=${BL31}` piece in `cmd_binman`. This tells binman to
234set the EntryArg `atf-bl31-path` to the value of the `BL31` environment
235variable. Within binman, this EntryArg is picked up by the `Entry_atf_bl31`
236etype. An EntryArg is simply an argument to the entry. The `atf-bl31-path`
237name is documented in :ref:`etype_atf_bl31`.
238
Simon Glass7d959c52022-08-18 02:16:45 -0600239Taking this a little further, when binman is used to create a FIT, it supports
240using an ELF file, e.g. `bl31.elf` and splitting it into separate pieces (with
241`fit,operation = "split-elf"`), each with its own load address.
242
Simon Glass76d71b02022-08-07 16:33:26 -0600243
244Invoking binman outside U-Boot
245------------------------------
246
247While binman is invoked from within the U-Boot build system, it is also possible
248to invoke it separately. This is typically used in a production build system,
249where signing is completed (with real keys) and any missing binaries are
250provided.
251
252For example, for build testing there is no need to provide a real signature,
253nor is there any need to provide a real ATF BL31 binary (for example). These can
254be added later by invoking binman again, providing all the required inputs
255from the first time, plus any that were missing or placeholders.
256
257So in practice binman is often used twice:
258
259- once within the U-Boot build system, for development and testing
260- again outside U-Boot to assembly and final production images
261
262While the same input binaries are used in each case, you will of course you will
263need to create your own binman command line, similar to that in `cmd_binman` in
264the Makefile. You may find the -I and --toolpath options useful. The
265device tree file is provided to binman in binary form, so there is no need to
266have access to the original `.dts` sources.
267
268
269Assembling the image description
270--------------------------------
271
272Since binman uses the device tree for its image description, you can use the
273same files that describe your board's hardware to describe how the image is
274assembled. Typically the images description is in a common file used by all
275boards with a particular SoC (e.g. `imx8mp-u-boot.dtsi`).
276
277Where a particular boards needs to make changes, it can override properties in
278the SoC file, just as it would for any other device tree property. It can also
279add a image that is specific to the board.
280
281Another way to control the image description to make use of CONFIG options in
282the description. For example, if the start offset of a particular entry varies
283by board, you can add a Kconfig for that and reference it in the description::
284
285 u-boot-spl {
286 };
287
288 fit {
289 offset = <CONFIG_SPL_PAD_TO>;
290 ...
291 };
292
293The SoC can provide a default value but boards can override that as needed and
294binman will take care of it.
295
296It is even possible to control which entries appear in the image, by using the
297C preprocessor::
298
299 #ifdef CONFIG_HAVE_MRC
300 intel-mrc {
301 offset = <CONFIG_X86_MRC_ADDR>;
302 };
303 #endif
304
305Only boards which enable `HAVE_MRC` will include this entry.
306
307Obviously a similar approach can be used to control which images are produced,
308with a Kconfig option to enable a SPI image, for example. However there is
309generally no harm in producing an image that is not used. If a board uses MMC
310but not SPI, but the SoC supports booting from both, then both images can be
311produced, with only on or other being used by particular boards. This can help
312reduce the need for having multiple defconfig targets for a board where the
313only difference is the boot media, enabling / disabling secure boot, etc.
314
315Of course you can use the device tree itself to pass any board-specific
316information that is needed by U-Boot at runtime (see binman_syms_ for how to
317make binman insert these values directly into executables like SPL).
318
319There is one more way this can be done: with individual .dtsi files for each
320image supported by the SoC. Then the board `.dts` file can include the ones it
321wants. This is not recommended, since it is likely to be difficult to maintain
322and harder to understand the relationship between the different boards.
323
324
325Producing images for multiple boards
326------------------------------------
327
328When invoked within U-Boot, binman only builds a single set of images, for
329the chosen board. This is set by the `CONFIG_DEFAULT_DEVICE_TREE` option.
330
331However, U-Boot generally builds all the device tree files associated with an
332SoC. These are written to the (e.g. for ARM) `arch/arm/dts` directory. Each of
333these contains the full binman description for that board. Often the best
334approach is to build a single image that includes all these device tree binaries
335and allow SPL to select the correct one on boot.
336
337However, it is also possible to build separate images for each board, simply by
338invoking binman multiple times, once for each device tree file, using a
339different output directory. This will produce one set of images for each board.
340
Simon Glass2574ef62016-11-25 20:15:51 -0700341
342Example use of binman for x86
343-----------------------------
344
345In most cases x86 images have a lot of binary blobs, 'black-box' code
346provided by Intel which must be run for the platform to work. Typically
347these blobs are not relocatable and must be placed at fixed areas in the
Michael Heimpold55c822d2018-08-22 22:01:24 +0200348firmware image.
Simon Glass2574ef62016-11-25 20:15:51 -0700349
350Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA
351BIOS, reference code and Intel ME binaries into a u-boot.rom file.
352
353Binman is intended to replace all of this, with ifdtool left to handle only
354the configuration of the Intel-format descriptor.
355
356
Simon Glass7a7874f2022-01-09 20:13:48 -0700357Installing binman
358-----------------
Simon Glass2574ef62016-11-25 20:15:51 -0700359
Simon Glass76d71b02022-08-07 16:33:26 -0600360First install prerequisites, e.g:
361
362.. code-block:: bash
Simon Glass567b6822019-07-08 13:18:35 -0600363
Simon Glass75ead662021-03-18 20:25:13 +1300364 sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
365 liblz4-tool
Simon Glass567b6822019-07-08 13:18:35 -0600366
Simon Glass7a7874f2022-01-09 20:13:48 -0700367You can run binman directly if you put it on your PATH. But if you want to
Simon Glass76d71b02022-08-07 16:33:26 -0600368install into your `~/.local` Python directory, use:
369
370.. code-block:: bash
Simon Glass7a7874f2022-01-09 20:13:48 -0700371
372 pip install tools/patman tools/dtoc tools/binman
373
374Note that binman makes use of libraries from patman and dtoc, which is why these
375need to be installed. Also you need `libfdt` and `pylibfdt` which can be
Simon Glass76d71b02022-08-07 16:33:26 -0600376installed like this:
377
378.. code-block:: bash
Simon Glass7a7874f2022-01-09 20:13:48 -0700379
380 git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
381 cd dtc
382 pip install .
383 make NO_PYTHON=1 install
384
385This installs the `libfdt.so` library into `~/lib` so you can use
386`LD_LIBRARY_PATH=~/lib` when running binman. If you want to install it in the
Simon Glass76d71b02022-08-07 16:33:26 -0600387system-library directory, replace the last line with:
388
389.. code-block:: bash
Simon Glass7a7874f2022-01-09 20:13:48 -0700390
391 make NO_PYTHON=1 PREFIX=/ install
392
393Running binman
394--------------
395
Simon Glass75ead662021-03-18 20:25:13 +1300396Type::
Simon Glass2574ef62016-11-25 20:15:51 -0700397
Simon Glass76d71b02022-08-07 16:33:26 -0600398.. code-block: bash
399
400 make NO_PYTHON=1 PREFIX=/ install
Simon Glass75ead662021-03-18 20:25:13 +1300401 binman build -b <board_name>
Simon Glass2574ef62016-11-25 20:15:51 -0700402
403to build an image for a board. The board name is the same name used when
404configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
405Binman assumes that the input files for the build are in ../b/<board_name>.
406
Simon Glass76d71b02022-08-07 16:33:26 -0600407Or you can specify this explicitly:
408
409.. code-block:: bash
Simon Glass2574ef62016-11-25 20:15:51 -0700410
Simon Glass76d71b02022-08-07 16:33:26 -0600411 make NO_PYTHON=1 PREFIX=/ install
Simon Glass75ead662021-03-18 20:25:13 +1300412 binman build -I <build_path>
Simon Glass2574ef62016-11-25 20:15:51 -0700413
414where <build_path> is the build directory containing the output of the U-Boot
415build.
416
417(Future work will make this more configurable)
418
419In either case, binman picks up the device tree file (u-boot.dtb) and looks
420for its instructions in the 'binman' node.
421
422Binman has a few other options which you can see by running 'binman -h'.
423
424
Simon Glass4b94ac92017-11-12 21:52:06 -0700425Enabling binman for a board
426---------------------------
427
Simon Glass774b23f2021-03-18 20:25:17 +1300428At present binman is invoked from a rule in the main Makefile. You should be
429able to enable CONFIG_BINMAN to enable this rule.
Simon Glass4b94ac92017-11-12 21:52:06 -0700430
Simon Glass774b23f2021-03-18 20:25:17 +1300431The output file is typically named image.bin and is located in the output
432directory. If input files are needed to you add these to INPUTS-y either in the
433main Makefile or in a config.mk file in your arch subdirectory.
Simon Glass4b94ac92017-11-12 21:52:06 -0700434
435Once binman is executed it will pick up its instructions from a device-tree
436file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value.
437You can use other, more specific CONFIG options - see 'Automatic .dtsi
438inclusion' below.
439
Simon Glass76d71b02022-08-07 16:33:26 -0600440.. _binman_syms:
Simon Glass4b94ac92017-11-12 21:52:06 -0700441
Simon Glassfa888282021-03-18 20:25:14 +1300442Access to binman entry offsets at run time (symbols)
443----------------------------------------------------
444
445Binman assembles images and determines where each entry is placed in the image.
446This information may be useful to U-Boot at run time. For example, in SPL it
447is useful to be able to find the location of U-Boot so that it can be executed
448when SPL is finished.
449
450Binman allows you to declare symbols in the SPL image which are filled in
Simon Glass76d71b02022-08-07 16:33:26 -0600451with their correct values during the build. For example:
452
453.. code-block:: c
Simon Glassfa888282021-03-18 20:25:14 +1300454
455 binman_sym_declare(ulong, u_boot_any, image_pos);
456
457declares a ulong value which will be assigned to the image-pos of any U-Boot
458image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
Simon Glass76d71b02022-08-07 16:33:26 -0600459You can access this value with something like:
460
461.. code-block:: c
Simon Glassfa888282021-03-18 20:25:14 +1300462
463 ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos);
464
465Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming
466that the whole image has been loaded, or is available in flash. You can then
467jump to that address to start U-Boot.
468
469At present this feature is only supported in SPL and TPL. In principle it is
470possible to fill in such symbols in U-Boot proper, as well, but a future C
471library is planned for this instead, to read from the device tree.
472
473As well as image-pos, it is possible to read the size of an entry and its
474offset (which is the start position of the entry within its parent).
475
476A small technical note: Binman automatically adds the base address of the image
477(i.e. __image_copy_start) to the value of the image-pos symbol, so that when the
478image is loaded to its linked address, the value will be correct and actually
479point into the image.
480
481For example, say SPL is at the start of the image and linked to start at address
48280108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos
483for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded
484to 80108000, with SPL at 80108000 and U-Boot at 80110000.
485
486For x86 devices (with the end-at-4gb property) this base address is not added
487since it is assumed that images are XIP and the offsets already include the
488address.
489
490
491Access to binman entry offsets at run time (fdt)
492------------------------------------------------
493
494Binman can update the U-Boot FDT to include the final position and size of
495each entry in the images it processes. The option to enable this is -u and it
496causes binman to make sure that the 'offset', 'image-pos' and 'size' properties
497are set correctly for every entry. Since it is not necessary to specify these in
498the image definition, binman calculates the final values and writes these to
499the device tree. These can be used by U-Boot at run-time to find the location
500of each entry.
501
502Alternatively, an FDT map entry can be used to add a special FDT containing
503just the information about the image. This is preceded by a magic string so can
504be located anywhere in the image. An image header (typically at the start or end
505of the image) can be used to point to the FDT map. See fdtmap and image-header
506entries for more information.
507
Simon Glassfa888282021-03-18 20:25:14 +1300508Map files
509---------
510
511The -m option causes binman to output a .map file for each image that it
512generates. This shows the offset and size of each entry. For example::
513
514 Offset Size Name
515 00000000 00000028 main-section
516 00000000 00000010 section@0
517 00000000 00000004 u-boot
518 00000010 00000010 section@1
519 00000000 00000004 u-boot
520
521This shows a hierarchical image with two sections, each with a single entry. The
522offsets of the sections are absolute hex byte offsets within the image. The
523offsets of the entries are relative to their respective sections. The size of
524each entry is also shown, in bytes (hex). The indentation shows the entries
525nested inside their sections.
526
527
528Passing command-line arguments to entries
529-----------------------------------------
530
531Sometimes it is useful to pass binman the value of an entry property from the
532command line. For example some entries need access to files and it is not
533always convenient to put these filenames in the image definition (device tree).
534
Bin Meng1fa2b7c2021-05-10 20:23:30 +0800535The -a option supports this::
Simon Glassfa888282021-03-18 20:25:14 +1300536
Bin Meng1fa2b7c2021-05-10 20:23:30 +0800537 -a <prop>=<value>
Simon Glassfa888282021-03-18 20:25:14 +1300538
539where::
540
541 <prop> is the property to set
542 <value> is the value to set it to
543
544Not all properties can be provided this way. Only some entries support it,
545typically for filenames.
546
547
Simon Glass2574ef62016-11-25 20:15:51 -0700548Image description format
Simon Glassfa888282021-03-18 20:25:14 +1300549========================
Simon Glass2574ef62016-11-25 20:15:51 -0700550
551The binman node is called 'binman'. An example image description is shown
Simon Glass75ead662021-03-18 20:25:13 +1300552below::
Simon Glass2574ef62016-11-25 20:15:51 -0700553
Simon Glass75ead662021-03-18 20:25:13 +1300554 binman {
555 filename = "u-boot-sunxi-with-spl.bin";
556 pad-byte = <0xff>;
557 blob {
558 filename = "spl/sunxi-spl.bin";
559 };
560 u-boot {
561 offset = <CONFIG_SPL_PAD_TO>;
562 };
563 };
Simon Glass2574ef62016-11-25 20:15:51 -0700564
565
566This requests binman to create an image file called u-boot-sunxi-with-spl.bin
567consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the
568normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The
569padding comes from the fact that the second binary is placed at
570CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would
571immediately follow the SPL binary.
572
573The binman node describes an image. The sub-nodes describe entries in the
574image. Each entry represents a region within the overall image. The name of
575the entry (blob, u-boot) tells binman what to put there. For 'blob' we must
576provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'.
577
578Entries are normally placed into the image sequentially, one after the other.
579The image size is the total size of all entries. As you can see, you can
Simon Glasse8561af2018-08-01 15:22:37 -0600580specify the start offset of an entry using the 'offset' property.
Simon Glass2574ef62016-11-25 20:15:51 -0700581
582Note that due to a device tree requirement, all entries must have a unique
583name. If you want to put the same binary in the image multiple times, you can
584use any unique name, with the 'type' property providing the type.
585
586The attributes supported for entries are described below.
587
Simon Glasse8561af2018-08-01 15:22:37 -0600588offset:
Simon Glass75ead662021-03-18 20:25:13 +1300589 This sets the offset of an entry within the image or section containing
590 it. The first byte of the image is normally at offset 0. If 'offset' is
591 not provided, binman sets it to the end of the previous region, or the
592 start of the image's entry area (normally 0) if there is no previous
593 region.
Simon Glass2574ef62016-11-25 20:15:51 -0700594
595align:
Simon Glass75ead662021-03-18 20:25:13 +1300596 This sets the alignment of the entry. The entry offset is adjusted
597 so that the entry starts on an aligned boundary within the containing
598 section or image. For example 'align = <16>' means that the entry will
599 start on a 16-byte boundary. This may mean that padding is added before
600 the entry. The padding is part of the containing section but is not
601 included in the entry, meaning that an empty space may be created before
602 the entry starts. Alignment should be a power of 2. If 'align' is not
603 provided, no alignment is performed.
Simon Glass2574ef62016-11-25 20:15:51 -0700604
605size:
Simon Glass75ead662021-03-18 20:25:13 +1300606 This sets the size of the entry. The contents will be padded out to
607 this size. If this is not provided, it will be set to the size of the
608 contents.
Simon Glass2574ef62016-11-25 20:15:51 -0700609
610pad-before:
Simon Glass75ead662021-03-18 20:25:13 +1300611 Padding before the contents of the entry. Normally this is 0, meaning
612 that the contents start at the beginning of the entry. This can be used
613 to offset the entry contents a little. While this does not affect the
614 contents of the entry within binman itself (the padding is performed
615 only when its parent section is assembled), the end result will be that
616 the entry starts with the padding bytes, so may grow. Defaults to 0.
Simon Glass2574ef62016-11-25 20:15:51 -0700617
618pad-after:
Simon Glass75ead662021-03-18 20:25:13 +1300619 Padding after the contents of the entry. Normally this is 0, meaning
620 that the entry ends at the last byte of content (unless adjusted by
621 other properties). This allows room to be created in the image for
622 this entry to expand later. While this does not affect the contents of
623 the entry within binman itself (the padding is performed only when its
624 parent section is assembled), the end result will be that the entry ends
625 with the padding bytes, so may grow. Defaults to 0.
Simon Glass2574ef62016-11-25 20:15:51 -0700626
627align-size:
Simon Glass75ead662021-03-18 20:25:13 +1300628 This sets the alignment of the entry size. For example, to ensure
629 that the size of an entry is a multiple of 64 bytes, set this to 64.
630 While this does not affect the contents of the entry within binman
631 itself (the padding is performed only when its parent section is
632 assembled), the end result is that the entry ends with the padding
633 bytes, so may grow. If 'align-size' is not provided, no alignment is
634 performed.
Simon Glass2574ef62016-11-25 20:15:51 -0700635
636align-end:
Simon Glass75ead662021-03-18 20:25:13 +1300637 This sets the alignment of the end of an entry with respect to the
638 containing section. Some entries require that they end on an alignment
639 boundary, regardless of where they start. This does not move the start
640 of the entry, so the contents of the entry will still start at the
641 beginning. But there may be padding at the end. While this does not
642 affect the contents of the entry within binman itself (the padding is
643 performed only when its parent section is assembled), the end result
644 is that the entry ends with the padding bytes, so may grow.
645 If 'align-end' is not provided, no alignment is performed.
Simon Glass2574ef62016-11-25 20:15:51 -0700646
647filename:
Simon Glass75ead662021-03-18 20:25:13 +1300648 For 'blob' types this provides the filename containing the binary to
649 put into the entry. If binman knows about the entry type (like
650 u-boot-bin), then there is no need to specify this.
Simon Glass2574ef62016-11-25 20:15:51 -0700651
652type:
Simon Glass75ead662021-03-18 20:25:13 +1300653 Sets the type of an entry. This defaults to the entry name, but it is
654 possible to use any name, and then add (for example) 'type = "u-boot"'
655 to specify the type.
Simon Glass2574ef62016-11-25 20:15:51 -0700656
Simon Glasse8561af2018-08-01 15:22:37 -0600657offset-unset:
Simon Glass75ead662021-03-18 20:25:13 +1300658 Indicates that the offset of this entry should not be set by placing
659 it immediately after the entry before. Instead, is set by another
660 entry which knows where this entry should go. When this boolean
661 property is present, binman will give an error if another entry does
662 not set the offset (with the GetOffsets() method).
Simon Glass4ba8d502018-06-01 09:38:17 -0600663
Simon Glass9dcc8612018-08-01 15:22:42 -0600664image-pos:
Simon Glass75ead662021-03-18 20:25:13 +1300665 This cannot be set on entry (or at least it is ignored if it is), but
666 with the -u option, binman will set it to the absolute image position
667 for each entry. This makes it easy to find out exactly where the entry
668 ended up in the image, regardless of parent sections, etc.
Simon Glass9dcc8612018-08-01 15:22:42 -0600669
Simon Glassdd156a42022-03-05 20:18:59 -0700670extend-size:
671 Extend the size of this entry to fit available space. This space is only
Simon Glass75ead662021-03-18 20:25:13 +1300672 limited by the size of the image/section and the position of the next
673 entry.
Simon Glass2574ef62016-11-25 20:15:51 -0700674
Simon Glassaa2fcf92019-07-08 14:25:30 -0600675compress:
Simon Glass75ead662021-03-18 20:25:13 +1300676 Sets the compression algortihm to use (for blobs only). See the entry
677 documentation for details.
Simon Glassaa2fcf92019-07-08 14:25:30 -0600678
Simon Glassa820af72020-09-06 10:39:09 -0600679missing-msg:
Simon Glass75ead662021-03-18 20:25:13 +1300680 Sets the tag of the message to show if this entry is missing. This is
681 used for external blobs. When they are missing it is helpful to show
682 information about what needs to be fixed. See missing-blob-help for the
683 message for each tag.
Simon Glassa820af72020-09-06 10:39:09 -0600684
Simon Glass7098b7f2021-03-21 18:24:30 +1300685no-expanded:
686 By default binman substitutes entries with expanded versions if available,
687 so that a `u-boot` entry type turns into `u-boot-expanded`, for example. The
688 `--no-expanded` command-line option disables this globally. The
689 `no-expanded` property disables this just for a single entry. Put the
690 `no-expanded` boolean property in the node to select this behaviour.
691
Simon Glass80045812018-09-14 04:57:30 -0600692The attributes supported for images and sections are described below. Several
693are similar to those for entries.
Simon Glass2574ef62016-11-25 20:15:51 -0700694
695size:
Simon Glass75ead662021-03-18 20:25:13 +1300696 Sets the image size in bytes, for example 'size = <0x100000>' for a
697 1MB image.
Simon Glass2574ef62016-11-25 20:15:51 -0700698
Simon Glasseb023b32019-04-25 21:58:39 -0600699offset:
Simon Glass75ead662021-03-18 20:25:13 +1300700 This is similar to 'offset' in entries, setting the offset of a section
701 within the image or section containing it. The first byte of the section
702 is normally at offset 0. If 'offset' is not provided, binman sets it to
703 the end of the previous region, or the start of the image's entry area
704 (normally 0) if there is no previous region.
Simon Glasseb023b32019-04-25 21:58:39 -0600705
Simon Glass2574ef62016-11-25 20:15:51 -0700706align-size:
Simon Glass75ead662021-03-18 20:25:13 +1300707 This sets the alignment of the image size. For example, to ensure
708 that the image ends on a 512-byte boundary, use 'align-size = <512>'.
709 If 'align-size' is not provided, no alignment is performed.
Simon Glass2574ef62016-11-25 20:15:51 -0700710
711pad-before:
Simon Glass75ead662021-03-18 20:25:13 +1300712 This sets the padding before the image entries. The first entry will
713 be positioned after the padding. This defaults to 0.
Simon Glass2574ef62016-11-25 20:15:51 -0700714
715pad-after:
Simon Glass75ead662021-03-18 20:25:13 +1300716 This sets the padding after the image entries. The padding will be
717 placed after the last entry. This defaults to 0.
Simon Glass2574ef62016-11-25 20:15:51 -0700718
719pad-byte:
Simon Glass75ead662021-03-18 20:25:13 +1300720 This specifies the pad byte to use when padding in the image. It
721 defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
Simon Glass2574ef62016-11-25 20:15:51 -0700722
723filename:
Simon Glass75ead662021-03-18 20:25:13 +1300724 This specifies the image filename. It defaults to 'image.bin'.
Simon Glass2574ef62016-11-25 20:15:51 -0700725
Simon Glasse8561af2018-08-01 15:22:37 -0600726sort-by-offset:
Simon Glass75ead662021-03-18 20:25:13 +1300727 This causes binman to reorder the entries as needed to make sure they
728 are in increasing positional order. This can be used when your entry
729 order may not match the positional order. A common situation is where
730 the 'offset' properties are set by CONFIG options, so their ordering is
731 not known a priori.
Simon Glass2574ef62016-11-25 20:15:51 -0700732
Simon Glass75ead662021-03-18 20:25:13 +1300733 This is a boolean property so needs no value. To enable it, add a
734 line 'sort-by-offset;' to your description.
Simon Glass2574ef62016-11-25 20:15:51 -0700735
736multiple-images:
Simon Glass75ead662021-03-18 20:25:13 +1300737 Normally only a single image is generated. To create more than one
738 image, put this property in the binman node. For example, this will
739 create image1.bin containing u-boot.bin, and image2.bin containing
740 both spl/u-boot-spl.bin and u-boot.bin::
Simon Glass2574ef62016-11-25 20:15:51 -0700741
Simon Glass75ead662021-03-18 20:25:13 +1300742 binman {
743 multiple-images;
744 image1 {
745 u-boot {
746 };
747 };
Simon Glass2574ef62016-11-25 20:15:51 -0700748
Simon Glass75ead662021-03-18 20:25:13 +1300749 image2 {
750 spl {
751 };
752 u-boot {
753 };
754 };
755 };
Simon Glass2574ef62016-11-25 20:15:51 -0700756
757end-at-4gb:
Simon Glass75ead662021-03-18 20:25:13 +1300758 For x86 machines the ROM offsets start just before 4GB and extend
759 up so that the image finished at the 4GB boundary. This boolean
760 option can be enabled to support this. The image size must be
761 provided so that binman knows when the image should start. For an
762 8MB ROM, the offset of the first entry would be 0xfff80000 with
763 this option, instead of 0 without this option.
Simon Glass2574ef62016-11-25 20:15:51 -0700764
Jagdish Gediya0fb978c2018-09-03 21:35:07 +0530765skip-at-start:
Simon Glass75ead662021-03-18 20:25:13 +1300766 This property specifies the entry offset of the first entry.
Jagdish Gediya0fb978c2018-09-03 21:35:07 +0530767
Simon Glass72cc5382022-10-20 18:22:39 -0600768 For PowerPC mpc85xx based CPU, CONFIG_TEXT_BASE is the entry
Simon Glass75ead662021-03-18 20:25:13 +1300769 offset of the first entry. It can be 0xeff40000 or 0xfff40000 for
770 nor flash boot, 0x201000 for sd boot etc.
Jagdish Gediya0fb978c2018-09-03 21:35:07 +0530771
Simon Glass72cc5382022-10-20 18:22:39 -0600772 'end-at-4gb' property is not applicable where CONFIG_TEXT_BASE +
Simon Glass75ead662021-03-18 20:25:13 +1300773 Image size != 4gb.
Simon Glass2574ef62016-11-25 20:15:51 -0700774
Simon Glassf427c5f2021-03-21 18:24:33 +1300775align-default:
776 Specifies the default alignment for entries in this section, if they do
777 not specify an alignment. Note that this only applies to top-level entries
778 in the section (direct subentries), not any subentries of those entries.
779 This means that each section must specify its own default alignment, if
780 required.
781
Neha Malcom Francis3eb4be32022-10-17 16:36:25 +0530782symlink:
783 Adds a symlink to the image with string given in the symlink property.
784
Simon Glass2574ef62016-11-25 20:15:51 -0700785Examples of the above options can be found in the tests. See the
786tools/binman/test directory.
787
Simon Glasse76a3e62018-06-01 09:38:11 -0600788It is possible to have the same binary appear multiple times in the image,
789either by using a unit number suffix (u-boot@0, u-boot@1) or by using a
790different name for each and specifying the type with the 'type' attribute.
791
Simon Glass2574ef62016-11-25 20:15:51 -0700792
Michael Heimpold55c822d2018-08-22 22:01:24 +0200793Sections and hierachical images
Simon Glassa91e1152018-06-01 09:38:16 -0600794-------------------------------
795
796Sometimes it is convenient to split an image into several pieces, each of which
797contains its own set of binaries. An example is a flash device where part of
798the image is read-only and part is read-write. We can set up sections for each
799of these, and place binaries in them independently. The image is still produced
800as a single output file.
801
802This feature provides a way of creating hierarchical images. For example here
Simon Glass1e324002018-06-01 09:38:19 -0600803is an example image with two copies of U-Boot. One is read-only (ro), intended
804to be written only in the factory. Another is read-write (rw), so that it can be
Simon Glassa91e1152018-06-01 09:38:16 -0600805upgraded in the field. The sizes are fixed so that the ro/rw boundary is known
Simon Glass75ead662021-03-18 20:25:13 +1300806and can be programmed::
Simon Glassa91e1152018-06-01 09:38:16 -0600807
Simon Glass75ead662021-03-18 20:25:13 +1300808 binman {
809 section@0 {
810 read-only;
811 name-prefix = "ro-";
812 size = <0x100000>;
813 u-boot {
814 };
815 };
816 section@1 {
817 name-prefix = "rw-";
818 size = <0x100000>;
819 u-boot {
820 };
821 };
822 };
Simon Glassa91e1152018-06-01 09:38:16 -0600823
824This image could be placed into a SPI flash chip, with the protection boundary
825set at 1MB.
826
827A few special properties are provided for sections:
828
829read-only:
Simon Glass75ead662021-03-18 20:25:13 +1300830 Indicates that this section is read-only. This has no impact on binman's
831 operation, but his property can be read at run time.
Simon Glassa91e1152018-06-01 09:38:16 -0600832
Simon Glass3b78d532018-06-01 09:38:21 -0600833name-prefix:
Simon Glass75ead662021-03-18 20:25:13 +1300834 This string is prepended to all the names of the binaries in the
835 section. In the example above, the 'u-boot' binaries which actually be
836 renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
837 distinguish binaries with otherwise identical names.
Simon Glass3b78d532018-06-01 09:38:21 -0600838
Simon Glassa91e1152018-06-01 09:38:16 -0600839
Simon Glassfb30e292019-07-20 12:23:51 -0600840Image Properties
841----------------
842
843Image nodes act like sections but also have a few extra properties:
844
845filename:
Simon Glass75ead662021-03-18 20:25:13 +1300846 Output filename for the image. This defaults to image.bin (or in the
847 case of multiple images <nodename>.bin where <nodename> is the name of
848 the image node.
Simon Glassfb30e292019-07-20 12:23:51 -0600849
850allow-repack:
Simon Glass75ead662021-03-18 20:25:13 +1300851 Create an image that can be repacked. With this option it is possible
852 to change anything in the image after it is created, including updating
853 the position and size of image components. By default this is not
854 permitted since it is not possibly to know whether this might violate a
855 constraint in the image description. For example, if a section has to
856 increase in size to hold a larger binary, that might cause the section
857 to fall out of its allow region (e.g. read-only portion of flash).
Simon Glassfb30e292019-07-20 12:23:51 -0600858
Simon Glass75ead662021-03-18 20:25:13 +1300859 Adding this property causes the original offset and size values in the
860 image description to be stored in the FDT and fdtmap.
Simon Glassfb30e292019-07-20 12:23:51 -0600861
862
Simon Glassfca38562022-08-18 02:16:46 -0600863Image dependencies
864------------------
865
866Binman does not currently support images that depend on each other. For example,
867if one image creates `fred.bin` and then the next uses this `fred.bin` to
868produce a final `image.bin`, then the behaviour is undefined. It may work, or it
869may produce an error about `fred.bin` being missing, or it may use a version of
870`fred.bin` from a previous run.
871
872Often this can be handled by incorporating the dependency into the second
873image. For example, instead of::
874
875 binman {
876 multiple-images;
877
878 fred {
879 u-boot {
880 };
881 fill {
882 size = <0x100>;
883 };
884 };
885
886 image {
887 blob {
888 filename = "fred.bin";
889 };
890 u-boot-spl {
891 };
892 };
893
894you can do this::
895
896 binman {
897 image {
898 fred {
899 type = "section";
900 u-boot {
901 };
902 fill {
903 size = <0x100>;
904 };
905 };
906 u-boot-spl {
907 };
908 };
909
910
911
Simon Glassfa888282021-03-18 20:25:14 +1300912Hashing Entries
913---------------
914
915It is possible to ask binman to hash the contents of an entry and write that
916value back to the device-tree node. For example::
917
918 binman {
919 u-boot {
920 hash {
921 algo = "sha256";
922 };
923 };
924 };
925
926Here, a new 'value' property will be written to the 'hash' node containing
927the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole
928sections can be hased if desired, by adding the 'hash' node to the section.
929
930The has value can be chcked at runtime by hashing the data actually read and
931comparing this has to the value in the device tree.
932
933
934Expanded entries
935----------------
936
937Binman automatically replaces 'u-boot' with an expanded version of that, i.e.
938'u-boot-expanded'. This means that when you write::
939
940 u-boot {
941 };
942
943you actually get::
944
945 u-boot {
946 type = "u-boot-expanded';
947 };
948
949which in turn expands to::
950
951 u-boot {
952 type = "section";
953
954 u-boot-nodtb {
955 };
956
957 u-boot-dtb {
958 };
959 };
960
961U-Boot's various phase binaries actually comprise two or three pieces.
962For example, u-boot.bin has the executable followed by a devicetree.
963
964With binman we want to be able to update that devicetree with full image
965information so that it is accessible to the executable. This is tricky
966if it is not clear where the devicetree starts.
967
968The above feature ensures that the devicetree is clearly separated from the
969U-Boot executable and can be updated separately by binman as needed. It can be
970disabled with the --no-expanded flag if required.
971
Heiko Thieryd5894562022-01-24 08:11:01 +0100972The same applies for u-boot-spl and u-boot-tpl. In those cases, the expansion
Simon Glassfa888282021-03-18 20:25:14 +1300973includes the BSS padding, so for example::
974
975 spl {
976 type = "u-boot-spl"
977 };
978
979you actually get::
980
981 spl {
982 type = "u-boot-expanded';
983 };
984
985which in turn expands to::
986
987 spl {
988 type = "section";
989
990 u-boot-spl-nodtb {
991 };
992
993 u-boot-spl-bss-pad {
994 };
995
996 u-boot-spl-dtb {
997 };
998 };
999
1000Of course we should not expand SPL if it has no devicetree. Also if the BSS
1001padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS),
1002the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned
1003entry type is controlled by the UseExpanded() method. In the SPL case it checks
1004the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree.
1005
1006For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. All
1007entry args are provided by the U-Boot Makefile.
1008
1009
1010Compression
1011-----------
1012
1013Binman support compression for 'blob' entries (those of type 'blob' and
1014derivatives). To enable this for an entry, add a 'compress' property::
1015
1016 blob {
1017 filename = "datafile";
1018 compress = "lz4";
1019 };
1020
1021The entry will then contain the compressed data, using the 'lz4' compression
1022algorithm. Currently this is the only one that is supported. The uncompressed
1023size is written to the node in an 'uncomp-size' property, if -u is used.
1024
1025Compression is also supported for sections. In that case the entire section is
1026compressed in one block, including all its contents. This means that accessing
1027an entry from the section required decompressing the entire section. Also, the
1028size of a section indicates the space that it consumes in its parent section
1029(and typically the image). With compression, the section may contain more data,
1030and the uncomp-size property indicates that, as above. The contents of the
1031section is compressed first, before any padding is added. This ensures that the
1032padding itself is not compressed, which would be a waste of time.
1033
1034
1035Automatic .dtsi inclusion
1036-------------------------
1037
1038It is sometimes inconvenient to add a 'binman' node to the .dts file for each
1039board. This can be done by using #include to bring in a common file. Another
1040approach supported by the U-Boot build system is to automatically include
1041a common header. You can then put the binman node (and anything else that is
1042specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
1043file.
1044
1045Binman will search for the following files in arch/<arch>/dts::
1046
1047 <dts>-u-boot.dtsi where <dts> is the base name of the .dts file
1048 <CONFIG_SYS_SOC>-u-boot.dtsi
1049 <CONFIG_SYS_CPU>-u-boot.dtsi
1050 <CONFIG_SYS_VENDOR>-u-boot.dtsi
1051 u-boot.dtsi
1052
1053U-Boot will only use the first one that it finds. If you need to include a
1054more general file you can do that from the more specific file using #include.
Simon Glass0a1b3b62021-12-16 20:59:23 -07001055If you are having trouble figuring out what is going on, you can use
1056`DEVICE_TREE_DEBUG=1` with your build::
Simon Glassfa888282021-03-18 20:25:14 +13001057
Simon Glass0a1b3b62021-12-16 20:59:23 -07001058 make DEVICE_TREE_DEBUG=1
1059 scripts/Makefile.lib:334: Automatic .dtsi inclusion: options:
1060 arch/arm/dts/juno-r2-u-boot.dtsi arch/arm/dts/-u-boot.dtsi
1061 arch/arm/dts/armv8-u-boot.dtsi arch/arm/dts/armltd-u-boot.dtsi
1062 arch/arm/dts/u-boot.dtsi ... found: "arch/arm/dts/juno-r2-u-boot.dtsi"
Simon Glassfa888282021-03-18 20:25:14 +13001063
1064
Simon Glassadfb8492021-11-03 21:09:18 -06001065Updating an ELF file
1066====================
1067
1068For the EFI app, where U-Boot is loaded from UEFI and runs as an app, there is
1069no way to update the devicetree after U-Boot is built. Normally this works by
1070creating a new u-boot.dtb.out with he updated devicetree, which is automatically
1071built into the output image. With ELF this is not possible since the ELF is
1072not part of an image, just a stand-along file. We must create an updated ELF
1073file with the new devicetree.
1074
1075This is handled by the --update-fdt-in-elf option. It takes four arguments,
1076separated by comma:
1077
1078 infile - filename of input ELF file, e.g. 'u-boot's
1079 outfile - filename of output ELF file, e.g. 'u-boot.out'
1080 begin_sym - symbol at the start of the embedded devicetree, e.g.
1081 '__dtb_dt_begin'
1082 end_sym - symbol at the start of the embedded devicetree, e.g.
1083 '__dtb_dt_end'
1084
1085When this flag is used, U-Boot does all the normal packaging, but as an
1086additional step, it creates a new ELF file with the new devicetree embedded in
1087it.
1088
1089If logging is enabled you will see a message like this::
1090
1091 Updating file 'u-boot' with data length 0x400a (16394) between symbols
1092 '__dtb_dt_begin' and '__dtb_dt_end'
1093
1094There must be enough space for the updated devicetree. If not, an error like
1095the following is produced::
1096
1097 ValueError: Not enough space in 'u-boot' for data length 0x400a (16394);
1098 size is 0x1744 (5956)
1099
1100
Simon Glass7a61c6b2018-07-17 13:25:37 -06001101Entry Documentation
Simon Glass774b23f2021-03-18 20:25:17 +13001102===================
Simon Glass7a61c6b2018-07-17 13:25:37 -06001103
1104For details on the various entry types supported by binman and how to use them,
Simon Glass774b23f2021-03-18 20:25:17 +13001105see entries.rst which is generated from the source code using:
1106
1107 binman entry-docs >tools/binman/entries.rst
Simon Glass7a61c6b2018-07-17 13:25:37 -06001108
Simon Glass774b23f2021-03-18 20:25:17 +13001109.. toctree::
1110 :maxdepth: 2
Simon Glass7a61c6b2018-07-17 13:25:37 -06001111
Simon Glass774b23f2021-03-18 20:25:17 +13001112 entries
1113
Simon Glassfa888282021-03-18 20:25:14 +13001114
1115Managing images
1116===============
Simon Glass7a61c6b2018-07-17 13:25:37 -06001117
Simon Glassb2fd11d2019-07-08 14:25:48 -06001118Listing images
1119--------------
1120
1121It is possible to list the entries in an existing firmware image created by
Simon Glass75ead662021-03-18 20:25:13 +13001122binman, provided that there is an 'fdtmap' entry in the image. For example::
Simon Glassb2fd11d2019-07-08 14:25:48 -06001123
1124 $ binman ls -i image.bin
1125 Name Image-pos Size Entry-type Offset Uncomp-size
1126 ----------------------------------------------------------------------
1127 main-section c00 section 0
1128 u-boot 0 4 u-boot 0
1129 section 5fc section 4
1130 cbfs 100 400 cbfs 0
1131 u-boot 138 4 u-boot 38
1132 u-boot-dtb 180 108 u-boot-dtb 80 3b5
1133 u-boot-dtb 500 1ff u-boot-dtb 400 3b5
1134 fdtmap 6fc 381 fdtmap 6fc
1135 image-header bf8 8 image-header bf8
1136
1137This shows the hierarchy of the image, the position, size and type of each
1138entry, the offset of each entry within its parent and the uncompressed size if
1139the entry is compressed.
1140
Simon Glass75ead662021-03-18 20:25:13 +13001141It is also possible to list just some files in an image, e.g.::
Simon Glassb2fd11d2019-07-08 14:25:48 -06001142
1143 $ binman ls -i image.bin section/cbfs
1144 Name Image-pos Size Entry-type Offset Uncomp-size
1145 --------------------------------------------------------------------
1146 cbfs 100 400 cbfs 0
1147 u-boot 138 4 u-boot 38
1148 u-boot-dtb 180 108 u-boot-dtb 80 3b5
1149
Simon Glass75ead662021-03-18 20:25:13 +13001150or with wildcards::
Simon Glassb2fd11d2019-07-08 14:25:48 -06001151
1152 $ binman ls -i image.bin "*cb*" "*head*"
1153 Name Image-pos Size Entry-type Offset Uncomp-size
1154 ----------------------------------------------------------------------
1155 cbfs 100 400 cbfs 0
1156 u-boot 138 4 u-boot 38
1157 u-boot-dtb 180 108 u-boot-dtb 80 3b5
1158 image-header bf8 8 image-header bf8
1159
Simon Glassb9028bc2021-11-23 21:09:49 -07001160If an older version of binman is used to list images created by a newer one, it
1161is possible that it will contain entry types that are not supported. These still
1162show with the correct type, but binman just sees them as blobs (plain binary
1163data). Any special features of that etype are not supported by the old binman.
1164
Simon Glassb2fd11d2019-07-08 14:25:48 -06001165
Simon Glass980a2842019-07-08 14:25:52 -06001166Extracting files from images
1167----------------------------
1168
1169You can extract files from an existing firmware image created by binman,
Simon Glass75ead662021-03-18 20:25:13 +13001170provided that there is an 'fdtmap' entry in the image. For example::
Simon Glass980a2842019-07-08 14:25:52 -06001171
1172 $ binman extract -i image.bin section/cbfs/u-boot
1173
1174which will write the uncompressed contents of that entry to the file 'u-boot' in
1175the current directory. You can also extract to a particular file, in this case
Simon Glass75ead662021-03-18 20:25:13 +13001176u-boot.bin::
Simon Glass980a2842019-07-08 14:25:52 -06001177
1178 $ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin
1179
1180It is possible to extract all files into a destination directory, which will
Simon Glass75ead662021-03-18 20:25:13 +13001181put files in subdirectories matching the entry hierarchy::
Simon Glass980a2842019-07-08 14:25:52 -06001182
1183 $ binman extract -i image.bin -O outdir
1184
Simon Glass75ead662021-03-18 20:25:13 +13001185or just a selection::
Simon Glass980a2842019-07-08 14:25:52 -06001186
1187 $ binman extract -i image.bin "*u-boot*" -O outdir
1188
Simon Glass637958f2021-11-23 21:09:50 -07001189Some entry types have alternative formats, for example fdtmap which allows
1190extracted just the devicetree binary without the fdtmap header::
1191
1192 $ binman extract -i /tmp/b/odroid-c4/image.bin -f out.dtb -F fdt fdtmap
1193 $ fdtdump out.dtb
1194 /dts-v1/;
1195 // magic: 0xd00dfeed
1196 // totalsize: 0x8ab (2219)
1197 // off_dt_struct: 0x38
1198 // off_dt_strings: 0x82c
1199 // off_mem_rsvmap: 0x28
1200 // version: 17
1201 // last_comp_version: 2
1202 // boot_cpuid_phys: 0x0
1203 // size_dt_strings: 0x7f
1204 // size_dt_struct: 0x7f4
1205
1206 / {
1207 image-node = "binman";
1208 image-pos = <0x00000000>;
1209 size = <0x0011162b>;
1210 ...
1211
1212Use `-F list` to see what alternative formats are available::
1213
1214 $ binman extract -i /tmp/b/odroid-c4/image.bin -F list
1215 Flag (-F) Entry type Description
1216 fdt fdtmap Extract the devicetree blob from the fdtmap
1217
Simon Glass980a2842019-07-08 14:25:52 -06001218
Simon Glass072959a2019-07-20 12:23:50 -06001219Replacing files in an image
1220---------------------------
1221
1222You can replace files in an existing firmware image created by binman, provided
Simon Glass31cce972021-11-23 21:09:48 -07001223that there is an 'fdtmap' entry in the image. For example::
Simon Glass072959a2019-07-20 12:23:50 -06001224
1225 $ binman replace -i image.bin section/cbfs/u-boot
1226
1227which will write the contents of the file 'u-boot' from the current directory
Simon Glass30033c22019-07-20 12:24:15 -06001228to the that entry, compressing if necessary. If the entry size changes, you must
1229add the 'allow-repack' property to the original image before generating it (see
1230above), otherwise you will get an error.
Simon Glass072959a2019-07-20 12:23:50 -06001231
Simon Glass75ead662021-03-18 20:25:13 +13001232You can also use a particular file, in this case u-boot.bin::
Simon Glass30033c22019-07-20 12:24:15 -06001233
1234 $ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin
1235
1236It is possible to replace all files from a source directory which uses the same
Simon Glass75ead662021-03-18 20:25:13 +13001237hierarchy as the entries::
Simon Glass30033c22019-07-20 12:24:15 -06001238
1239 $ binman replace -i image.bin -I indir
1240
1241Files that are missing will generate a warning.
1242
Simon Glass75ead662021-03-18 20:25:13 +13001243You can also replace just a selection of entries::
Simon Glass30033c22019-07-20 12:24:15 -06001244
1245 $ binman replace -i image.bin "*u-boot*" -I indir
1246
Simon Glass072959a2019-07-20 12:23:50 -06001247
Simon Glassa9223472022-11-09 19:14:49 -07001248.. _`BinmanLogging`:
1249
Simon Glass233a26a92019-07-08 14:25:49 -06001250Logging
1251-------
1252
1253Binman normally operates silently unless there is an error, in which case it
1254just displays the error. The -D/--debug option can be used to create a full
Simon Glasscaa5f182021-02-06 09:57:28 -07001255backtrace when errors occur. You can use BINMAN_DEBUG=1 when building to select
1256this.
Simon Glass233a26a92019-07-08 14:25:49 -06001257
1258Internally binman logs some output while it is running. This can be displayed
1259by increasing the -v/--verbosity from the default of 1:
1260
1261 0: silent
1262 1: warnings only
1263 2: notices (important messages)
1264 3: info about major operations
1265 4: detailed information about each operation
1266 5: debug (all output)
1267
Simon Glasscaa5f182021-02-06 09:57:28 -07001268You can use BINMAN_VERBOSE=5 (for example) when building to select this.
Simon Glass233a26a92019-07-08 14:25:49 -06001269
Simon Glass72232452016-11-25 20:15:53 -07001270
Simon Glass41424862022-01-09 20:14:12 -07001271Bintools
1272========
1273
1274`Bintool` is the name binman gives to a binary tool which it uses to create and
1275manipulate binaries that binman cannot handle itself. Bintools are often
1276necessary since Binman only supports a subset of the available file formats
1277natively.
1278
1279Many SoC vendors invent ways to load code into their SoC using new file formats,
1280sometimes changing the format with successive SoC generations. Sometimes the
1281tool is available as Open Source. Sometimes it is a pre-compiled binary that
1282must be downloaded from the vendor's website. Sometimes it is available in
1283source form but difficult or slow to build.
1284
1285Even for images that use bintools, binman still assembles the image from its
1286image description. It may handle parts of the image natively and part with
1287various bintools.
1288
1289Binman relies on these tools so provides various features to manage them:
1290
1291- Determining whether the tool is currently installed
1292- Downloading or building the tool
1293- Determining the version of the tool that is installed
1294- Deciding which tools are needed to build an image
1295
1296The Bintool class is an interface to the tool, a thin level of abstration, using
1297Python functions to run the tool for each purpose (e.g. creating a new
1298structure, adding a file to an existing structure) rather than just lists of
1299string arguments.
1300
1301As with external blobs, bintools (which are like 'external' tools) can be
1302missing. When building an image requires a bintool and it is not installed,
1303binman detects this and reports the problem, but continues to build an image.
1304This is useful in CI systems which want to check that everything is correct but
1305don't have access to the bintools.
1306
1307To make this work, all calls to bintools (e.g. with Bintool.run_cmd()) must cope
1308with the tool being missing, i.e. when None is returned, by:
1309
1310- Calling self.record_missing_bintool()
1311- Setting up some fake contents so binman can continue
1312
1313Of course the image will not work, but binman reports which bintools are needed
1314and also provide a way to fetch them.
1315
1316To see the available bintools, use::
1317
1318 binman tool --list
1319
1320To fetch tools which are missing, use::
1321
1322 binman tool --fetch missing
1323
1324You can also use `--fetch all` to fetch all tools or `--fetch <tool>` to fetch
1325a particular tool. Some tools are built from source code, in which case you will
1326need to have at least the `build-essential` and `git` packages installed.
1327
1328Bintool Documentation
1329=====================
1330
1331To provide details on the various bintools supported by binman, bintools.rst is
1332generated from the source code using:
1333
1334 binman bintool-docs >tools/binman/bintools.rst
1335
1336.. toctree::
1337 :maxdepth: 2
1338
1339 bintools
1340
Simon Glassa20c0412022-11-09 19:14:54 -07001341Binman commands and arguments
1342=============================
1343
1344Usage::
1345
1346 binman [-h] [-B BUILD_DIR] [-D] [-H] [--toolpath TOOLPATH] [-T THREADS]
1347 [--test-section-timeout] [-v VERBOSITY] [-V]
1348 {build,bintool-docs,entry-docs,ls,extract,replace,test,tool} ...
1349
1350Binman provides the following commands:
1351
1352- **build** - build images
1353- **bintools-docs** - generate documentation about bintools
1354- **entry-docs** - generate documentation about entry types
1355- **ls** - list an image
1356- **extract** - extract files from an image
1357- **replace** - replace one or more entries in an image
1358- **test** - run tests
1359- **tool** - manage bintools
1360
1361Options:
1362
1363-h, --help
1364 Show help message and exit
1365
1366-B BUILD_DIR, --build-dir BUILD_DIR
1367 Directory containing the build output
1368
1369-D, --debug
1370 Enabling debugging (provides a full traceback on error)
1371
1372-H, --full-help
1373 Display the README file
1374
1375--toolpath TOOLPATH
1376 Add a path to the directories containing tools
1377
1378-T THREADS, --threads THREADS
1379 Number of threads to use (0=single-thread). Note that -T0 is useful for
1380 debugging since everything runs in one thread.
1381
1382-v VERBOSITY, --verbosity VERBOSITY
1383 Control verbosity: 0=silent, 1=warnings, 2=notices, 3=info, 4=detail,
1384 5=debug
1385
1386-V, --version
1387 Show the binman version
1388
1389Test options:
1390
1391--test-section-timeout
1392 Use a zero timeout for section multi-threading (for testing)
1393
1394Commands are described below.
1395
1396binman build
1397------------
1398
1399This builds one or more images using the provided image description.
1400
1401Usage::
1402
1403 binman build [-h] [-a ENTRY_ARG] [-b BOARD] [-d DT] [--fake-dtb]
1404 [--fake-ext-blobs] [--force-missing-bintools FORCE_MISSING_BINTOOLS]
1405 [-i IMAGE] [-I INDIR] [-m] [-M] [-n] [-O OUTDIR] [-p] [-u]
1406 [--update-fdt-in-elf UPDATE_FDT_IN_ELF] [-W]
1407
1408Options:
1409
1410-h, --help
1411 Show help message and exit
1412
1413-a ENTRY_ARG, --entry-arg ENTRY_ARG
1414 Set argument value `arg=value`. See
1415 `Passing command-line arguments to entries`_.
1416
1417-b BOARD, --board BOARD
1418 Board name to build. This can be used instead of `-d`, in which case the
1419 file `u-boot.dtb` is used, within the build directory's board subdirectory.
1420
1421-d DT, --dt DT
1422 Configuration file (.dtb) to use. This must have a top-level node called
1423 `binman`. See `Image description format`_.
1424
1425-i IMAGE, --image IMAGE
1426 Image filename to build (if not specified, build all)
1427
1428-I INDIR, --indir INDIR
1429 Add a path to the list of directories to use for input files. This can be
1430 specified multiple times to add more than one path.
1431
1432-m, --map
1433 Output a map file for each image. See `Map files`_.
1434
1435-M, --allow-missing
1436 Allow external blobs and bintools to be missing. See `External blobs`_.
1437
1438-n, --no-expanded
1439 Don't use 'expanded' versions of entries where available; normally 'u-boot'
1440 becomes 'u-boot-expanded', for example. See `Expanded entries`_.
1441
1442-O OUTDIR, --outdir OUTDIR
1443 Path to directory to use for intermediate and output files
1444
1445-p, --preserve
1446 Preserve temporary output directory even if option -O is not given
1447
1448-u, --update-fdt
1449 Update the binman node with offset/size info. See
1450 `Access to binman entry offsets at run time (fdt)`_.
1451
1452--update-fdt-in-elf UPDATE_FDT_IN_ELF
1453 Update an ELF file with the output dtb. The argument is a string consisting
1454 of four parts, separated by commas. See `Updating an ELF file`_.
1455
1456-W, --ignore-missing
1457 Return success even if there are missing blobs/bintools (requires -M)
1458
1459Options used only for testing:
1460
1461--fake-dtb
1462 Use fake device tree contents
1463
1464--fake-ext-blobs
1465 Create fake ext blobs with dummy content
1466
1467--force-missing-bintools FORCE_MISSING_BINTOOLS
1468 Comma-separated list of bintools to consider missing
1469
1470binman bintool-docs
1471-------------------
1472
1473Usage::
1474
1475 binman bintool-docs [-h]
1476
1477This outputs documentation for the bintools in rST format. See
1478`Bintool Documentation`_.
1479
1480binman entry-docs
1481-----------------
1482
1483Usage::
1484
1485 binman entry-docs [-h]
1486
1487This outputs documentation for the entry types in rST format. See
1488`Entry Documentation`_.
1489
1490binman ls
1491---------
1492
1493Usage::
1494
1495 binman ls [-h] -i IMAGE [paths ...]
1496
1497Positional arguments:
1498
1499paths
1500 Paths within file to list (wildcard)
1501
1502Pptions:
1503
1504-h, --help
1505 show help message and exit
1506
1507-i IMAGE, --image IMAGE
1508 Image filename to list
1509
1510This lists an image, showing its contents. See `Listing images`_.
1511
1512binman extract
1513--------------
1514
1515Usage::
1516
1517 binman extract [-h] [-F FORMAT] -i IMAGE [-f FILENAME] [-O OUTDIR] [-U]
1518 [paths ...]
1519
1520Positional arguments:
1521
1522Paths
1523 Paths within file to extract (wildcard)
1524
1525Options:
1526
1527-h, --help
1528 show help message and exit
1529
1530-F FORMAT, --format FORMAT
1531 Select an alternative format for extracted data
1532
1533-i IMAGE, --image IMAGE
1534 Image filename to extract
1535
1536-f FILENAME, --filename FILENAME
1537 Output filename to write to
1538
1539-O OUTDIR, --outdir OUTDIR
1540 Path to directory to use for output files
1541
1542-U, --uncompressed
1543 Output raw uncompressed data for compressed entries
1544
1545This extracts the contents of entries from an image. See
1546`Extracting files from images`_.
1547
1548binman replace
1549--------------
1550
1551Usage::
1552
1553 binman replace [-h] [-C] -i IMAGE [-f FILENAME] [-F] [-I INDIR] [-m]
1554 [paths ...]
1555
1556Positional arguments:
1557
1558paths
1559 Paths within file to replace (wildcard)
1560
1561Options:
1562
1563-h, --help
1564 show help message and exit
1565
1566-C, --compressed
1567 Input data is already compressed if needed for the entry
1568
1569-i IMAGE, --image IMAGE
1570 Image filename to update
1571
1572-f FILENAME, --filename FILENAME
1573 Input filename to read from
1574
1575-F, --fix-size
1576 Don't allow entries to be resized
1577
1578-I INDIR, --indir INDIR
1579 Path to directory to use for input files
1580
1581-m, --map
1582 Output a map file for the updated image
1583
1584This replaces one or more entries in an existing image. See
1585`Replacing files in an image`_.
1586
1587binman test
1588-----------
1589
1590Usage::
1591
1592 binman test [-h] [-P PROCESSES] [-T] [-X] [tests ...]
1593
1594Positional arguments:
1595
1596tests
1597 Test names to run (omit for all)
1598
1599Options:
1600
1601-h, --help
1602 show help message and exit
1603
1604-P PROCESSES, --processes PROCESSES
1605 set number of processes to use for running tests. This defaults to the
1606 number of CPUs on the machine
1607
1608-T, --test-coverage
1609 run tests and check for 100% coverage
1610
1611-X, --test-preserve-dirs
1612 Preserve and display test-created input directories; also preserve the
1613 output directory if a single test is run (pass test name at the end of the
1614 command line
1615
1616binman tool
1617-----------
1618
1619Usage::
1620
1621 binman tool [-h] [-l] [-f] [bintools ...]
1622
1623Positional arguments:
1624
1625bintools
1626 Bintools to process
1627
1628Options:
1629
1630-h, --help
1631 show help message and exit
1632
1633-l, --list
1634 List all known bintools
1635
1636-f, --fetch
1637 Fetch a bintool from a known location. Use `all` to fetch all and `missing`
1638 to fetch any missing tools.
1639
Simon Glass41424862022-01-09 20:14:12 -07001640
Simon Glassfa888282021-03-18 20:25:14 +13001641Technical details
1642=================
Simon Glass72232452016-11-25 20:15:53 -07001643
Simon Glass2574ef62016-11-25 20:15:51 -07001644Order of image creation
1645-----------------------
1646
1647Image creation proceeds in the following order, for each entry in the image.
1648
Simon Glasse22f8fa2018-07-06 10:27:41 -060016491. AddMissingProperties() - binman can add calculated values to the device
Simon Glasse8561af2018-08-01 15:22:37 -06001650tree as part of its processing, for example the offset and size of each
Simon Glasse22f8fa2018-07-06 10:27:41 -06001651entry. This method adds any properties associated with this, expanding the
1652device tree as needed. These properties can have placeholder values which are
1653set later by SetCalculatedProperties(). By that stage the size of sections
1654cannot be changed (since it would cause the images to need to be repacked),
1655but the correct values can be inserted.
1656
16572. ProcessFdt() - process the device tree information as required by the
Simon Glass92307732018-07-06 10:27:40 -06001658particular entry. This may involve adding or deleting properties. If the
1659processing is complete, this method should return True. If the processing
1660cannot complete because it needs the ProcessFdt() method of another entry to
1661run first, this method should return False, in which case it will be called
1662again later.
1663
Simon Glasse22f8fa2018-07-06 10:27:41 -060016643. GetEntryContents() - the contents of each entry are obtained, normally by
Simon Glass2574ef62016-11-25 20:15:51 -07001665reading from a file. This calls the Entry.ObtainContents() to read the
1666contents. The default version of Entry.ObtainContents() calls
1667Entry.GetDefaultFilename() and then reads that file. So a common mechanism
1668to select a file to read is to override that function in the subclass. The
1669functions must return True when they have read the contents. Binman will
1670retry calling the functions a few times if False is returned, allowing
1671dependencies between the contents of different entries.
1672
Simon Glasse8561af2018-08-01 15:22:37 -060016734. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can
Simon Glass2574ef62016-11-25 20:15:51 -07001674return a dict containing entries that need updating. The key should be the
Simon Glasse8561af2018-08-01 15:22:37 -06001675entry name and the value is a tuple (offset, size). This allows an entry to
1676provide the offset and size for other entries. The default implementation
1677of GetEntryOffsets() returns {}.
Simon Glass2574ef62016-11-25 20:15:51 -07001678
Simon Glasse8561af2018-08-01 15:22:37 -060016795. PackEntries() - calls Entry.Pack() which figures out the offset and
1680size of an entry. The 'current' image offset is passed in, and the function
1681returns the offset immediately after the entry being packed. The default
Simon Glass2574ef62016-11-25 20:15:51 -07001682implementation of Pack() is usually sufficient.
1683
Simon Glass2d9570d2020-10-26 17:40:22 -06001684Note: for sections, this also checks that the entries do not overlap, nor extend
1685outside the section. If the section does not have a defined size, the size is
1686set large enough to hold all the entries.
Simon Glass2574ef62016-11-25 20:15:51 -07001687
Simon Glass2d9570d2020-10-26 17:40:22 -060016886. SetImagePos() - sets the image position of every entry. This is the absolute
Simon Glass4b05b2d2019-07-20 12:23:52 -06001689position 'image-pos', as opposed to 'offset' which is relative to the containing
1690section. This must be done after all offsets are known, which is why it is quite
1691late in the ordering.
1692
Simon Glass2d9570d2020-10-26 17:40:22 -060016937. SetCalculatedProperties() - update any calculated properties in the device
Simon Glasse8561af2018-08-01 15:22:37 -06001694tree. This sets the correct 'offset' and 'size' vaues, for example.
Simon Glasse22f8fa2018-07-06 10:27:41 -06001695
Simon Glass2d9570d2020-10-26 17:40:22 -060016968. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
Simon Glass2574ef62016-11-25 20:15:51 -07001697The default implementatoin does nothing. This can be overriden to adjust the
1698contents of an entry in some way. For example, it would be possible to create
1699an entry containing a hash of the contents of some other entries. At this
Simon Glasse61b6f62019-07-08 14:25:37 -06001700stage the offset and size of entries should not be adjusted unless absolutely
1701necessary, since it requires a repack (going back to PackEntries()).
Simon Glass2574ef62016-11-25 20:15:51 -07001702
Simon Glass2d9570d2020-10-26 17:40:22 -060017039. ResetForPack() - if the ProcessEntryContents() step failed, in that an entry
Simon Glass4b05b2d2019-07-20 12:23:52 -06001704has changed its size, then there is no alternative but to go back to step 5 and
1705try again, repacking the entries with the updated size. ResetForPack() removes
1706the fixed offset/size values added by binman, so that the packing can start from
1707scratch.
1708
Simon Glass2d9570d2020-10-26 17:40:22 -0600170910. WriteSymbols() - write the value of symbols into the U-Boot SPL binary.
Simon Glasse8561af2018-08-01 15:22:37 -06001710See 'Access to binman entry offsets at run time' below for a description of
Simon Glass29dae672018-07-06 10:27:39 -06001711what happens in this stage.
Simon Glassbe83bc72017-11-13 18:55:05 -07001712
Simon Glass2d9570d2020-10-26 17:40:22 -0600171311. BuildImage() - builds the image and writes it to a file
Simon Glass4b05b2d2019-07-20 12:23:52 -06001714
Simon Glass2d9570d2020-10-26 17:40:22 -0600171512. WriteMap() - writes a text file containing a map of the image. This is the
Simon Glass4b05b2d2019-07-20 12:23:52 -06001716final step.
Simon Glass2574ef62016-11-25 20:15:51 -07001717
1718
Simon Glassa9223472022-11-09 19:14:49 -07001719.. _`External tools`:
1720
Simon Glass6244fa42019-07-08 13:18:28 -06001721External tools
1722--------------
1723
1724Binman can make use of external command-line tools to handle processing of
1725entry contents or to generate entry contents. These tools are executed using
1726the 'tools' module's Run() method. The tools generally must exist on the PATH,
1727but the --toolpath option can be used to specify additional search paths to
1728use. This option can be specified multiple times to add more than one path.
1729
Alper Nebi Yasakfb4e5382020-09-06 14:46:07 +03001730For some compile tools binman will use the versions specified by commonly-used
1731environment variables like CC and HOSTCC for the C compiler, based on whether
1732the tool's output will be used for the target or for the host machine. If those
1733aren't given, it will also try to derive target-specific versions from the
1734CROSS_COMPILE environment variable during a cross-compilation.
1735
Simon Glass31cce972021-11-23 21:09:48 -07001736If the tool is not available in the path you can use BINMAN_TOOLPATHS to specify
1737a space-separated list of paths to search, e.g.::
1738
1739 BINMAN_TOOLPATHS="/tools/g12a /tools/tegra" binman ...
1740
1741
Simon Glassa9223472022-11-09 19:14:49 -07001742.. _`External blobs`:
1743
Simon Glass31cce972021-11-23 21:09:48 -07001744External blobs
1745--------------
1746
1747Binary blobs, even if the source code is available, complicate building
1748firmware. The instructions can involve multiple steps and the binaries may be
1749hard to build or obtain. Binman at least provides a unified description of how
1750to build the final image, no matter what steps are needed to get there.
1751
1752Binman also provides a `blob-ext` entry type that pulls in a binary blob from an
1753external file. If the file is missing, binman can optionally complete the build
1754and just report a warning. Use the `-M/--allow-missing` option to enble this.
1755This is useful in CI systems which want to check that everything is correct but
1756don't have access to the blobs.
1757
1758If the blobs are in a different directory, you can specify this with the `-I`
1759option.
1760
1761For U-Boot, you can use set the BINMAN_INDIRS environment variable to provide a
1762space-separated list of directories to search for binary blobs::
1763
1764 BINMAN_INDIRS="odroid-c4/fip/g12a \
1765 odroid-c4/build/board/hardkernel/odroidc4/firmware \
1766 odroid-c4/build/scp_task" binman ...
Simon Glass6244fa42019-07-08 13:18:28 -06001767
Simon Glass6bce5dc2022-11-09 19:14:42 -07001768Note that binman fails with exit code 103 when there are missing blobs. If you
1769wish binman to continue anyway, you can pass `-W` to binman.
1770
1771
Simon Glass52debad2016-11-25 20:15:59 -07001772Code coverage
1773-------------
1774
1775Binman is a critical tool and is designed to be very testable. Entry
Simon Glassf46732a2019-07-08 14:25:29 -06001776implementations target 100% test coverage. Run 'binman test -T' to check this.
Simon Glass52debad2016-11-25 20:15:59 -07001777
Simon Glass75ead662021-03-18 20:25:13 +13001778To enable Python test coverage on Debian-type distributions (e.g. Ubuntu)::
Simon Glass52debad2016-11-25 20:15:59 -07001779
Simon Glassa16dd6e2019-07-08 13:18:26 -06001780 $ sudo apt-get install python-coverage python3-coverage python-pytest
Simon Glass52debad2016-11-25 20:15:59 -07001781
1782
Simon Glass6bce5dc2022-11-09 19:14:42 -07001783Exit status
1784-----------
1785
1786Binman produces the following exit codes:
1787
17880
1789 Success
1790
17911
1792 Any sort of failure - see output for more details
1793
1794103
1795 There are missing external blobs or bintools. This is only returned if
1796 -M is passed to binman, otherwise missing blobs return an exit status of 1.
1797 Note, if -W is passed as well as -M, then this is converted into a warning
1798 and will return an exit status of 0 instead.
1799
1800
Simon Glassa9223472022-11-09 19:14:49 -07001801U-Boot environment variables for binman
1802---------------------------------------
1803
1804The U-Boot Makefile supports various environment variables to control binman.
1805All of these are set within the Makefile and result in passing various
1806environment variables (or make flags) to binman:
1807
1808BINMAN_DEBUG
1809 Enables backtrace debugging by adding a `-D` argument. See
1810 :ref:`BinmanLogging`.
1811
1812BINMAN_INDIRS
1813 Sets the search path for input files used by binman by adding one or more
1814 `-I` arguments. See :ref:`External blobs`.
1815
1816BINMAN_TOOLPATHS
1817 Sets the search path for external tool used by binman by adding one or more
1818 `--toolpath` arguments. See :ref:`External tools`.
1819
1820BINMAN_VERBOSE
1821 Sets the logging verbosity of binman by adding a `-v` argument. See
1822 :ref:`BinmanLogging`.
1823
1824
Simon Glassddd5e1d2022-01-23 12:55:46 -07001825Error messages
1826--------------
1827
1828This section provides some guidance for some of the less obvious error messages
1829produced by binman.
1830
1831
1832Expected __bss_size symbol
1833~~~~~~~~~~~~~~~~~~~~~~~~~~
1834
1835Example::
1836
1837 binman: Node '/binman/u-boot-spl-ddr/u-boot-spl/u-boot-spl-bss-pad':
1838 Expected __bss_size symbol in spl/u-boot-spl
1839
1840This indicates that binman needs the `__bss_size` symbol to be defined in the
1841SPL binary, where `spl/u-boot-spl` is the ELF file containing the symbols. The
1842symbol tells binman the size of the BSS region, in bytes. It needs this to be
1843able to pad the image so that the following entries do not overlap the BSS,
1844which would cause them to be overwritte by variable access in SPL.
1845
1846This symbols is normally defined in the linker script, immediately after
1847_bss_start and __bss_end are defined, like this::
1848
1849 __bss_size = __bss_end - __bss_start;
1850
1851You may need to add it to your linker script if you get this error.
1852
1853
Simon Glass1aeb7512019-05-17 22:00:52 -06001854Concurrent tests
1855----------------
1856
1857Binman tries to run tests concurrently. This means that the tests make use of
1858all available CPUs to run.
1859
Simon Glass75ead662021-03-18 20:25:13 +13001860 To enable this::
Simon Glass1aeb7512019-05-17 22:00:52 -06001861
1862 $ sudo apt-get install python-subunit python3-subunit
1863
1864Use '-P 1' to disable this. It is automatically disabled when code coverage is
1865being used (-T) since they are incompatible.
1866
1867
Simon Glass1c420c92019-07-08 13:18:49 -06001868Debugging tests
1869---------------
1870
1871Sometimes when debugging tests it is useful to keep the input and output
1872directories so they can be examined later. Use -X or --test-preserve-dirs for
1873this.
1874
1875
Alper Nebi Yasakfb4e5382020-09-06 14:46:07 +03001876Running tests on non-x86 architectures
1877--------------------------------------
1878
1879Binman's tests have been written under the assumption that they'll be run on a
1880x86-like host and there hasn't been an attempt to make them portable yet.
1881However, it's possible to run the tests by cross-compiling to x86.
1882
Simon Glass75ead662021-03-18 20:25:13 +13001883To install an x86 cross-compiler on Debian-type distributions (e.g. Ubuntu)::
Alper Nebi Yasakfb4e5382020-09-06 14:46:07 +03001884
1885 $ sudo apt-get install gcc-x86-64-linux-gnu
1886
Simon Glass75ead662021-03-18 20:25:13 +13001887Then, you can run the tests under cross-compilation::
Alper Nebi Yasakfb4e5382020-09-06 14:46:07 +03001888
1889 $ CROSS_COMPILE=x86_64-linux-gnu- binman test -T
1890
1891You can also use gcc-i686-linux-gnu similar to the above.
1892
1893
Simon Glassfa888282021-03-18 20:25:14 +13001894Writing new entries and debugging
1895---------------------------------
Simon Glass2574ef62016-11-25 20:15:51 -07001896
1897The behaviour of entries is defined by the Entry class. All other entries are
1898a subclass of this. An important subclass is Entry_blob which takes binary
1899data from a file and places it in the entry. In fact most entry types are
1900subclasses of Entry_blob.
1901
1902Each entry type is a separate file in the tools/binman/etype directory. Each
1903file contains a class called Entry_<type> where <type> is the entry type.
1904New entry types can be supported by adding new files in that directory.
1905These will automatically be detected by binman when needed.
1906
1907Entry properties are documented in entry.py. The entry subclasses are free
1908to change the values of properties to support special behaviour. For example,
1909when Entry_blob loads a file, it sets content_size to the size of the file.
1910Entry classes can adjust other entries. For example, an entry that knows
Simon Glasse8561af2018-08-01 15:22:37 -06001911where other entries should be positioned can set up those entries' offsets
Simon Glass2574ef62016-11-25 20:15:51 -07001912so they don't need to be set in the binman decription. It can also adjust
1913entry contents.
1914
1915Most of the time such essoteric behaviour is not needed, but it can be
1916essential for complex images.
1917
Simon Glassade2ef62017-12-24 12:12:07 -07001918If you need to specify a particular device-tree compiler to use, you can define
1919the DTC environment variable. This can be useful when the system dtc is too
1920old.
1921
Simon Glasse64a0922018-11-06 15:21:31 -07001922To enable a full backtrace and other debugging features in binman, pass
Simon Glass75ead662021-03-18 20:25:13 +13001923BINMAN_DEBUG=1 to your build::
Simon Glasse64a0922018-11-06 15:21:31 -07001924
Bin Menga089c412019-10-02 19:07:29 -07001925 make qemu-x86_defconfig
Simon Glasse64a0922018-11-06 15:21:31 -07001926 make BINMAN_DEBUG=1
1927
Simon Glass03b1d8f2019-09-25 08:11:11 -06001928To enable verbose logging from binman, base BINMAN_VERBOSE to your build, which
Simon Glass75ead662021-03-18 20:25:13 +13001929adds a -v<level> option to the call to binman::
Simon Glass03b1d8f2019-09-25 08:11:11 -06001930
Bin Menga089c412019-10-02 19:07:29 -07001931 make qemu-x86_defconfig
Simon Glass03b1d8f2019-09-25 08:11:11 -06001932 make BINMAN_VERBOSE=5
1933
Simon Glass2574ef62016-11-25 20:15:51 -07001934
Simon Glass76f496d2021-07-06 10:36:37 -06001935Building sections in parallel
1936-----------------------------
1937
1938By default binman uses multiprocessing to speed up compilation of large images.
1939This works at a section level, with one thread for each entry in the section.
1940This can speed things up if the entries are large and use compression.
1941
1942This feature can be disabled with the '-T' flag, which defaults to a suitable
1943value for your machine. This depends on the Python version, e.g on v3.8 it uses
194412 threads on an 8-core machine. See ConcurrentFutures_ for more details.
1945
1946The special value -T0 selects single-threaded mode, useful for debugging during
1947development, since dealing with exceptions and problems in threads is more
1948difficult. This avoids any use of ThreadPoolExecutor.
1949
1950
Simon Glass6fba35c2022-02-08 11:50:00 -07001951Collecting data for an entry type
1952---------------------------------
1953
1954Some entry types deal with data obtained from others. For example,
1955`Entry_mkimage` calls the `mkimage` tool with data from its subnodes::
1956
1957 mkimage {
1958 args = "-n test -T script";
1959
1960 u-boot-spl {
1961 };
1962
1963 u-boot {
1964 };
1965 };
1966
1967This shows mkimage being passed a file consisting of SPL and U-Boot proper. It
Simon Glass43a98cc2022-03-05 20:18:58 -07001968is created by calling `Entry.collect_contents_to_file()`. Note that in this
1969case, the data is passed to mkimage for processing but does not appear
1970separately in the image. It may not appear at all, depending on what mkimage
1971does. The contents of the `mkimage` entry are entirely dependent on the
1972processing done by the entry, with the provided subnodes (`u-boot-spl` and
1973`u-boot`) simply providing the input data for that processing.
Simon Glass6fba35c2022-02-08 11:50:00 -07001974
1975Note that `Entry.collect_contents_to_file()` simply concatenates the data from
1976the different entries together, with no control over alignment, etc. Another
1977approach is to subclass `Entry_section` so that those features become available,
1978such as `size` and `pad-byte`. Then the contents of the entry can be obtained by
Simon Glass43a98cc2022-03-05 20:18:58 -07001979calling `super().BuildSectionData()` in the entry's BuildSectionData()
1980implementation to get the input data, then write it to a file and process it
1981however is desired.
Simon Glass6fba35c2022-02-08 11:50:00 -07001982
1983There are other ways to obtain data also, depending on the situation. If the
1984entry type is simply signing data which exists elsewhere in the image, then
1985you can use `Entry_collection` as a base class. It lets you use a property
1986called `content` which lists the entries containing data to be processed. This
1987is used by `Entry_vblock`, for example::
1988
1989 u_boot: u-boot {
1990 };
Simon Glass43a98cc2022-03-05 20:18:58 -07001991
Simon Glass6fba35c2022-02-08 11:50:00 -07001992 vblock {
1993 content = <&u_boot &dtb>;
1994 keyblock = "firmware.keyblock";
1995 signprivate = "firmware_data_key.vbprivk";
1996 version = <1>;
1997 kernelkey = "kernel_subkey.vbpubk";
1998 preamble-flags = <1>;
1999 };
2000
2001 dtb: u-boot-dtb {
2002 };
2003
2004which shows an image containing `u-boot` and `u-boot-dtb`, with the `vblock`
2005image collecting their contents to produce input for its signing process,
2006without affecting those entries, which still appear in the final image
2007untouched.
2008
2009Another example is where an entry type needs several independent pieces of input
2010to function. For example, `Entry_fip` allows a number of different binary blobs
2011to be placed in their own individual places in a custom data structure in the
2012output image. To make that work you can add subnodes for each of them and call
2013`Entry.Create()` on each subnode, as `Entry_fip` does. Then the data for each
2014blob can come from any suitable place, such as an `Entry_u_boot` or an
2015`Entry_blob` or anything else::
2016
2017 atf-fip {
2018 fip-hdr-flags = /bits/ 64 <0x123>;
2019 soc-fw {
2020 fip-flags = /bits/ 64 <0x123456789abcdef>;
2021 filename = "bl31.bin";
2022 };
2023
2024 u-boot {
2025 fip-uuid = [fc 65 13 92 4a 5b 11 ec
2026 94 35 ff 2d 1c fc 79 9c];
2027 };
2028 };
2029
2030The `soc-fw` node is a `blob-ext` (i.e. it reads in a named binary file) whereas
2031`u-boot` is a normal entry type. This works because `Entry_fip` selects the
2032`blob-ext` entry type if the node name (here `soc-fw`) is recognised as being
2033a known blob type.
2034
2035When adding new entry types you are encouraged to use subnodes to provide the
Simon Glass43a98cc2022-03-05 20:18:58 -07002036data for processing, unless the `content` approach is more suitable. Consider
2037whether the input entries are contained within (or consumed by) the entry, vs
2038just being 'referenced' by the entry. In the latter case, the `content` approach
2039makes more sense. Ad-hoc properties and other methods of obtaining data are
2040discouraged, since it adds to confusion for users.
Simon Glass6fba35c2022-02-08 11:50:00 -07002041
Simon Glass2574ef62016-11-25 20:15:51 -07002042History / Credits
2043-----------------
2044
2045Binman takes a lot of inspiration from a Chrome OS tool called
2046'cros_bundle_firmware', which I wrote some years ago. That tool was based on
2047a reasonably simple and sound design but has expanded greatly over the
2048years. In particular its handling of x86 images is convoluted.
2049
Simon Glass1e324002018-06-01 09:38:19 -06002050Quite a few lessons have been learned which are hopefully applied here.
Simon Glass2574ef62016-11-25 20:15:51 -07002051
2052
2053Design notes
2054------------
2055
2056On the face of it, a tool to create firmware images should be fairly simple:
2057just find all the input binaries and place them at the right place in the
2058image. The difficulty comes from the wide variety of input types (simple
2059flat binaries containing code, packaged data with various headers), packing
2060requirments (alignment, spacing, device boundaries) and other required
2061features such as hierarchical images.
2062
2063The design challenge is to make it easy to create simple images, while
2064allowing the more complex cases to be supported. For example, for most
2065images we don't much care exactly where each binary ends up, so we should
2066not have to specify that unnecessarily.
2067
2068New entry types should aim to provide simple usage where possible. If new
2069core features are needed, they can be added in the Entry base class.
2070
2071
2072To do
2073-----
2074
2075Some ideas:
Simon Glass75ead662021-03-18 20:25:13 +13002076
Simon Glass2574ef62016-11-25 20:15:51 -07002077- Use of-platdata to make the information available to code that is unable
Simon Glass774b23f2021-03-18 20:25:17 +13002078 to use device tree (such as a very small SPL image). For now, limited info is
2079 available via linker symbols
Simon Glass2574ef62016-11-25 20:15:51 -07002080- Allow easy building of images by specifying just the board name
Simon Glass2574ef62016-11-25 20:15:51 -07002081- Support building an image for a board (-b) more completely, with a
2082 configurable build directory
Simon Glass8100a8e2019-07-20 12:24:02 -06002083- Detect invalid properties in nodes
2084- Sort the fdtmap by offset
Simon Glass01ab2292021-01-06 21:35:12 -07002085- Output temporary files to a different directory
Simon Glasse87009da2022-02-08 11:49:57 -07002086- Rationalise the fdt, fdt_util and pylibfdt modules which currently have some
2087 overlapping and confusing functionality
2088- Update the fdt library to use a better format for Prop.value (the current one
2089 is useful for dtoc but not much else)
2090- Figure out how to make Fdt support changing the node order, so that
2091 Node.AddSubnode() can support adding a node before another, existing node.
2092 Perhaps it should completely regenerate the flat tree?
Simon Glassfca38562022-08-18 02:16:46 -06002093- Support images which depend on each other
Simon Glass2574ef62016-11-25 20:15:51 -07002094
2095--
2096Simon Glass <sjg@chromium.org>
20977/7/2016
Simon Glass76f496d2021-07-06 10:36:37 -06002098
2099.. _ConcurrentFutures: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor