binman: Support packaging U-Boot for scenarios like OF_BOARD or OF_PRIOR_STAGE

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

diff --git a/tools/binman/binman.rst b/tools/binman/binman.rst
index 15314d1..bc635aa 100644 (file)
--- a/tools/binman/binman.rst
+++ b/tools/binman/binman.rst
@@ -232,6 +232,30 @@ You can use other, more specific CONFIG options - see 'Automatic .dtsi
 inclusion' below.
 
 
+Using binman with OF_BOARD or OF_PRIOR_STAGE
+--------------------------------------------
+
+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 or OF_PRIOR_STAGE, 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.
+
+See qemu-riscv64_spl_defconfig for an example of how binman is used with
+OF_PRIOR_STAGE to generate u-boot.itb image.
+
+
 Access to binman entry offsets at run time (symbols)
 ----------------------------------------------------
 
@@ -322,9 +346,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::
 
@@ -472,6 +496,13 @@ missing-msg:
     information about what needs to be fixed. See missing-blob-help for the
     message for each tag.
 
+no-expanded:
+    By default binman substitutes entries with expanded versions if available,
+    so that a `u-boot` entry type turns into `u-boot-expanded`, for example. The
+    `--no-expanded` command-line option disables this globally. The
+    `no-expanded` property disables this just for a single entry. Put the
+    `no-expanded` boolean property in the node to select this behaviour.
+
 The attributes supported for images and sections are described below. Several
 are similar to those for entries.
 
@@ -555,6 +586,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.