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
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 ------------
29 Features
30 --------
32 So far binman is pretty simple. It supports binary blobs, such as 'u-boot',
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
67 standard format, we can support making valid images for any board without
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
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
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
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.
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.
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
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:
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:
402 	this option, instead of 0 without this option.
404 skip-at-start:
411 	'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
418 either by using a unit number suffix (u-boot@0, u-boot@1) or by using a
423 -------------------------------
427 the image is read-only and part is read-write. We can set up sections for each
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
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 -------------------
475 	binman -E >tools/binman/README.entries
479 ---------------
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
501 -----------------------
505 1. AddMissingProperties() - binman can add calculated values to the device
513 2. ProcessFdt() - process the device tree information as required by the
520 3. GetEntryContents() - the contents of each entry are obtained, normally by
522 contents. The default version of Entry.ObtainContents() calls
529 4. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can
532 provide the offset and size for other entries. The default implementation
535 5. PackEntries() - calls Entry.Pack() which figures out the offset and
537 returns the offset immediately after the entry being packed. The default
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
550 9. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
551 The default implementatoin does nothing. This can be overriden to adjust the
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
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
593 ----------------------------------------------------
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
627 the device tree. These can be used by U-Boot at run-time to find the location
632 -----------
648 ---------
650 The -m option causes binman to output a .map file for each image that it
654     00000000  00000028  main-section
656       00000000  00000004  u-boot
658       00000000  00000004  u-boot
667 Passing command-line arguments to entries
668 -----------------------------------------
674 The-a option supports this:
676     -a<prop>=<value>
688 -------------
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 ----------------------------------
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 -----------------
745 ------------
752 features such as hierarchical images.
760 core features are needed, they can be added in the Entry base class.
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 --