binman: Automatically expand phase binaries into sections
When creating an entry, check for an expanded version of that entry, then
use it instead. This allows, for example use of:
u-boot {
};
instead of having to write out in full:
u-boot {
type = "section";
u-boot-nodtb {
};
u-boot-dtb {
};
};
Add an implementaion of this and associated documentation.
Signed-off-by: Simon Glass <sjg@chromium.org>
diff --git a/tools/binman/README.entries b/tools/binman/README.entries
index 368c976..0d9105e 100644
--- a/tools/binman/README.entries
+++ b/tools/binman/README.entries
@@ -87,6 +87,15 @@
+Entry: blob-phase: Section that holds a phase binary
+----------------------------------------------------
+
+This is a base class that should not normally be used directly. It is used
+when converting a 'u-boot' entry automatically into a 'u-boot-expanded'
+entry; similarly for SPL.
+
+
+
Entry: cbfs: Entry containing a Coreboot Filesystem (CBFS)
----------------------------------------------------------
@@ -840,8 +849,7 @@
This is the U-Boot binary, containing relocation information to allow it
to relocate itself at runtime. The binary typically includes a device tree
-blob at the end of it. Use u-boot-nodtb if you want to package the device
-tree separately.
+blob at the end of it.
U-Boot can access binman symbols at runtime. See:
@@ -849,8 +857,11 @@
in the binman README for more information.
+Note that this entry is automatically replaced with u-boot-expanded unless
+--no-expanded is used.
+
Entry: u-boot-dtb: U-Boot device tree
-------------------------------------
@@ -901,6 +912,21 @@
form var=value
+
+Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
+------------------------------------------------------------------------------
+
+This is a section containing the U-Boot binary and a devicetree. Using this
+entry type automatically creates this section, with the following entries
+in it:
+
+ u-boot-nodtb
+ u-boot-dtb
+
+Having the devicetree separate allows binman to update it in the final
+image, so that the entries positions are provided to the running U-Boot.
+
+
Entry: u-boot-img: U-Boot legacy image
--------------------------------------
@@ -925,8 +951,8 @@
This is the U-Boot binary, containing relocation information to allow it
to relocate itself at runtime. It does not include a device tree blob at
the end of it so normally cannot work without it. You can add a u-boot-dtb
-entry after this one, or use a u-boot entry instead (which contains both
-U-Boot and the device tree).
+entry after this one, or use a u-boot entry instead, normally expands to a
+section containing u-boot and u-boot-dtb
@@ -952,6 +978,9 @@
The ELF file 'spl/u-boot-spl' must also be available for this to work, since
binman uses that to look up symbols to write into the SPL binary.
+Note that this entry is automatically replaced with u-boot-spl-expanded
+unless --no-expanded is used.
+
Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
@@ -997,8 +1026,31 @@
This is the U-Boot SPL ELF image. It does not include a device tree but can
be relocated to any address for execution.
+
+
+Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
+--------------------------------------------------------------------------------------
+
+Properties / Entry arguments:
+ - spl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
+ select)
+
+This is a section containing the U-Boot binary, BSS padding if needed and a
+devicetree. Using this entry type automatically creates this section, with
+the following entries in it:
+
+ u-boot-spl-nodtb
+ u-boot-spl-bss-pad
+ u-boot-dtb
+
+Having the devicetree separate allows binman to update it in the final
+image, so that the entries positions are provided to the running U-Boot.
+
+This entry is selected based on the value of the 'spl-dtb' entryarg. If
+this is non-empty (and not 'n' or '0') then this expanded entry is selected.
+
Entry: u-boot-spl-nodtb: SPL binary without device tree appended
----------------------------------------------------------------
@@ -1008,8 +1060,9 @@
This is the U-Boot SPL binary, It does not include a device tree blob at
the end of it so may not be able to work without it, assuming SPL needs
a device tree to operate on your platform. You can add a u-boot-spl-dtb
-entry after this one, or use a u-boot-spl entry instead (which contains
-both SPL and the device tree).
+entry after this one, or use a u-boot-spl entry instead' which normally
+expands to a section containing u-boot-spl-dtb, u-boot-spl-bss-pad and
+u-boot-spl-dtb
SPL can access binman symbols at runtime. See:
@@ -1054,6 +1107,9 @@
The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
binman uses that to look up symbols to write into the TPL binary.
+Note that this entry is automatically replaced with u-boot-tpl-expanded
+unless --no-expanded is used.
+
Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
@@ -1111,6 +1167,29 @@
+Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
+--------------------------------------------------------------------------------------
+
+Properties / Entry arguments:
+ - tpl-dtb: Controls whether this entry is selected (set to 'y' or '1' to
+ select)
+
+This is a section containing the U-Boot binary, BSS padding if needed and a
+devicetree. Using this entry type automatically creates this section, with
+the following entries in it:
+
+ u-boot-tpl-nodtb
+ u-boot-tpl-bss-pad
+ u-boot-dtb
+
+Having the devicetree separate allows binman to update it in the final
+image, so that the entries positions are provided to the running U-Boot.
+
+This entry is selected based on the value of the 'tpl-dtb' entryarg. If
+this is non-empty (and not 'n' or '0') then this expanded entry is selected.
+
+
+
Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
----------------------------------------------------------------
@@ -1120,8 +1199,9 @@
This is the U-Boot TPL binary, It does not include a device tree blob at
the end of it so may not be able to work without it, assuming TPL needs
a device tree to operate on your platform. You can add a u-boot-tpl-dtb
-entry after this one, or use a u-boot-tpl entry instead (which contains
-both TPL and the device tree).
+entry after this one, or use a u-boot-tpl entry instead, which normally
+expands to a section containing u-boot-tpl-dtb, u-boot-tpl-bss-pad and
+u-boot-tpl-dtb
TPL can access binman symbols at runtime. See: