colin/u-boot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

binman: Rearrange documentation into headings

Browse Source 
Collect the material into different top-level headings to make it easier
to read.

Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass
2021-03-18 20:25:14 +13:00
parent 61adb2d247
commit 072026e7bb
1 changed files with 266 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files

523
tools/binman/binman.rst
View File

@@ -2,7 +2,7 @@
.. Copyright (c) 2016 Google, Inc .. Copyright (c) 2016 Google, Inc
Introduction Introduction
------------ ============
Firmware often consists of several components which must be packaged together. Firmware often consists of several components which must be packaged together.
For example, we may have SPL, U-Boot, a device tree and an environment area For example, we may have SPL, U-Boot, a device tree and an environment area
@@ -137,6 +137,9 @@ the boundaries between building input files (mkimage) and packaging then
into a final image (binman). into a final image (binman).
Using binman
============
Example use of binman in U-Boot Example use of binman in U-Boot
------------------------------- -------------------------------
@@ -230,8 +233,111 @@ You can use other, more specific CONFIG options - see 'Automatic .dtsi
inclusion' below. inclusion' below.
Access to binman entry offsets at run time (symbols)
----------------------------------------------------
Binman assembles images and determines where each entry is placed in the image.
This information may be useful to U-Boot at run time. For example, in SPL it
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::
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::
ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos);
Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming
that the whole image has been loaded, or is available in flash. You can then
jump to that address to start U-Boot.
At present this feature is only supported in SPL and TPL. In principle it is
possible to fill in such symbols in U-Boot proper, as well, but a future C
library is planned for this instead, to read from the device tree.
As well as image-pos, it is possible to read the size of an entry and its
offset (which is the start position of the entry within its parent).
A small technical note: Binman automatically adds the base address of the image
(i.e. __image_copy_start) to the value of the image-pos symbol, so that when the
image is loaded to its linked address, the value will be correct and actually
point into the image.
For example, say SPL is at the start of the image and linked to start at address
80108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos
for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded
to 80108000, with SPL at 80108000 and U-Boot at 80110000.
For x86 devices (with the end-at-4gb property) this base address is not added
since it is assumed that images are XIP and the offsets already include the
address.
Access to binman entry offsets at run time (fdt)
------------------------------------------------
Binman can update the U-Boot FDT to include the final position and size of
each entry in the images it processes. The option to enable this is -u and it
causes binman to make sure that the 'offset', 'image-pos' and 'size' properties
are set correctly for every entry. Since it is not necessary to specify these in
the image definition, binman calculates the final values and writes these to
the device tree. These can be used by U-Boot at run-time to find the location
of each entry.
Alternatively, an FDT map entry can be used to add a special FDT containing
just the information about the image. This is preceded by a magic string so can
be located anywhere in the image. An image header (typically at the start or end
of the image) can be used to point to the FDT map. See fdtmap and image-header
entries for more information.
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::
Offset Size Name
00000000 00000028 main-section
00000000 00000010 section@0
00000000 00000004 u-boot
00000010 00000010 section@1
00000000 00000004 u-boot
This shows a hierarchical image with two sections, each with a single entry. The
offsets of the sections are absolute hex byte offsets within the image. The
offsets of the entries are relative to their respective sections. The size of
each entry is also shown, in bytes (hex). The indentation shows the entries
nested inside their sections.
Passing command-line arguments to entries
-----------------------------------------
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::
-a<prop>=<value>
where::
<prop> is the property to set
<value> is the value to set it to
Not all properties can be provided this way. Only some entries support it,
typically for filenames.
Image description format Image description format
------------------------ ========================
The binman node is called 'binman'. An example image description is shown The binman node is called 'binman'. An example image description is shown
below:: below::
@@ -528,6 +634,157 @@ allow-repack:
image description to be stored in the FDT and fdtmap. image description to be stored in the FDT and fdtmap.
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::
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
sections can be hased if desired, by adding the 'hash' node to the section.
The has value can be chcked at runtime by hashing the data actually read and
comparing this has to the value in the device tree.
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 {
};
you actually get::
u-boot {
type = "u-boot-expanded';
};
which in turn expands to::
u-boot {
type = "section";
u-boot-nodtb {
};
u-boot-dtb {
};
};
U-Boot's various phase binaries actually comprise two or three pieces.
For example, u-boot.bin has the executable followed by a devicetree.
With binman we want to be able to update that devicetree with full image
information so that it is accessible to the executable. This is tricky
if it is not clear where the devicetree starts.
The above feature ensures that the devicetree is clearly separated from the
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::
spl {
type = "u-boot-spl"
};
you actually get::
spl {
type = "u-boot-expanded';
};
which in turn expands to::
spl {
type = "section";
u-boot-spl-nodtb {
};
u-boot-spl-bss-pad {
};
u-boot-spl-dtb {
};
};
Of course we should not expand SPL if it has no devicetree. Also if the BSS
padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS),
the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned
entry type is controlled by the UseExpanded() method. In the SPL case it checks
the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree.
For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. All
entry args are provided by the U-Boot Makefile.
Compression
-----------
Binman support compression for 'blob' entries (those of type 'blob' and
derivatives). To enable this for an entry, add a 'compress' property::
blob {
filename = "datafile";
compress = "lz4";
};
The entry will then contain the compressed data, using the 'lz4' compression
algorithm. Currently this is the only one that is supported. The uncompressed
size is written to the node in an 'uncomp-size' property, if -u is used.
Compression is also supported for sections. In that case the entire section is
compressed in one block, including all its contents. This means that accessing
an entry from the section required decompressing the entire section. Also, the
size of a section indicates the space that it consumes in its parent section
(and typically the image). With compression, the section may contain more data,
and the uncomp-size property indicates that, as above. The contents of the
section is compressed first, before any padding is added. This ensures that the
padding itself is not compressed, which would be a waste of time.
Automatic .dtsi inclusion
-------------------------
It is sometimes inconvenient to add a 'binman' node to the .dts file for each
board. This can be done by using #include to bring in a common file. Another
approach supported by the U-Boot build system is to automatically include
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::
<dts>-u-boot.dtsi where <dts> is the base name of the .dts file
<CONFIG_SYS_SOC>-u-boot.dtsi
<CONFIG_SYS_CPU>-u-boot.dtsi
<CONFIG_SYS_VENDOR>-u-boot.dtsi
u-boot.dtsi
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::
# Uncomment for debugging
# This shows all the files that were considered and the one that we chose.
# u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw)
Entry Documentation Entry Documentation
------------------- -------------------
@@ -537,6 +794,9 @@ 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
Managing images
===============
Listing images Listing images
-------------- --------------
@@ -653,27 +913,9 @@ by increasing the -v/--verbosity from the default of 1:
You can use BINMAN_VERBOSE=5 (for example) when building to select this. You can use BINMAN_VERBOSE=5 (for example) when building to select this.
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::
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
sections can be hased if desired, by adding the 'hash' node to the section.
The has value can be chcked at runtime by hashing the data actually read and
comparing this has to the value in the device tree.
Technical details
=================
Order of image creation Order of image creation
----------------------- -----------------------
@@ -750,239 +992,6 @@ what happens in this stage.
final step. final step.
Automatic .dtsi inclusion
-------------------------
It is sometimes inconvenient to add a 'binman' node to the .dts file for each
board. This can be done by using #include to bring in a common file. Another
approach supported by the U-Boot build system is to automatically include
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::
<dts>-u-boot.dtsi where <dts> is the base name of the .dts file
<CONFIG_SYS_SOC>-u-boot.dtsi
<CONFIG_SYS_CPU>-u-boot.dtsi
<CONFIG_SYS_VENDOR>-u-boot.dtsi
u-boot.dtsi
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::
# Uncomment for debugging
# This shows all the files that were considered and the one that we chose.
# u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw)
Access to binman entry offsets at run time (symbols)
----------------------------------------------------
Binman assembles images and determines where each entry is placed in the image.
This information may be useful to U-Boot at run time. For example, in SPL it
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::
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::
ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos);
Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming
that the whole image has been loaded, or is available in flash. You can then
jump to that address to start U-Boot.
At present this feature is only supported in SPL and TPL. In principle it is
possible to fill in such symbols in U-Boot proper, as well, but a future C
library is planned for this instead, to read from the device tree.
As well as image-pos, it is possible to read the size of an entry and its
offset (which is the start position of the entry within its parent).
A small technical note: Binman automatically adds the base address of the image
(i.e. __image_copy_start) to the value of the image-pos symbol, so that when the
image is loaded to its linked address, the value will be correct and actually
point into the image.
For example, say SPL is at the start of the image and linked to start at address
80108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos
for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded
to 80108000, with SPL at 80108000 and U-Boot at 80110000.
For x86 devices (with the end-at-4gb property) this base address is not added
since it is assumed that images are XIP and the offsets already include the
address.
Access to binman entry offsets at run time (fdt)
------------------------------------------------
Binman can update the U-Boot FDT to include the final position and size of
each entry in the images it processes. The option to enable this is -u and it
causes binman to make sure that the 'offset', 'image-pos' and 'size' properties
are set correctly for every entry. Since it is not necessary to specify these in
the image definition, binman calculates the final values and writes these to
the device tree. These can be used by U-Boot at run-time to find the location
of each entry.
Alternatively, an FDT map entry can be used to add a special FDT containing
just the information about the image. This is preceded by a magic string so can
be located anywhere in the image. An image header (typically at the start or end
of the image) can be used to point to the FDT map. See fdtmap and image-header
entries for more information.
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 {
};
you actually get::
u-boot {
type = "u-boot-expanded';
};
which in turn expands to::
u-boot {
type = "section";
u-boot-nodtb {
};
u-boot-dtb {
};
};
U-Boot's various phase binaries actually comprise two or three pieces.
For example, u-boot.bin has the executable followed by a devicetree.
With binman we want to be able to update that devicetree with full image
information so that it is accessible to the executable. This is tricky
if it is not clear where the devicetree starts.
The above feature ensures that the devicetree is clearly separated from the
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::
spl {
type = "u-boot-spl"
};
you actually get::
spl {
type = "u-boot-expanded';
};
which in turn expands to::
spl {
type = "section";
u-boot-spl-nodtb {
};
u-boot-spl-bss-pad {
};
u-boot-spl-dtb {
};
};
Of course we should not expand SPL if it has no devicetree. Also if the BSS
padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS),
the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned
entry type is controlled by the UseExpanded() method. In the SPL case it checks
the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree.
For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. All
entry args are provided by the U-Boot Makefile.
Compression
-----------
Binman support compression for 'blob' entries (those of type 'blob' and
derivatives). To enable this for an entry, add a 'compress' property::
blob {
filename = "datafile";
compress = "lz4";
};
The entry will then contain the compressed data, using the 'lz4' compression
algorithm. Currently this is the only one that is supported. The uncompressed
size is written to the node in an 'uncomp-size' property, if -u is used.
Compression is also supported for sections. In that case the entire section is
compressed in one block, including all its contents. This means that accessing
an entry from the section required decompressing the entire section. Also, the
size of a section indicates the space that it consumes in its parent section
(and typically the image). With compression, the section may contain more data,
and the uncomp-size property indicates that, as above. The contents of the
section is compressed first, before any padding is added. This ensures that the
padding itself is not compressed, which would be a waste of time.
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::
Offset Size Name
00000000 00000028 main-section
00000000 00000010 section@0
00000000 00000004 u-boot
00000010 00000010 section@1
00000000 00000004 u-boot
This shows a hierarchical image with two sections, each with a single entry. The
offsets of the sections are absolute hex byte offsets within the image. The
offsets of the entries are relative to their respective sections. The size of
each entry is also shown, in bytes (hex). The indentation shows the entries
nested inside their sections.
Passing command-line arguments to entries
-----------------------------------------
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::
-a<prop>=<value>
where::
<prop> is the property to set
<value> is the value to set it to
Not all properties can be provided this way. Only some entries support it,
typically for filenames.
External tools External tools
-------------- --------------
@@ -1050,8 +1059,8 @@ Then, you can run the tests under cross-compilation::
You can also use gcc-i686-linux-gnu similar to the above. You can also use gcc-i686-linux-gnu similar to the above.
Advanced Features / Technical docs Writing new entries and debugging
---------------------------------- ---------------------------------
The behaviour of entries is defined by the Entry class. All other entries are The behaviour of entries is defined by the Entry class. All other entries are
a subclass of this. An important subclass is Entry_blob which takes binary a subclass of this. An important subclass is Entry_blob which takes binary