|
|
|
@@ -1,5 +1,5 @@
|
|
|
|
|
# SPDX-License-Identifier: GPL-2.0+
|
|
|
|
|
# Copyright (c) 2016 Google, Inc
|
|
|
|
|
.. SPDX-License-Identifier: GPL-2.0+
|
|
|
|
|
.. Copyright (c) 2016 Google, Inc
|
|
|
|
|
|
|
|
|
|
Introduction
|
|
|
|
|
------------
|
|
|
|
@@ -67,18 +67,19 @@ standard format, we can support making valid images for any board without
|
|
|
|
|
manual effort, lots of READMEs, etc.
|
|
|
|
|
|
|
|
|
|
Benefits:
|
|
|
|
|
- Each binary can have its own build system and tool chain without creating
|
|
|
|
|
any dependencies between them
|
|
|
|
|
- Avoids the need for a single-shot build: individual parts can be updated
|
|
|
|
|
and brought in as needed
|
|
|
|
|
- Provides for a standard image description available in the build and at
|
|
|
|
|
run-time
|
|
|
|
|
- SoC-specific image-signing tools can be accommodated
|
|
|
|
|
- Avoids cluttering the U-Boot build system with image-building code
|
|
|
|
|
- The image description is automatically available at run-time in U-Boot,
|
|
|
|
|
SPL. It can be made available to other software also
|
|
|
|
|
- The image description is easily readable (it's a text file in device-tree
|
|
|
|
|
format) and permits flexible packing of binaries
|
|
|
|
|
|
|
|
|
|
- Each binary can have its own build system and tool chain without creating
|
|
|
|
|
any dependencies between them
|
|
|
|
|
- Avoids the need for a single-shot build: individual parts can be updated
|
|
|
|
|
and brought in as needed
|
|
|
|
|
- Provides for a standard image description available in the build and at
|
|
|
|
|
run-time
|
|
|
|
|
- SoC-specific image-signing tools can be accommodated
|
|
|
|
|
- Avoids cluttering the U-Boot build system with image-building code
|
|
|
|
|
- The image description is automatically available at run-time in U-Boot,
|
|
|
|
|
SPL. It can be made available to other software also
|
|
|
|
|
- The image description is easily readable (it's a text file in device-tree
|
|
|
|
|
format) and permits flexible packing of binaries
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Terminology
|
|
|
|
@@ -144,14 +145,14 @@ build system.
|
|
|
|
|
|
|
|
|
|
Consider sunxi. It has the following steps:
|
|
|
|
|
|
|
|
|
|
1. It uses a custom mksunxiboot tool to build an SPL image called
|
|
|
|
|
sunxi-spl.bin. This should probably move into mkimage.
|
|
|
|
|
#. It uses a custom mksunxiboot tool to build an SPL image called
|
|
|
|
|
sunxi-spl.bin. This should probably move into mkimage.
|
|
|
|
|
|
|
|
|
|
2. It uses mkimage to package U-Boot into a legacy image file (so that it can
|
|
|
|
|
hold the load and execution address) called u-boot.img.
|
|
|
|
|
#. It uses mkimage to package U-Boot into a legacy image file (so that it can
|
|
|
|
|
hold the load and execution address) called u-boot.img.
|
|
|
|
|
|
|
|
|
|
3. It builds a final output image called u-boot-sunxi-with-spl.bin which
|
|
|
|
|
consists of sunxi-spl.bin, some padding and u-boot.img.
|
|
|
|
|
#. It builds a final output image called u-boot-sunxi-with-spl.bin which
|
|
|
|
|
consists of sunxi-spl.bin, some padding and u-boot.img.
|
|
|
|
|
|
|
|
|
|
Binman is intended to replace the last step. The U-Boot build system builds
|
|
|
|
|
u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
|
|
|
|
@@ -180,12 +181,12 @@ the configuration of the Intel-format descriptor.
|
|
|
|
|
Running binman
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
First install prerequisites, e.g.
|
|
|
|
|
First install prerequisites, e.g::
|
|
|
|
|
|
|
|
|
|
sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
|
|
|
|
|
liblz4-tool
|
|
|
|
|
|
|
|
|
|
Type:
|
|
|
|
|
Type::
|
|
|
|
|
|
|
|
|
|
binman build -b <board_name>
|
|
|
|
|
|
|
|
|
@@ -193,7 +194,7 @@ to build an image for a board. The board name is the same name used when
|
|
|
|
|
configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
|
|
|
|
|
Binman assumes that the input files for the build are in ../b/<board_name>.
|
|
|
|
|
|
|
|
|
|
Or you can specify this explicitly:
|
|
|
|
|
Or you can specify this explicitly::
|
|
|
|
|
|
|
|
|
|
binman build -I <build_path>
|
|
|
|
|
|
|
|
|
@@ -212,12 +213,12 @@ Enabling binman for a board
|
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
|
|
At present binman is invoked from a rule in the main Makefile. Typically you
|
|
|
|
|
will have a rule like:
|
|
|
|
|
will have a rule like::
|
|
|
|
|
|
|
|
|
|
ifneq ($(CONFIG_ARCH_<something>),)
|
|
|
|
|
u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
|
|
|
|
|
ifneq ($(CONFIG_ARCH_<something>),)
|
|
|
|
|
u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
|
|
|
|
|
$(call if_changed,binman)
|
|
|
|
|
endif
|
|
|
|
|
endif
|
|
|
|
|
|
|
|
|
|
This assumes that u-boot-<your_suffix>.bin is a target, and is the final file
|
|
|
|
|
that you need to produce. You can make it a target by adding it to INPUTS-y
|
|
|
|
@@ -233,7 +234,7 @@ Image description format
|
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
|
|
The binman node is called 'binman'. An example image description is shown
|
|
|
|
|
below:
|
|
|
|
|
below::
|
|
|
|
|
|
|
|
|
|
binman {
|
|
|
|
|
filename = "u-boot-sunxi-with-spl.bin";
|
|
|
|
@@ -414,7 +415,7 @@ multiple-images:
|
|
|
|
|
Normally only a single image is generated. To create more than one
|
|
|
|
|
image, put this property in the binman node. For example, this will
|
|
|
|
|
create image1.bin containing u-boot.bin, and image2.bin containing
|
|
|
|
|
both spl/u-boot-spl.bin and u-boot.bin:
|
|
|
|
|
both spl/u-boot-spl.bin and u-boot.bin::
|
|
|
|
|
|
|
|
|
|
binman {
|
|
|
|
|
multiple-images;
|
|
|
|
@@ -470,7 +471,7 @@ This feature provides a way of creating hierarchical images. For example here
|
|
|
|
|
is an example image with two copies of U-Boot. One is read-only (ro), intended
|
|
|
|
|
to be written only in the factory. Another is read-write (rw), so that it can be
|
|
|
|
|
upgraded in the field. The sizes are fixed so that the ro/rw boundary is known
|
|
|
|
|
and can be programmed:
|
|
|
|
|
and can be programmed::
|
|
|
|
|
|
|
|
|
|
binman {
|
|
|
|
|
section@0 {
|
|
|
|
@@ -540,7 +541,7 @@ Listing images
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
It is possible to list the entries in an existing firmware image created by
|
|
|
|
|
binman, provided that there is an 'fdtmap' entry in the image. For example:
|
|
|
|
|
binman, provided that there is an 'fdtmap' entry in the image. For example::
|
|
|
|
|
|
|
|
|
|
$ binman ls -i image.bin
|
|
|
|
|
Name Image-pos Size Entry-type Offset Uncomp-size
|
|
|
|
@@ -559,7 +560,7 @@ This shows the hierarchy of the image, the position, size and type of each
|
|
|
|
|
entry, the offset of each entry within its parent and the uncompressed size if
|
|
|
|
|
the entry is compressed.
|
|
|
|
|
|
|
|
|
|
It is also possible to list just some files in an image, e.g.
|
|
|
|
|
It is also possible to list just some files in an image, e.g.::
|
|
|
|
|
|
|
|
|
|
$ binman ls -i image.bin section/cbfs
|
|
|
|
|
Name Image-pos Size Entry-type Offset Uncomp-size
|
|
|
|
@@ -568,7 +569,7 @@ It is also possible to list just some files in an image, e.g.
|
|
|
|
|
u-boot 138 4 u-boot 38
|
|
|
|
|
u-boot-dtb 180 108 u-boot-dtb 80 3b5
|
|
|
|
|
|
|
|
|
|
or with wildcards:
|
|
|
|
|
or with wildcards::
|
|
|
|
|
|
|
|
|
|
$ binman ls -i image.bin "*cb*" "*head*"
|
|
|
|
|
Name Image-pos Size Entry-type Offset Uncomp-size
|
|
|
|
@@ -583,22 +584,22 @@ Extracting files from images
|
|
|
|
|
----------------------------
|
|
|
|
|
|
|
|
|
|
You can extract files from an existing firmware image created by binman,
|
|
|
|
|
provided that there is an 'fdtmap' entry in the image. For example:
|
|
|
|
|
provided that there is an 'fdtmap' entry in the image. For example::
|
|
|
|
|
|
|
|
|
|
$ binman extract -i image.bin section/cbfs/u-boot
|
|
|
|
|
|
|
|
|
|
which will write the uncompressed contents of that entry to the file 'u-boot' in
|
|
|
|
|
the current directory. You can also extract to a particular file, in this case
|
|
|
|
|
u-boot.bin:
|
|
|
|
|
u-boot.bin::
|
|
|
|
|
|
|
|
|
|
$ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin
|
|
|
|
|
|
|
|
|
|
It is possible to extract all files into a destination directory, which will
|
|
|
|
|
put files in subdirectories matching the entry hierarchy:
|
|
|
|
|
put files in subdirectories matching the entry hierarchy::
|
|
|
|
|
|
|
|
|
|
$ binman extract -i image.bin -O outdir
|
|
|
|
|
|
|
|
|
|
or just a selection:
|
|
|
|
|
or just a selection::
|
|
|
|
|
|
|
|
|
|
$ binman extract -i image.bin "*u-boot*" -O outdir
|
|
|
|
|
|
|
|
|
@@ -616,18 +617,18 @@ to the that entry, compressing if necessary. If the entry size changes, you must
|
|
|
|
|
add the 'allow-repack' property to the original image before generating it (see
|
|
|
|
|
above), otherwise you will get an error.
|
|
|
|
|
|
|
|
|
|
You can also use a particular file, in this case u-boot.bin:
|
|
|
|
|
You can also use a particular file, in this case u-boot.bin::
|
|
|
|
|
|
|
|
|
|
$ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin
|
|
|
|
|
|
|
|
|
|
It is possible to replace all files from a source directory which uses the same
|
|
|
|
|
hierarchy as the entries:
|
|
|
|
|
hierarchy as the entries::
|
|
|
|
|
|
|
|
|
|
$ binman replace -i image.bin -I indir
|
|
|
|
|
|
|
|
|
|
Files that are missing will generate a warning.
|
|
|
|
|
|
|
|
|
|
You can also replace just a selection of entries:
|
|
|
|
|
You can also replace just a selection of entries::
|
|
|
|
|
|
|
|
|
|
$ binman replace -i image.bin "*u-boot*" -I indir
|
|
|
|
|
|
|
|
|
@@ -656,7 +657,7 @@ Hashing Entries
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
It is possible to ask binman to hash the contents of an entry and write that
|
|
|
|
|
value back to the device-tree node. For example:
|
|
|
|
|
value back to the device-tree node. For example::
|
|
|
|
|
|
|
|
|
|
binman {
|
|
|
|
|
u-boot {
|
|
|
|
@@ -759,7 +760,7 @@ a common header. You can then put the binman node (and anything else that is
|
|
|
|
|
specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header
|
|
|
|
|
file.
|
|
|
|
|
|
|
|
|
|
Binman will search for the following files in arch/<arch>/dts:
|
|
|
|
|
Binman will search for the following files in arch/<arch>/dts::
|
|
|
|
|
|
|
|
|
|
<dts>-u-boot.dtsi where <dts> is the base name of the .dts file
|
|
|
|
|
<CONFIG_SYS_SOC>-u-boot.dtsi
|
|
|
|
@@ -770,7 +771,7 @@ Binman will search for the following files in arch/<arch>/dts:
|
|
|
|
|
U-Boot will only use the first one that it finds. If you need to include a
|
|
|
|
|
more general file you can do that from the more specific file using #include.
|
|
|
|
|
If you are having trouble figuring out what is going on, you can uncomment
|
|
|
|
|
the 'warning' line in scripts/Makefile.lib to see what it has found:
|
|
|
|
|
the 'warning' line in scripts/Makefile.lib to see what it has found::
|
|
|
|
|
|
|
|
|
|
# Uncomment for debugging
|
|
|
|
|
# This shows all the files that were considered and the one that we chose.
|
|
|
|
@@ -786,13 +787,13 @@ is useful to be able to find the location of U-Boot so that it can be executed
|
|
|
|
|
when SPL is finished.
|
|
|
|
|
|
|
|
|
|
Binman allows you to declare symbols in the SPL image which are filled in
|
|
|
|
|
with their correct values during the build. For example:
|
|
|
|
|
with their correct values during the build. For example::
|
|
|
|
|
|
|
|
|
|
binman_sym_declare(ulong, u_boot_any, image_pos);
|
|
|
|
|
|
|
|
|
|
declares a ulong value which will be assigned to the image-pos of any U-Boot
|
|
|
|
|
image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
|
|
|
|
|
You can access this value with something like:
|
|
|
|
|
You can access this value with something like::
|
|
|
|
|
|
|
|
|
|
ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos);
|
|
|
|
|
|
|
|
|
@@ -844,18 +845,18 @@ Expanded entries
|
|
|
|
|
----------------
|
|
|
|
|
|
|
|
|
|
Binman automatically replaces 'u-boot' with an expanded version of that, i.e.
|
|
|
|
|
'u-boot-expanded'. This means that when you write:
|
|
|
|
|
'u-boot-expanded'. This means that when you write::
|
|
|
|
|
|
|
|
|
|
u-boot {
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
you actually get:
|
|
|
|
|
you actually get::
|
|
|
|
|
|
|
|
|
|
u-boot {
|
|
|
|
|
type = "u-boot-expanded';
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
which in turn expands to:
|
|
|
|
|
which in turn expands to::
|
|
|
|
|
|
|
|
|
|
u-boot {
|
|
|
|
|
type = "section";
|
|
|
|
@@ -879,19 +880,19 @@ U-Boot executable and can be updated separately by binman as needed. It can be
|
|
|
|
|
disabled with the --no-expanded flag if required.
|
|
|
|
|
|
|
|
|
|
The same applies for u-boot-spl and u-boot-spl. In those cases, the expansion
|
|
|
|
|
includes the BSS padding, so for example:
|
|
|
|
|
includes the BSS padding, so for example::
|
|
|
|
|
|
|
|
|
|
spl {
|
|
|
|
|
type = "u-boot-spl"
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
you actually get:
|
|
|
|
|
you actually get::
|
|
|
|
|
|
|
|
|
|
spl {
|
|
|
|
|
type = "u-boot-expanded';
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
which in turn expands to:
|
|
|
|
|
which in turn expands to::
|
|
|
|
|
|
|
|
|
|
spl {
|
|
|
|
|
type = "section";
|
|
|
|
@@ -921,7 +922,7 @@ Compression
|
|
|
|
|
-----------
|
|
|
|
|
|
|
|
|
|
Binman support compression for 'blob' entries (those of type 'blob' and
|
|
|
|
|
derivatives). To enable this for an entry, add a 'compress' property:
|
|
|
|
|
derivatives). To enable this for an entry, add a 'compress' property::
|
|
|
|
|
|
|
|
|
|
blob {
|
|
|
|
|
filename = "datafile";
|
|
|
|
@@ -946,7 +947,7 @@ Map files
|
|
|
|
|
---------
|
|
|
|
|
|
|
|
|
|
The -m option causes binman to output a .map file for each image that it
|
|
|
|
|
generates. This shows the offset and size of each entry. For example:
|
|
|
|
|
generates. This shows the offset and size of each entry. For example::
|
|
|
|
|
|
|
|
|
|
Offset Size Name
|
|
|
|
|
00000000 00000028 main-section
|
|
|
|
@@ -969,11 +970,11 @@ Sometimes it is useful to pass binman the value of an entry property from the
|
|
|
|
|
command line. For example some entries need access to files and it is not
|
|
|
|
|
always convenient to put these filenames in the image definition (device tree).
|
|
|
|
|
|
|
|
|
|
The-a option supports this:
|
|
|
|
|
The-a option supports this::
|
|
|
|
|
|
|
|
|
|
-a<prop>=<value>
|
|
|
|
|
|
|
|
|
|
where
|
|
|
|
|
where::
|
|
|
|
|
|
|
|
|
|
<prop> is the property to set
|
|
|
|
|
<value> is the value to set it to
|
|
|
|
@@ -1004,7 +1005,7 @@ Code coverage
|
|
|
|
|
Binman is a critical tool and is designed to be very testable. Entry
|
|
|
|
|
implementations target 100% test coverage. Run 'binman test -T' to check this.
|
|
|
|
|
|
|
|
|
|
To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):
|
|
|
|
|
To enable Python test coverage on Debian-type distributions (e.g. Ubuntu)::
|
|
|
|
|
|
|
|
|
|
$ sudo apt-get install python-coverage python3-coverage python-pytest
|
|
|
|
|
|
|
|
|
@@ -1015,7 +1016,7 @@ Concurrent tests
|
|
|
|
|
Binman tries to run tests concurrently. This means that the tests make use of
|
|
|
|
|
all available CPUs to run.
|
|
|
|
|
|
|
|
|
|
To enable this:
|
|
|
|
|
To enable this::
|
|
|
|
|
|
|
|
|
|
$ sudo apt-get install python-subunit python3-subunit
|
|
|
|
|
|
|
|
|
@@ -1038,11 +1039,11 @@ Binman's tests have been written under the assumption that they'll be run on a
|
|
|
|
|
x86-like host and there hasn't been an attempt to make them portable yet.
|
|
|
|
|
However, it's possible to run the tests by cross-compiling to x86.
|
|
|
|
|
|
|
|
|
|
To install an x86 cross-compiler on Debian-type distributions (e.g. Ubuntu):
|
|
|
|
|
To install an x86 cross-compiler on Debian-type distributions (e.g. Ubuntu)::
|
|
|
|
|
|
|
|
|
|
$ sudo apt-get install gcc-x86-64-linux-gnu
|
|
|
|
|
|
|
|
|
|
Then, you can run the tests under cross-compilation:
|
|
|
|
|
Then, you can run the tests under cross-compilation::
|
|
|
|
|
|
|
|
|
|
$ CROSS_COMPILE=x86_64-linux-gnu- binman test -T
|
|
|
|
|
|
|
|
|
@@ -1078,13 +1079,13 @@ the DTC environment variable. This can be useful when the system dtc is too
|
|
|
|
|
old.
|
|
|
|
|
|
|
|
|
|
To enable a full backtrace and other debugging features in binman, pass
|
|
|
|
|
BINMAN_DEBUG=1 to your build:
|
|
|
|
|
BINMAN_DEBUG=1 to your build::
|
|
|
|
|
|
|
|
|
|
make qemu-x86_defconfig
|
|
|
|
|
make BINMAN_DEBUG=1
|
|
|
|
|
|
|
|
|
|
To enable verbose logging from binman, base BINMAN_VERBOSE to your build, which
|
|
|
|
|
adds a -v<level> option to the call to binman:
|
|
|
|
|
adds a -v<level> option to the call to binman::
|
|
|
|
|
|
|
|
|
|
make qemu-x86_defconfig
|
|
|
|
|
make BINMAN_VERBOSE=5
|
|
|
|
@@ -1124,6 +1125,7 @@ To do
|
|
|
|
|
-----
|
|
|
|
|
|
|
|
|
|
Some ideas:
|
|
|
|
|
|
|
|
|
|
- Use of-platdata to make the information available to code that is unable
|
|
|
|
|
to use device tree (such as a very small SPL image)
|
|
|
|
|
- Allow easy building of images by specifying just the board name
|