Mirrors/u-boot
2
0
Fork 0
mirror of https://github.com/AsahiLinux/u-boot synced 2024-11-24 21:54:01 +00:00
Code Issues Projects Releases Packages Wiki Activity

binman: doc: Add documentation to htmldocs

Browse source 
Add a link to binman's documentation and adjust the files so that it is
accessible. Use the name README.rst so it is easy to discover when binman
is installed without U-Boot.

Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass 2021-03-18 20:25:13 +13:00
parent 5ce319133b
commit 61adb2d247
11 changed files with 291 additions and 242 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
doc/develop/index.rst
View file

@ -26,6 +26,14 @@ Debugging
crash_dumps
trace
Packaging
---------
.. toctree::
:maxdepth: 1
package/index
Testing
-------

1
doc/develop/package/binman.rst Symbolic link
View file

@ -0,0 +1 @@
../../../tools/binman/binman.rst

19
doc/develop/package/index.rst Normal file
View file

@ -0,0 +1,19 @@
.. SPDX-License-Identifier: GPL-2.0+
Package U-Boot
==============
U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging
images that it it reads and boots. Documentation about FIT is available at
doc/uImage.FIT
U-Boot also provides binman for cases not covered by FIT. Examples include
initial execution (since FIT itself does not have an executable header) and
dealing with device boundaries, such as the read-only/read-write separation in
SPI flash.
.. toctree::
:maxdepth: 2
binman

8
doc/usage/fit.rst Normal file
View file

@ -0,0 +1,8 @@
.. SPDX-License-Identifier: GPL-2.0+
Flat Image Tree (FIT)
=====================
U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging
images that it it reads and boots. Documentation about FIT is available at
doc/uImage.FIT

1
doc/usage/index.rst
View file

@ -5,6 +5,7 @@ Use U-Boot
:maxdepth: 1
fdt_overlays
fit
netconsole
partitions

1
tools/binman/README.rst Symbolic link
View file

@ -0,0 +1 @@
binman.rst

478
tools/binman/README → tools/binman/binman.rst
View file

