brain-hackers_pepepper-mirror
/
u-boot-brain
mirror of https://github.com/brain-hackers/u-boot-brain
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

binman: Update various pieces of the documentation 

A few sections are a little out of date now. Update them.

Signed-off-by: Simon Glass <sjg@chromium.org>
This commit is contained in:
Simon Glass 2021-03-18 20:25:17 +13:00
parent 96d340e9f6
commit fcae6682a7
2 changed files with 45 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/develop/package/entries.rst Symbolic link
View File

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

83
tools/binman/binman.rst
View File

@ -9,39 +9,43 @@ For example, we may have SPL, U-Boot, a device tree and an environment area
grouped together and placed in MMC flash. When the system starts, it must be grouped together and placed in MMC flash. When the system starts, it must be
able to find these pieces. able to find these pieces.
So far U-Boot has not provided a way to handle creating such images in a Building firmware should be separate from packaging it. Many of the complexities
general way. Each SoC does what it needs to build an image, often packing or of modern firmware build systems come from trying to do both at once. With
concatenating images in the U-Boot build system. binman, you build all the pieces that are needed, using whatever assortment of
projects and build systems are needed, then use binman to stitch everything
Binman aims to provide a mechanism for building images, from simple together.
SPL + U-Boot combinations, to more complex arrangements with many parts.
What it does What it does
------------ ------------
Binman reads your board's device tree and finds a node which describes the Binman reads your board's device tree and finds a node which describes the
required image layout. It uses this to work out what to place where. The required image layout. It uses this to work out what to place where.
output file normally contains the device tree, so it is in principle possible
to read an image and extract its constituent parts. Binman provides a mechanism for building images, from simple SPL + U-Boot
combinations, to more complex arrangements with many parts. It also allows
users to inspect images, extract and replace binaries within them, repacking if
needed.
Features Features
-------- --------
So far binman is pretty simple. It supports binary blobs, such as 'u-boot', Apart from basic padding, alignment and positioning features, Binman supports
'spl' and 'fdt'. It supports empty entries (such as setting to 0xff). It can hierarchical images, compression, hashing and dealing with the binary blobs
place entries at a fixed location in the image, or fit them together with which are a sad trend in open-source firmware at present.
suitable padding and alignment. It provides a way to process binaries before
they are included, by adding a Python plug-in. The device tree is available
to U-Boot at run-time so that the images can be interpreted.
Binman can update the device tree with the final location of everything when it Executable binaries can access the location of other binaries in an image by
is done. Entry positions can be provided to U-Boot SPL as run-time symbols, using special linker symbols (zero-overhead but somewhat limited) or by reading
avoiding device-tree code overhead. the devicetree description of the image.
Binman can also support incorporating filesystems in the image if required. Binman is designed primarily for use with U-Boot and associated binaries such
For example x86 platforms may use CBFS in some cases. as ARM Trusted Firmware, but it is suitable for use with other projects, such
as Zephyr. Binman also provides facilities useful in Chromium OS, such as CBFS,
vblocks and and the like.
Binman provides a way to process binaries before they are included, by adding a
Python plug-in.
Binman is intended for use with U-Boot but is designed to be general enough Binman is intended for use with U-Boot but is designed to be general enough
to be useful in other image-packaging situations. to be useful in other image-packaging situations.
@ -50,11 +54,11 @@ to be useful in other image-packaging situations.
Motivation Motivation
---------- ----------
Packaging of firmware is quite a different task from building the various As mentioned above, packaging of firmware is quite a different task from
parts. In many cases the various binaries which go into the image come from building the various parts. In many cases the various binaries which go into
separate build systems. For example, ARM Trusted Firmware is used on ARMv8 the image come from separate build systems. For example, ARM Trusted Firmware
devices but is not built in the U-Boot tree. If a Linux kernel is included is used on ARMv8 devices but is not built in the U-Boot tree. If a Linux kernel
in the firmware image, it is built elsewhere. is included in the firmware image, it is built elsewhere.
It is of course possible to add more and more build rules to the U-Boot It is of course possible to add more and more build rules to the U-Boot
build system to cover these cases. It can shell out to other Makefiles and build system to cover these cases. It can shell out to other Makefiles and
@ -215,17 +219,12 @@ Binman has a few other options which you can see by running 'binman -h'.
Enabling binman for a board Enabling binman for a board
--------------------------- ---------------------------
At present binman is invoked from a rule in the main Makefile. Typically you At present binman is invoked from a rule in the main Makefile. You should be
will have a rule like:: able to enable CONFIG_BINMAN to enable this rule.
ifneq ($(CONFIG_ARCH_<something>),) The output file is typically named image.bin and is located in the output
u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE directory. If input files are needed to you add these to INPUTS-y either in the
$(call if_changed,binman) main Makefile or in a config.mk file in your arch subdirectory.
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
either in the main Makefile or in a config.mk file in your arch subdirectory.
Once binman is executed it will pick up its instructions from a device-tree Once binman is executed it will pick up its instructions from a device-tree
file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value. file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value.
@ -786,12 +785,17 @@ the 'warning' line in scripts/Makefile.lib to see what it has found::
Entry Documentation Entry Documentation
------------------- ===================
For details on the various entry types supported by binman and how to use them, 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: see entries.rst which is generated from the source code using:
binman entry-docs >tools/binman/README.entries binman entry-docs >tools/binman/entries.rst
.. toctree::
:maxdepth: 2
entries
Managing images Managing images
@ -1136,7 +1140,8 @@ To do
Some ideas: Some ideas:
- Use of-platdata to make the information available to code that is unable - Use of-platdata to make the information available to code that is unable
to use device tree (such as a very small SPL image) to use device tree (such as a very small SPL image). For now, limited info is
available via linker symbols
- Allow easy building of images by specifying just the board name - Allow easy building of images by specifying just the board name
- Support building an image for a board (-b) more completely, with a - Support building an image for a board (-b) more completely, with a
configurable build directory configurable build directory