README - OpenGrok cross reference for /openbmc/u-boot/tools/binman/README

1 # SPDX-License-Identifier: GPL-2.0+
5 ------------
8 For example, we may have SPL, U-Boot, a device tree and an environment area
9 grouped together and placed in MMC flash. When the system starts, it must be
12 So far U-Boot has not provided a way to handle creating such images in a
13 general way. Each SoC does what it needs to build an image, often packing or
14 concatenating images in the U-Boot build system.
17 SPL + U-Boot combinations, to more complex arrangements with many parts.
21 ------------
23 Binman reads your board's device tree and finds a node which describes the
26 to read an image and extract its constituent parts.
30 --------
32 So far binman is pretty simple. It supports binary blobs, such as 'u-boot',
33 'spl' and 'fdt'. It supports empty entries (such as setting to 0xff). It can
35 suitable padding and alignment. It provides a way to process binaries before
36 they are included, by adding a Python plug-in. The device tree is available
37 to U-Boot at run-time so that the images can be interpreted.
47 Binman is intended for use with U-Boot but is designed to be general enough
48 to be useful in other image-packaging situations.
52 ----------
56 separate build systems. For example, ARM Trusted Firmware is used on ARMv8
57 devices but is not built in the U-Boot tree. If a Linux kernel is included
60 It is of course possible to add more and more build rules to the U-Boot
61 build system to cover these cases. It can shell out to other Makefiles and
62 build scripts. But it seems better to create a clear divide between building
63 software and packaging it.
71 - Each binary can have its own build system and tool chain without creating
73 - Avoids the need for a single-shot build: individual parts can be updated
74 and brought in as needed
75 - Provides for a standard image description available in the build and at
76 run-time
77 - SoC-specific image-signing tools can be accomodated
78 - Avoids cluttering the U-Boot build system with image-building code
79 - The image description is automatically available at run-time in U-Boot,
81 - The image description is easily readable (it's a text file in device-tree
82 format) and permits flexible packing of binaries
86 -----------
90 - image - an output file containing a firmware image
91 - binary - an input binary that goes into the image
95 -------------------
97 FIT is U-Boot's official image format. It supports multiple binaries with
99 through hashing and RSA signatures.
102 optional ramdisk) and device tree chosen from various options in the FIT.
103 Now that U-Boot supports configuration via device tree, it is possible to
104 load U-Boot from a FIT, with the device tree chosen by SPL.
110 execution (since FIT itself does not have an executable header) and dealing
111 with device boundaries, such as the read-only/read-write separation in SPI
114 For U-Boot, binman should not be used to create ad-hoc images in place of
119 -----------------------
123 different format. More recently it has started to support a '-f auto' mode
126 More relevant to binman, mkimage also permits creation of many SoC-specific
127 image types. These can be listed by running 'mkimage -T list'. Examples
129 called from the U-Boot build system for this reason.
135 seems better to use the mkimage tool to generate binaries and avoid blurring
136 the boundaries between building input files (mkimage) and packaging then
140 Example use of binman in U-Boot
141 -------------------------------
143 Binman aims to replace some of the ad-hoc image creation in the U-Boot
144 build system.
148 1. It uses a custom mksunxiboot tool to build an SPL image called
149 sunxi-spl.bin. This should probably move into mkimage.
151 2. It uses mkimage to package U-Boot into a legacy image file (so that it can
152 hold the load and execution address) called u-boot.img.
154 3. It builds a final output image called u-boot-sunxi-with-spl.bin which
155 consists of sunxi-spl.bin, some padding and u-boot.img.
157 Binman is intended to replace the last step. The U-Boot build system builds
158 u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
159 sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any
162 This simplifies the U-Boot Makefile somewhat, since various pieces of logic
167 -----------------------------
169 In most cases x86 images have a lot of binary blobs, 'black-box' code
171 these blobs are not relocatable and must be placed at fixed areas in the
175 BIOS, reference code and Intel ME binaries into a u-boot.rom file.
178 the configuration of the Intel-format descriptor.
182 --------------
186 	binman -b <board_name>
188 to build an image for a board. The board name is the same name used when
189 configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
190 Binman assumes that the input files for the build are in ../b/<board_name>.
194 	binman -I <build_path>
196 where <build_path> is the build directory containing the output of the U-Boot
197 build.
201 In either case, binman picks up the device tree file (u-boot.dtb) and looks
204 Binman has a few other options which you can see by running 'binman -h'.
208 ---------------------------
214 u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
218 This assumes that u-boot-<your_suffix>.bin is a target, and is the final file
219 that you need to produce. You can make it a target by adding it to ALL-y
222 Once binman is executed it will pick up its instructions from a device-tree
223 file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value.
224 You can use other, more specific CONFIG options - see 'Automatic .dtsi
229 ------------------------
235 		filename = "u-boot-sunxi-with-spl.bin";
236 		pad-byte = <0xff>;
238 			filename = "spl/sunxi-spl.bin";
240 		u-boot {
246 This requests binman to create an image file called u-boot-sunxi-with-spl.bin
247 consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the
248 normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The
250 CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would
253 The binman node describes an image. The sub-nodes describe entries in the
255 the entry (blob, u-boot) tells binman what to put there. For 'blob' we must
256 provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'.
278 	example 'align = <16>' means that the entry will start on a 16-byte
287 pad-before:
292 pad-after:
298 align-size:
301 	If 'align-size' is not provided, no alignment is performed.
303 align-end:
308 	at the end. If 'align-end' is not provided, no alignment is performed.
313 	u-boot-bin), then there is no need to specify this.
317 	possible to use any name, and then add (for example) 'type = "u-boot"'
320 offset-unset:
327 image-pos:
329 	with the -u option, binman will set it to the absolute image position
333 expand-size:
335 	limited by the size of the image/section and the position of the next
338 The attributes supported for images and sections are described below. Several
345 align-size:
347 	that the image ends on a 512-byte boundary, use 'align-size = <512>'.
348 	If 'align-size' is not provided, no alignment is performed.
350 pad-before:
354 pad-after:
358 pad-byte:
360 	defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
365 sort-by-offset:
373 	line 'sort-by-offset;' to your description.
375 multiple-images:
378 	create image1.bin containing u-boot.bin, and image2.bin containing
379 	both spl/u-boot-spl.bin and u-boot.bin:
382 		multiple-images;
384 			u-boot {
391 			u-boot {
396 end-at-4gb:
397 	For x86 machines the ROM offsets start just before 4GB and extend
404 skip-at-start:
411 	'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
415 tools/binman/test directory.
418 either by using a unit number suffix (u-boot@0, u-boot@1) or by using a
419 different name for each and specifying the type with the 'type' attribute.
422 Sections and hierachical images
423 -------------------------------
427 the image is read-only and part is read-write. We can set up sections for each
428 of these, and place binaries in them independently. The image is still produced
432 is an example image with two copies of U-Boot. One is read-only (ro), intended
433 to be written only in the factory. Another is read-write (rw), so that it can be
435 and can be programmed:
439 			read-only;
440 			name-prefix = "ro-";
442 			u-boot {
446 			name-prefix = "rw-";
448 			u-boot {
458 read-only:
459 	Indicates that this section is read-only. This has no impact on binman's
462 name-prefix:
464 	section. In the example above, the 'u-boot' binaries which actually be
465 	renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
470 -------------------
472 For details on the various entry types supported by binman and how to use them,
475 	binman -E >tools/binman/README.entries
479 ---------------
481 It is possible to ask binman to hash the contents of an entry and write that
482 value back to the device-tree node. For example:
485 		u-boot {
493 the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole
496 The has value can be chcked at runtime by hashing the data actually read and
501 -----------------------
505 1. AddMissingProperties() - binman can add calculated values to the device
506 tree as part of its processing, for example the offset and size of each
513 2. ProcessFdt() - process the device tree information as required by the
520 3. GetEntryContents() - the contents of each entry are obtained, normally by
523 Entry.GetDefaultFilename() and then reads that file. So a common mechanism
529 4. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can
531 entry name and the value is a tuple (offset, size). This allows an entry to
532 provide the offset and size for other entries. The default implementation
535 5. PackEntries() - calls Entry.Pack() which figures out the offset and
536 size of an entry. The 'current' image offset is passed in, and the function
540 6. CheckSize() - checks that the contents of all the entries fits within
544 7. CheckEntries() - checks that the entries do not overlap, nor extend
547 8. SetCalculatedProperties() - update any calculated properties in the device
548 tree. This sets the correct 'offset' and 'size' vaues, for example.
550 9. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
554 stage the offset and size of entries should not be adjusted.
556 10. WriteSymbols() - write the value of symbols into the U-Boot SPL binary.
560 11. BuildImage() - builds the image and writes it to a file. This is the final
565 -------------------------
569 approach supported by the U-Boot build system is to automatically include
570 a common header. You can then put the binman node (and anything else that is
571 specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
576    <dts>-u-boot.dtsi where <dts> is the base name of the .dts file
577    <CONFIG_SYS_SOC>-u-boot.dtsi
578    <CONFIG_SYS_CPU>-u-boot.dtsi
579    <CONFIG_SYS_VENDOR>-u-boot.dtsi
580    u-boot.dtsi
582 U-Boot will only use the first one that it finds. If you need to include a
588    # This shows all the files that were considered and the one that we chose.
593 ----------------------------------------------------
595 Binman assembles images and determines where each entry is placed in the image.
596 This information may be useful to U-Boot at run time. For example, in SPL it
597 is useful to be able to find the location of U-Boot so that it can be executed
601 with their correct values during the build. For example:
605 declares a ulong value which will be assigned to the offset of any U-Boot
606 image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
611 Thus u_boot_offset will be set to the offset of U-Boot in memory, assuming that
613 that address to start U-Boot.
616 to fill in such symbols in U-Boot proper, as well.
620 ------------------------------------------------
622 Binman can update the U-Boot FDT to include the final position and size of
623 each entry in the images it processes. The option to enable this is -u and it
624 causes binman to make sure that the 'offset', 'image-pos' and 'size' properties
626 the image definition, binman calculates the final values and writes these to
627 the device tree. These can be used by U-Boot at run-time to find the location
632 -----------
634 Binman support compression for 'blob' entries (those of type 'blob' and
648 ---------
650 The -m option causes binman to output a .map file for each image that it
651 generates. This shows the offset and size of each entry. For example:
654     00000000  00000028  main-section
656       00000000  00000004  u-boot
658       00000000  00000004  u-boot
667 Passing command-line arguments to entries
668 -----------------------------------------
671 command line. For example some entries need access to files and it is not
674 The-a option supports this:
676     -a<prop>=<value>
688 -------------
690 Binman is a critical tool and is designed to be very testable. Entry
691 implementations target 100% test coverage. Run 'binman -T' to check this.
693 To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
695    $ sudo apt-get install python-coverage python-pytest
698 Advanced Features / Technical docs
699 ----------------------------------
703 data from a file and places it in the entry. In fact most entry types are
706 Each entry type is a separate file in the tools/binman/etype directory. Each
722 If you need to specify a particular device-tree compiler to use, you can define
726 To enable a full backtrace and other debugging features in binman, pass
727 BINMAN_DEBUG=1 to your build:
734 -----------------
738 a reasonably simple and sound design but has expanded greatly over the
745 ------------
748 just find all the input binaries and place them at the right place in the
751 requirments (alignment, spacing, device boundaries) and other required
764 -----
767 - Use of-platdata to make the information available to code that is unable
769 - Allow easy building of images by specifying just the board name
770 - Produce a full Python binding for libfdt (for upstream). This is nearing
772 - Add an option to decode an image into the constituent binaries
773 - Support building an image for a board (-b) more completely, with a
774   configurable build directory
775 - Consider making binman work with buildman, although if it is used in the
778 --