@ -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,22 +181,22 @@ 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
sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \
liblz4-tool
Type:
Type::
binman build -b <board_name>
binman build -b <board_name>
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>
binman build -I <build_path>
where <build_path> is the build directory containing the output of the U-Boot
build.
@ -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
$(call if_changed,binman)
endif
ifneq ($(CONFIG_ARCH_<something>),)
u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE
$(call if_changed,binman)
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,18 +234,18 @@ 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";
pad-byte = <0xff>;
blob {
filename = "spl/sunxi-spl.bin";
};
u-boot {
offset = <CONFIG_SPL_PAD_TO>;
};
};
binman {
filename = "u-boot-sunxi-with-spl.bin";
pad-byte = <0xff>;
blob {
filename = "spl/sunxi-spl.bin";
};
u-boot {
offset = <CONFIG_SPL_PAD_TO>;
};
};
This requests binman to create an image file called u-boot-sunxi-with-spl.bin
@ -270,184 +271,184 @@ use any unique name, with the 'type' property providing the type.
The attributes supported for entries are described below.
offset:
This sets the offset of an entry within the image or section containing
it. The first byte of the image is normally at offset 0. If 'offset' is
not provided, binman sets it to the end of the previous region, or the
start of the image's entry area (normally 0) if there is no previous
region.
This sets the offset of an entry within the image or section containing
it. The first byte of the image is normally at offset 0. If 'offset' is
not provided, binman sets it to the end of the previous region, or the
start of the image's entry area (normally 0) if there is no previous
region.
align:
This sets the alignment of the entry. The entry offset is adjusted
so that the entry starts on an aligned boundary within the containing
section or image. For example 'align = <16>' means that the entry will
start on a 16-byte boundary. This may mean that padding is added before
the entry. The padding is part of the containing section but is not
included in the entry, meaning that an empty space may be created before
the entry starts. Alignment should be a power of 2. If 'align' is not
provided, no alignment is performed.
This sets the alignment of the entry. The entry offset is adjusted
so that the entry starts on an aligned boundary within the containing
section or image. For example 'align = <16>' means that the entry will
start on a 16-byte boundary. This may mean that padding is added before
the entry. The padding is part of the containing section but is not
included in the entry, meaning that an empty space may be created before
the entry starts. Alignment should be a power of 2. If 'align' is not
provided, no alignment is performed.
size:
This sets the size of the entry. The contents will be padded out to
this size. If this is not provided, it will be set to the size of the
contents.
This sets the size of the entry. The contents will be padded out to
this size. If this is not provided, it will be set to the size of the
contents.
pad-before:
Padding before the contents of the entry. Normally this is 0, meaning
that the contents start at the beginning of the entry. This can be used
to offset the entry contents a little. While this does not affect the
contents of the entry within binman itself (the padding is performed
only when its parent section is assembled), the end result will be that
the entry starts with the padding bytes, so may grow. Defaults to 0.
Padding before the contents of the entry. Normally this is 0, meaning
that the contents start at the beginning of the entry. This can be used
to offset the entry contents a little. While this does not affect the
contents of the entry within binman itself (the padding is performed
only when its parent section is assembled), the end result will be that
the entry starts with the padding bytes, so may grow. Defaults to 0.
pad-after:
Padding after the contents of the entry. Normally this is 0, meaning
that the entry ends at the last byte of content (unless adjusted by
other properties). This allows room to be created in the image for
this entry to expand later. While this does not affect the contents of
the entry within binman itself (the padding is performed only when its
parent section is assembled), the end result will be that the entry ends
with the padding bytes, so may grow. Defaults to 0.
Padding after the contents of the entry. Normally this is 0, meaning
that the entry ends at the last byte of content (unless adjusted by
other properties). This allows room to be created in the image for
this entry to expand later. While this does not affect the contents of
the entry within binman itself (the padding is performed only when its
parent section is assembled), the end result will be that the entry ends
with the padding bytes, so may grow. Defaults to 0.
align-size:
This sets the alignment of the entry size. For example, to ensure
that the size of an entry is a multiple of 64 bytes, set this to 64.
While this does not affect the contents of the entry within binman
itself (the padding is performed only when its parent section is
assembled), the end result is that the entry ends with the padding
bytes, so may grow. If 'align-size' is not provided, no alignment is
performed.
This sets the alignment of the entry size. For example, to ensure
that the size of an entry is a multiple of 64 bytes, set this to 64.
While this does not affect the contents of the entry within binman
itself (the padding is performed only when its parent section is
assembled), the end result is that the entry ends with the padding
bytes, so may grow. If 'align-size' is not provided, no alignment is
performed.
align-end:
This sets the alignment of the end of an entry with respect to the
containing section. Some entries require that they end on an alignment
boundary, regardless of where they start. This does not move the start
of the entry, so the contents of the entry will still start at the
beginning. But there may be padding at the end. While this does not
affect the contents of the entry within binman itself (the padding is
performed only when its parent section is assembled), the end result
is that the entry ends with the padding bytes, so may grow.
If 'align-end' is not provided, no alignment is performed.
This sets the alignment of the end of an entry with respect to the
containing section. Some entries require that they end on an alignment
boundary, regardless of where they start. This does not move the start
of the entry, so the contents of the entry will still start at the
beginning. But there may be padding at the end. While this does not
affect the contents of the entry within binman itself (the padding is
performed only when its parent section is assembled), the end result
is that the entry ends with the padding bytes, so may grow.
If 'align-end' is not provided, no alignment is performed.
filename:
For 'blob' types this provides the filename containing the binary to
put into the entry. If binman knows about the entry type (like
u-boot-bin), then there is no need to specify this.
For 'blob' types this provides the filename containing the binary to
put into the entry. If binman knows about the entry type (like
u-boot-bin), then there is no need to specify this.
type:
Sets the type of an entry. This defaults to the entry name, but it is
possible to use any name, and then add (for example) 'type = "u-boot"'
to specify the type.
Sets the type of an entry. This defaults to the entry name, but it is
possible to use any name, and then add (for example) 'type = "u-boot"'
to specify the type.
offset-unset:
Indicates that the offset of this entry should not be set by placing
it immediately after the entry before. Instead, is set by another
entry which knows where this entry should go. When this boolean
property is present, binman will give an error if another entry does
not set the offset (with the GetOffsets() method).
Indicates that the offset of this entry should not be set by placing
it immediately after the entry before. Instead, is set by another
entry which knows where this entry should go. When this boolean
property is present, binman will give an error if another entry does
not set the offset (with the GetOffsets() method).
image-pos:
This cannot be set on entry (or at least it is ignored if it is), but
with the -u option, binman will set it to the absolute image position
for each entry. This makes it easy to find out exactly where the entry
ended up in the image, regardless of parent sections, etc.
This cannot be set on entry (or at least it is ignored if it is), but
with the -u option, binman will set it to the absolute image position
for each entry. This makes it easy to find out exactly where the entry
ended up in the image, regardless of parent sections, etc.
expand-size:
Expand the size of this entry to fit available space. This space is only
limited by the size of the image/section and the position of the next
entry.
Expand the size of this entry to fit available space. This space is only
limited by the size of the image/section and the position of the next
entry.
compress:
Sets the compression algortihm to use (for blobs only). See the entry
documentation for details.
Sets the compression algortihm to use (for blobs only). See the entry
documentation for details.
missing-msg:
Sets the tag of the message to show if this entry is missing. This is
used for external blobs. When they are missing it is helpful to show
information about what needs to be fixed. See missing-blob-help for the
message for each tag.
Sets the tag of the message to show if this entry is missing. This is
used for external blobs. When they are missing it is helpful to show
information about what needs to be fixed. See missing-blob-help for the
message for each tag.
The attributes supported for images and sections are described below. Several
are similar to those for entries.
size:
Sets the image size in bytes, for example 'size = <0x100000>' for a
1MB image.
Sets the image size in bytes, for example 'size = <0x100000>' for a
1MB image.
offset:
This is similar to 'offset' in entries, setting the offset of a section
within the image or section containing it. The first byte of the section
is normally at offset 0. If 'offset' is not provided, binman sets it to
the end of the previous region, or the start of the image's entry area
(normally 0) if there is no previous region.
This is similar to 'offset' in entries, setting the offset of a section
within the image or section containing it. The first byte of the section
is normally at offset 0. If 'offset' is not provided, binman sets it to
the end of the previous region, or the start of the image's entry area
(normally 0) if there is no previous region.
align-size:
This sets the alignment of the image size. For example, to ensure
that the image ends on a 512-byte boundary, use 'align-size = <512>'.
If 'align-size' is not provided, no alignment is performed.
This sets the alignment of the image size. For example, to ensure
that the image ends on a 512-byte boundary, use 'align-size = <512>'.
If 'align-size' is not provided, no alignment is performed.
pad-before:
This sets the padding before the image entries. The first entry will
be positioned after the padding. This defaults to 0.
This sets the padding before the image entries. The first entry will
be positioned after the padding. This defaults to 0.
pad-after:
This sets the padding after the image entries. The padding will be
placed after the last entry. This defaults to 0.
This sets the padding after the image entries. The padding will be
placed after the last entry. This defaults to 0.
pad-byte:
This specifies the pad byte to use when padding in the image. It
defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
This specifies the pad byte to use when padding in the image. It
defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
filename:
This specifies the image filename. It defaults to 'image.bin'.
This specifies the image filename. It defaults to 'image.bin'.
sort-by-offset:
This causes binman to reorder the entries as needed to make sure they
are in increasing positional order. This can be used when your entry
order may not match the positional order. A common situation is where
the 'offset' properties are set by CONFIG options, so their ordering is
not known a priori.
This causes binman to reorder the entries as needed to make sure they
are in increasing positional order. This can be used when your entry
order may not match the positional order. A common situation is where
the 'offset' properties are set by CONFIG options, so their ordering is
not known a priori.
This is a boolean property so needs no value. To enable it, add a
line 'sort-by-offset;' to your description.
This is a boolean property so needs no value. To enable it, add a
line 'sort-by-offset;' to your description.
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:
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::
binman {
multiple-images;
image1 {
u-boot {
};
};
binman {
multiple-images;
image1 {
u-boot {
};
};
image2 {
spl {
};
u-boot {
};
};
};
image2 {
spl {
};
u-boot {
};
};
};
end-at-4gb:
For x86 machines the ROM offsets start just before 4GB and extend
up so that the image finished at the 4GB boundary. This boolean
option can be enabled to support this. The image size must be
provided so that binman knows when the image should start. For an
8MB ROM, the offset of the first entry would be 0xfff80000 with
this option, instead of 0 without this option.
For x86 machines the ROM offsets start just before 4GB and extend
up so that the image finished at the 4GB boundary. This boolean
option can be enabled to support this. The image size must be
provided so that binman knows when the image should start. For an
8MB ROM, the offset of the first entry would be 0xfff80000 with
this option, instead of 0 without this option.
skip-at-start:
This property specifies the entry offset of the first entry.
This property specifies the entry offset of the first entry.
For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry
offset of the first entry. It can be 0xeff40000 or 0xfff40000 for
nor flash boot, 0x201000 for sd boot etc.
For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry
offset of the first entry. It can be 0xeff40000 or 0xfff40000 for
nor flash boot, 0x201000 for sd boot etc.
'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
Image size != 4gb.
'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
Image size != 4gb.
Examples of the above options can be found in the tests. See the
tools/binman/test directory.
@ -470,23 +471,23 @@ 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 {
read-only;
name-prefix = "ro-";
size = <0x100000>;
u-boot {
};
};
section@1 {
name-prefix = "rw-";
size = <0x100000>;
u-boot {
};
};
};
binman {
section@0 {
read-only;
name-prefix = "ro-";
size = <0x100000>;
u-boot {
};
};
section@1 {
name-prefix = "rw-";
size = <0x100000>;
u-boot {
};
};
};
This image could be placed into a SPI flash chip, with the protection boundary
set at 1MB.
@ -494,14 +495,14 @@ set at 1MB.
A few special properties are provided for sections:
read-only:
Indicates that this section is read-only. This has no impact on binman's
operation, but his property can be read at run time.
Indicates that this section is read-only. This has no impact on binman's
operation, but his property can be read at run time.
name-prefix:
This string is prepended to all the names of the binaries in the
section. In the example above, the 'u-boot' binaries which actually be
renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
distinguish binaries with otherwise identical names.
This string is prepended to all the names of the binaries in the
section. In the example above, the 'u-boot' binaries which actually be
renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to
distinguish binaries with otherwise identical names.
Image Properties
@ -510,21 +511,21 @@ Image Properties
Image nodes act like sections but also have a few extra properties:
filename:
Output filename for the image. This defaults to image.bin (or in the
case of multiple images <nodename>.bin where <nodename> is the name of
the image node.
Output filename for the image. This defaults to image.bin (or in the
case of multiple images <nodename>.bin where <nodename> is the name of
the image node.
allow-repack:
Create an image that can be repacked. With this option it is possible
to change anything in the image after it is created, including updating
the position and size of image components. By default this is not
permitted since it is not possibly to know whether this might violate a
constraint in the image description. For example, if a section has to
increase in size to hold a larger binary, that might cause the section
to fall out of its allow region (e.g. read-only portion of flash).
Create an image that can be repacked. With this option it is possible
to change anything in the image after it is created, including updating
the position and size of image components. By default this is not
permitted since it is not possibly to know whether this might violate a
constraint in the image description. For example, if a section has to
increase in size to hold a larger binary, that might cause the section
to fall out of its allow region (e.g. read-only portion of flash).
Adding this property causes the original offset and size values in the
image description to be stored in the FDT and fdtmap.
Adding this property causes the original offset and size values in the
image description to be stored in the FDT and fdtmap.
Entry Documentation
@ -533,14 +534,14 @@ Entry Documentation
For details on the various entry types supported by binman and how to use them,
see README.entries. This is generated from the source code using:
binman entry-docs >tools/binman/README.entries
binman entry-docs >tools/binman/README.entries
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,15 +657,15 @@ 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 {
hash {
algo = "sha256";
};
};
};
binman {
u-boot {
hash {
algo = "sha256";
};
};
};
Here, a new 'value' property will be written to the 'hash' node containing
the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole
@ -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

2
tools/binman/control.py
View file

@ -569,7 +569,7 @@ def Binman(args):
if not pager:
pager = 'more'
fname = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
'README')
'README.rst')
command.Run(pager, fname)
return 0

