mirror of
https://github.com/brain-hackers/u-boot-brain
synced 2024-06-09 23:36:03 +09:00
binman: doc: Add documentation to htmldocs
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
parent
5ce319133b
commit
61adb2d247
|
|
@ -26,6 +26,14 @@ Debugging
|
|||
crash_dumps
|
||||
trace
|
||||
|
||||
Packaging
|
||||
---------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
package/index
|
||||
|
||||
Testing
|
||||
-------
|
||||
|
||||
|
|
|
|||
1
doc/develop/package/binman.rst
Symbolic link
1
doc/develop/package/binman.rst
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
../../../tools/binman/binman.rst
|
||||
19
doc/develop/package/index.rst
Normal file
19
doc/develop/package/index.rst
Normal 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
8
doc/usage/fit.rst
Normal 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
|
||||
|
|
@ -5,6 +5,7 @@ Use U-Boot
|
|||
:maxdepth: 1
|
||||
|
||||
fdt_overlays
|
||||
fit
|
||||
netconsole
|
||||
partitions
|
||||
|
||||
|
|
|
|||
1
tools/binman/README.rst
Symbolic link
1
tools/binman/README.rst
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
binman.rst
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
9
tools/binman/index.rst
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
.. SPDX-License-Identifier: GPL-2.0+
|
||||
|
||||
Binman
|
||||
======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
README
|
||||
|
|
@ -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'])
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user