Lines Matching +full:build +full:- +full:without +full:- +full:defaults
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 ------------
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:
290 offset the entry contents a little. Defaults to 0.
292 pad-after:
296 this entry to expand later. Defaults to 0.
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.
316 Sets the type of an entry. This defaults to the entry name, but it is
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:
352 be positioned after the padding. This defaults to 0.
354 pad-after:
356 placed after the last entry. This defaults to 0.
358 pad-byte:
360 defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
363 This specifies the image filename. It defaults to 'image.bin'.
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
529 4. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can
535 5. PackEntries() - calls Entry.Pack() which figures out the offset and
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.
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
699 ----------------------------------
722 If you need to specify a particular device-tree compiler to use, you can define
727 BINMAN_DEBUG=1 to your build:
734 -----------------
745 ------------
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 --