4
tools/binman/ftest.py
View file

@ -631,7 +631,7 @@ class TestFunctional(unittest.TestCase):
def testFullHelp(self):
"""Test that the full help is displayed with -H"""
result = self._RunBinman('-H')
help_file = os.path.join(self._binman_dir, 'README')
help_file = os.path.join(self._binman_dir, 'README.rst')
# Remove possible extraneous strings
extra = '::::::::::::::\n' + help_file + '\n::::::::::::::\n'
gothelp = result.stdout.replace(extra, '')
@ -644,7 +644,7 @@ class TestFunctional(unittest.TestCase):
try:
command.test_result = command.CommandResult()
result = self._DoBinman('-H')
help_file = os.path.join(self._binman_dir, 'README')
help_file = os.path.join(self._binman_dir, 'README.rst')
finally:
command.test_result = None

9
tools/binman/index.rst Normal file
View file

@ -0,0 +1,9 @@
.. SPDX-License-Identifier: GPL-2.0+
Binman
======
.. toctree::
:maxdepth: 2
README

2
tools/binman/setup.py
View file

@ -7,6 +7,6 @@ setup(name='binman',
scripts=['binman'],
packages=['binman', 'binman.etype'],
package_dir={'binman': ''},
package_data={'binman': ['README', 'README.entries']},
package_data={'binman': ['README.rst', 'README.entries']},
classifiers=['Environment :: Console',
'Topic :: Software Development :: Embedded Systems'])