Merge tag 'u-boot-imx-20211020' of https://source.denx.de/u-boot/custodians/u-boot-imx

[platform/kernel/u-boot.git] / tools / binman / binman.rst

diff --git a/tools/binman/binman.rst b/tools/binman/binman.rst
index 28cb2e7..614df54 100644 (file)
--- a/tools/binman/binman.rst
+++ b/tools/binman/binman.rst
@@ -232,6 +232,26 @@ You can use other, more specific CONFIG options - see 'Automatic .dtsi
 inclusion' below.
 
 
+Using binman with OF_BOARD
+--------------------------------------------
+
+Normally binman is used with a board configured with OF_SEPARATE or OF_EMBED.
+This is a typical scenario where a device tree source that contains the binman
+node is provided in the arch/<arch>/dts directory for a specific board.
+
+However for a board configured with OF_BOARD, no device tree blob is provided
+in the U-Boot build phase hence the binman node information is not available.
+In order to support such use case, a new Kconfig option BINMAN_STANDALONE_FDT
+is introduced, to tell the build system that a standalone device tree blob
+containing binman node is explicitly required.
+
+Note there is a Kconfig option BINMAN_FDT which enables U-Boot run time to
+access information about binman entries, stored in the device tree in a binman
+node. Generally speaking, this option makes sense for OF_SEPARATE or OF_EMBED.
+For the other OF_CONTROL methods, it's quite possible binman node is not
+available as binman is invoked during the build phase, thus this option is not
+turned on by default for these OF_CONTROL methods.
+
 Access to binman entry offsets at run time (symbols)
 ----------------------------------------------------
 
@@ -322,9 +342,9 @@ 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>
+    -a <prop>=<value>
 
 where::
 
@@ -562,6 +582,13 @@ skip-at-start:
     'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE +
     Image size != 4gb.
 
+align-default:
+    Specifies the default alignment for entries in this section, if they do
+    not specify an alignment. Note that this only applies to top-level entries
+    in the section (direct subentries), not any subentries of those entries.
+    This means that each section must specify its own default alignment, if
+    required.
+
 Examples of the above options can be found in the tests. See the
 tools/binman/test directory.
 
@@ -1111,6 +1138,22 @@ adds a -v<level> option to the call to binman::
    make BINMAN_VERBOSE=5
 
 
+Building sections in parallel
+-----------------------------
+
+By default binman uses multiprocessing to speed up compilation of large images.
+This works at a section level, with one thread for each entry in the section.
+This can speed things up if the entries are large and use compression.
+
+This feature can be disabled with the '-T' flag, which defaults to a suitable
+value for your machine. This depends on the Python version, e.g on v3.8 it uses
+12 threads on an 8-core machine. See ConcurrentFutures_ for more details.
+
+The special value -T0 selects single-threaded mode, useful for debugging during
+development, since dealing with exceptions and problems in threads is more
+difficult. This avoids any use of ThreadPoolExecutor.
+
+
 History / Credits
 -----------------
 
@@ -1159,3 +1202,5 @@ Some ideas:
 --
 Simon Glass <sjg@chromium.org>
 7/7/2016
+
+.. _ConcurrentFutures: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor