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

3 # SPDX-License-Identifier:	GPL-2.0+
7 ------------
9 Firmware often consists of several components which must be packaged together.
10 For example, we may have SPL, U-Boot, a device tree and an environment area
14 So far U-Boot has not provided a way to handle creating such images in a
16 concatenating images in the U-Boot build system.
19 SPL + U-Boot combinations, to more complex arrangements with many parts.
23 ------------
32 --------
34 So far binman is pretty simple. It supports binary blobs, such as 'u-boot',
38 they are included, by adding a Python plug-in. The device tree is available
39 to U-Boot at run-time so that the images can be interpreted.
49 Binman is intended for use with U-Boot but is designed to be general enough
50 to be useful in other image-packaging situations.
54 ----------
59 devices but is not built in the U-Boot tree. If a Linux kernel is included
62 It is of course possible to add more and more build rules to the U-Boot
73 - Each binary can have its own build system and tool chain without creating
75 - Avoids the need for a single-shot build: individual parts can be updated
77 - Provides for a standard image description available in the build and at
78 run-time
79 - SoC-specific image-signing tools can be accomodated
80 - Avoids cluttering the U-Boot build system with image-building code
81 - The image description is automatically available at run-time in U-Boot,
83 - The image description is easily readable (it's a text file in device-tree
88 -----------
92 - image - an output file containing a firmware image
93 - binary - an input binary that goes into the image
97 -------------------
99 FIT is U-Boot's official image format. It supports multiple binaries with
105 Now that U-Boot supports configuration via device tree, it is possible to
106 load U-Boot from a FIT, with the device tree chosen by SPL.
113 with device boundaries, such as the read-only/read-write separation in SPI
116 For U-Boot, binman should not be used to create ad-hoc images in place of
121 -----------------------
125 different format. More recently it has started to support a '-f auto' mode
128 More relevant to binman, mkimage also permits creation of many SoC-specific
129 image types. These can be listed by running 'mkimage -T list'. Examples
131 called from the U-Boot build system for this reason.
142 Example use of binman in U-Boot
143 -------------------------------
145 Binman aims to replace some of the ad-hoc image creation in the U-Boot
151 sunxi-spl.bin. This should probably move into mkimage.
153 2. It uses mkimage to package U-Boot into a legacy image file (so that it can
154 hold the load and execution address) called u-boot.img.
156 3. It builds a final output image called u-boot-sunxi-with-spl.bin which
157 consists of sunxi-spl.bin, some padding and u-boot.img.
159 Binman is intended to replace the last step. The U-Boot build system builds
160 u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
161 sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any
164 This simplifies the U-Boot Makefile somewhat, since various pieces of logic
169 -----------------------------
171 In most cases x86 images have a lot of binary blobs, 'black-box' code
177 BIOS, reference code and Intel ME binaries into a u-boot.rom file.
180 the configuration of the Intel-format descriptor.
184 --------------
188 	binman -b <board_name>
191 configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
196 	binman -I <build_path>
198 where <build_path> is the build directory containing the output of the U-Boot
203 In either case, binman picks up the device tree file (u-boot.dtb) and looks
206 Binman has a few other options which you can see by running 'binman -h'.
210 ------------------------
216 		filename = "u-boot-sunxi-with-spl.bin";
217 		pad-byte = <0xff>;
219 			filename = "spl/sunxi-spl.bin";
221 		u-boot {
227 This requests binman to create an image file called u-boot-sunxi-with-spl.bin
228 consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the
229 normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The
231 CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would
234 The binman node describes an image. The sub-nodes describe entries in the
236 the entry (blob, u-boot) tells binman what to put there. For 'blob' we must
237 provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'.
258 	example 'align = <16>' means that the entry will start on a 16-byte
267 pad-before:
272 pad-after:
278 align-size:
281 	If 'align-size' is not provided, no alignment is performed.
283 align-end:
286 	start. If 'align-end' is not provided, no alignment is performed.
293 	u-boot-bin), then there is no need to specify this.
297 	possible to use any name, and then add (for example) 'type = "u-boot"'
308 align-size:
310 	that the image ends on a 512-byte boundary, use 'align-size = <512>'.
311 	If 'align-size' is not provided, no alignment is performed.
313 pad-before:
317 pad-after:
321 pad-byte:
323 	defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
328 sort-by-pos:
336 	line 'sort-by-pos;' to your description.
338 multiple-images:
341 	create image1.bin containing u-boot.bin, and image2.bin containing
342 	both spl/u-boot-spl.bin and u-boot.bin:
345 		multiple-images;
347 			u-boot {
354 			u-boot {
359 end-at-4gb:
373 ------------------
377 u-boot-with-ucode-ptr:
378 	optional-ucode: boolean property to make microcode optional. If the
379 		u-boot.bin image does not include microcode, no error will
384 -----------------------
388 1. GetEntryContents() - the contents of each entry are obtained, normally by
397 2. GetEntryPositions() - calls Entry.GetPositions() for each entry. This can
403 3. PackEntries() - calls Entry.Pack() which figures out the position and
408 4. CheckSize() - checks that the contents of all the entries fits within
412 5. CheckEntries() - checks that the entries do not overlap, nor extend
415 6. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
421 7. BuildImage() - builds the image and writes it to a file. This is the final
426 -------------------------
430 approach supported by the U-Boot build system is to automatically include
432 specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
437    <dts>-u-boot.dtsi where <dts> is the base name of the .dts file
438    <CONFIG_SYS_SOC>-u-boot.dtsi
439    <CONFIG_SYS_CPU>-u-boot.dtsi
440    <CONFIG_SYS_VENDOR>-u-boot.dtsi
441    u-boot.dtsi
443 U-Boot will only use the first one that it finds. If you need to include a
453 -------------
456 implementations target 100% test coverage. Run 'binman -T' to check this.
458 To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
460    $ sudo apt-get install python-pip python-pytest
465 ----------------------------------
490 -----------------
501 ------------
506 flat binaries containing code, packaged data with various headers), packing
520 -----
523 - Fill out the device tree to include the final position and size of each
525 - Use of-platdata to make the information available to code that is unable
527 - Write an image map to a text file
528 - Allow easy building of images by specifying just the board name
529 - Produce a full Python binding for libfdt (for upstream)
530 - Add an option to decode an image into the constituent binaries
531 - Suppoort hierarchical images (packing of binaries into another binary
533 - Support building an image for a board (-b) more completely, with a
535 - Consider making binman work with buildman, although if it is used in the
537 - Implement align-end
539 --