[PATCH 1/2] binman: Add rST references for binman entry types

[PATCH 1/2] binman: Add rST references for binman entry types

[Simon Glass]

Add references in the documentation for each entry type, so we can refer
to them from other documentation.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

 tools/binman/entries.rst | 146 ++++++++++++++++++++++++++++++++++++++-
 tools/binman/entry.py    |   5 ++
 2 files changed, 150 insertions(+), 1 deletion(-)

diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst
index ae4305c99e4..782bff1f8d9 100644
--- a/tools/binman/entries.rst
+++ b/tools/binman/entries.rst
@@ -11,6 +11,8 @@ features to produce new behaviours.
 
 
 
+.. _etype_atf_bl31:
+
 Entry: atf-bl31: ARM Trusted Firmware (ATF) BL31 blob
 -----------------------------------------------------
 
@@ -25,6 +27,8 @@ about ATF.
 
 
 
+.. _etype_atf_fip:
+
 Entry: atf-fip: ARM Trusted Firmware's Firmware Image Package (FIP)
 -------------------------------------------------------------------
 
@@ -179,6 +183,8 @@ FIPs so that binman and other tools can access the entire image correctly.
 
 
 
+.. _etype_blob:
+
 Entry: blob: Arbitrary binary blob
 ----------------------------------
 
@@ -201,6 +207,8 @@ data.
 
 
 
+.. _etype_blob_dtb:
+
 Entry: blob-dtb: A blob that holds a device tree
 ------------------------------------------------
 
@@ -210,6 +218,8 @@ obtained from the list of available device-tree files, managed by the
 
 
 
+.. _etype_blob_ext:
+
 Entry: blob-ext: Externally built binary blob
 ---------------------------------------------
 
@@ -223,6 +233,8 @@ See 'blob' for Properties / Entry arguments.
 
 
 
+.. _etype_blob_ext_list:
+
 Entry: blob-ext-list: List of externally built binary blobs
 -----------------------------------------------------------
 
@@ -237,6 +249,8 @@ Args:
 
 
 
+.. _etype_blob_named_by_arg:
+
 Entry: blob-named-by-arg: A blob entry which gets its filename property from its subclass
 -----------------------------------------------------------------------------------------
 
@@ -255,6 +269,8 @@ See cros_ec_rw for an example of this.
 
 
 
+.. _etype_blob_phase:
+
 Entry: blob-phase: Section that holds a phase binary
 ----------------------------------------------------
 
@@ -264,6 +280,8 @@ entry; similarly for SPL.
 
 
 
+.. _etype_cbfs:
+
 Entry: cbfs: Coreboot Filesystem (CBFS)
 ---------------------------------------
 
@@ -416,6 +434,8 @@ both of size 1MB.
 
 
 
+.. _etype_collection:
+
 Entry: collection: An entry which contains a collection of other entries
 ------------------------------------------------------------------------
 
@@ -429,6 +449,8 @@ the image, not necessarily child entries.
 
 
 
+.. _etype_cros_ec_rw:
+
 Entry: cros-ec-rw: A blob entry which contains a Chromium OS read-write EC image
 --------------------------------------------------------------------------------
 
@@ -440,6 +462,8 @@ updating the EC on startup via software sync.
 
 
 
+.. _etype_fdtmap:
+
 Entry: fdtmap: An entry which contains an FDT map
 -------------------------------------------------
 
@@ -488,6 +512,8 @@ without the fdtmap header, so it can be viewed with `fdtdump`.
 
 
 
+.. _etype_files:
+
 Entry: files: A set of files arranged in a section
 --------------------------------------------------
 
@@ -504,6 +530,8 @@ at run-time so you can obtain the file positions.
 
 
 
+.. _etype_fill:
+
 Entry: fill: An entry which is filled to a particular byte value
 ----------------------------------------------------------------
 
@@ -520,6 +548,8 @@ byte value of a region.
 
 
 
+.. _etype_fit:
+
 Entry: fit: Flat Image Tree (FIT)
 ---------------------------------
 
@@ -803,6 +833,8 @@ U-Boot SPL can then load the firmware (U-Boot proper) and all the loadables
 
 
 
+.. _etype_fmap:
+
 Entry: fmap: An entry which contains an Fmap section
 ----------------------------------------------------
 
@@ -828,6 +860,8 @@ CBFS entries appear as a single entry, i.e. the sub-entries are ignored.
 
 
 
+.. _etype_gbb:
+
 Entry: gbb: An entry which contains a Chromium OS Google Binary Block
 ---------------------------------------------------------------------
 
@@ -847,6 +881,8 @@ README.chromium for how to obtain the required keys and tools.
 
 
 
+.. _etype_image_header:
+
 Entry: image-header: An entry which contains a pointer to the FDT map
 ---------------------------------------------------------------------
 
@@ -866,6 +902,8 @@ first/last in the entry list.
 
 
 
+.. _etype_intel_cmc:
+
 Entry: intel-cmc: Intel Chipset Micro Code (CMC) file
 -----------------------------------------------------
 
@@ -879,6 +917,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_descriptor:
+
 Entry: intel-descriptor: Intel flash descriptor block (4KB)
 -----------------------------------------------------------
 
@@ -900,6 +940,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_fit:
+
 Entry: intel-fit: Intel Firmware Image Table (FIT)
 --------------------------------------------------
 
@@ -911,6 +953,8 @@ At present binman only supports a basic FIT with no microcode.
 
 
 
+.. _etype_intel_fit_ptr:
+
 Entry: intel-fit-ptr: Intel Firmware Image Table (FIT) pointer
 --------------------------------------------------------------
 
@@ -919,6 +963,8 @@ This entry contains a pointer to the FIT. It is required to be at address
 
 
 
+.. _etype_intel_fsp:
+
 Entry: intel-fsp: Intel Firmware Support Package (FSP) file
 -----------------------------------------------------------
 
@@ -936,6 +982,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_fsp_m:
+
 Entry: intel-fsp-m: Intel Firmware Support Package (FSP) memory init
 --------------------------------------------------------------------
 
@@ -953,6 +1001,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_fsp_s:
+
 Entry: intel-fsp-s: Intel Firmware Support Package (FSP) silicon init
 ---------------------------------------------------------------------
 
@@ -970,6 +1020,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_fsp_t:
+
 Entry: intel-fsp-t: Intel Firmware Support Package (FSP) temp ram init
 ----------------------------------------------------------------------
 
@@ -986,6 +1038,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_ifwi:
+
 Entry: intel-ifwi: Intel Integrated Firmware Image (IFWI) file
 --------------------------------------------------------------
 
@@ -1020,6 +1074,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_me:
+
 Entry: intel-me: Intel Management Engine (ME) file
 --------------------------------------------------
 
@@ -1040,6 +1096,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_mrc:
+
 Entry: intel-mrc: Intel Memory Reference Code (MRC) file
 --------------------------------------------------------
 
@@ -1054,6 +1112,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_refcode:
+
 Entry: intel-refcode: Intel Reference Code file
 -----------------------------------------------
 
@@ -1068,6 +1128,8 @@ See README.x86 for information about x86 binary blobs.
 
 
 
+.. _etype_intel_vbt:
+
 Entry: intel-vbt: Intel Video BIOS Table (VBT) file
 ---------------------------------------------------
 
@@ -1081,6 +1143,8 @@ See README.x86 for information about Intel binary blobs.
 
 
 
+.. _etype_intel_vga:
+
 Entry: intel-vga: Intel Video Graphics Adaptor (VGA) file
 ---------------------------------------------------------
 
@@ -1096,6 +1160,8 @@ See README.x86 for information about Intel binary blobs.
 
 
 
+.. _etype_mkimage:
+
 Entry: mkimage: Binary produced by mkimage
 ------------------------------------------
 
@@ -1130,6 +1196,8 @@ this example which also produces four arguments::
 
 
 
+.. _etype_opensbi:
+
 Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
 ----------------------------------------------
 
@@ -1143,6 +1211,8 @@ https://github.com/riscv/opensbi for more information about OpenSBI.
 
 
 
+.. _etype_powerpc_mpc85xx_bootpg_resetvec:
+
 Entry: powerpc-mpc85xx-bootpg-resetvec: PowerPC mpc85xx bootpg + resetvec code for U-Boot
 -----------------------------------------------------------------------------------------
 
@@ -1155,11 +1225,13 @@ placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.
 
 
 
+.. _etype_pre_load:
+
 Entry: pre-load: Pre load image header
 --------------------------------------
 
 Properties / Entry arguments:
-    - key-path: Path of the directory that store key (provided by the environment variable KEY_PATH)
+    - pre-load-key-path: Path of the directory that store key (provided by the environment variable PRE_LOAD_KEY_PATH)
     - content: List of phandles to entries to sign
     - algo-name: Hash and signature algo to use for the signature
     - padding-name: Name of the padding (pkcs-1.5 or pss)
@@ -1193,6 +1265,8 @@ For example, this creates an image with a pre-load header and a binary::
 
 
 
+.. _etype_scp:
+
 Entry: scp: System Control Processor (SCP) firmware blob
 --------------------------------------------------------
 
@@ -1203,6 +1277,8 @@ This entry holds firmware for an external platform-specific coprocessor.
 
 
 
+.. _etype_section:
+
 Entry: section: Entry that contains other entries
 -------------------------------------------------
 
@@ -1338,6 +1414,8 @@ available. This is set by the `SetAllowMissing()` method, if
 
 
 
+.. _etype_tee_os:
+
 Entry: tee-os: Entry containing an OP-TEE Trusted OS (TEE) blob
 ---------------------------------------------------------------
 
@@ -1351,6 +1429,8 @@ https://github.com/OP-TEE/optee_os for more information about OP-TEE.
 
 
 
+.. _etype_text:
+
 Entry: text: An entry which contains text
 -----------------------------------------
 
@@ -1399,6 +1479,8 @@ by setting the size of the entry to something larger than the text.
 
 
 
+.. _etype_u_boot:
+
 Entry: u-boot: U-Boot flat binary
 ---------------------------------
 
@@ -1420,6 +1502,8 @@ Note that this entry is automatically replaced with u-boot-expanded unless
 
 
 
+.. _etype_u_boot_dtb:
+
 Entry: u-boot-dtb: U-Boot device tree
 -------------------------------------
 
@@ -1435,6 +1519,8 @@ binman to know which entries contain a device tree.
 
 
 
+.. _etype_u_boot_dtb_with_ucode:
+
 Entry: u-boot-dtb-with-ucode: A U-Boot device tree file, with the microcode removed
 -----------------------------------------------------------------------------------
 
@@ -1451,6 +1537,8 @@ it available to u-boot-ucode.
 
 
 
+.. _etype_u_boot_elf:
+
 Entry: u-boot-elf: U-Boot ELF image
 -----------------------------------
 
@@ -1462,6 +1550,8 @@ relocated to any address for execution.
 
 
 
+.. _etype_u_boot_env:
+
 Entry: u-boot-env: An entry which contains a U-Boot environment
 ---------------------------------------------------------------
 
@@ -1471,6 +1561,8 @@ Properties / Entry arguments:
 
 
 
+.. _etype_u_boot_expanded:
+
 Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
 ------------------------------------------------------------------------------
 
@@ -1486,6 +1578,8 @@ image, so that the entries positions are provided to the running U-Boot.
 
 
 
+.. _etype_u_boot_img:
+
 Entry: u-boot-img: U-Boot legacy image
 --------------------------------------
 
@@ -1500,6 +1594,8 @@ applications.
 
 
 
+.. _etype_u_boot_nodtb:
+
 Entry: u-boot-nodtb: U-Boot flat binary without device tree appended
 --------------------------------------------------------------------
 
@@ -1514,6 +1610,8 @@ section containing u-boot and u-boot-dtb
 
 
 
+.. _etype_u_boot_spl:
+
 Entry: u-boot-spl: U-Boot SPL binary
 ------------------------------------
 
@@ -1541,6 +1639,8 @@ unless --no-expanded is used or the node has a 'no-expanded' property.
 
 
 
+.. _etype_u_boot_spl_bss_pad:
+
 Entry: u-boot-spl-bss-pad: U-Boot SPL binary padded with a BSS region
 ---------------------------------------------------------------------
 
@@ -1563,6 +1663,8 @@ binman uses that to look up the BSS address.
 
 
 
+.. _etype_u_boot_spl_dtb:
+
 Entry: u-boot-spl-dtb: U-Boot SPL device tree
 ---------------------------------------------
 
@@ -1575,6 +1677,8 @@ to activate.
 
 
 
+.. _etype_u_boot_spl_elf:
+
 Entry: u-boot-spl-elf: U-Boot SPL ELF image
 -------------------------------------------
 
@@ -1586,6 +1690,8 @@ be relocated to any address for execution.
 
 
 
+.. _etype_u_boot_spl_expanded:
+
 Entry: u-boot-spl-expanded: U-Boot SPL flat binary broken out into its component parts
 --------------------------------------------------------------------------------------
 
@@ -1609,6 +1715,8 @@ this is non-empty (and not 'n' or '0') then this expanded entry is selected.
 
 
 
+.. _etype_u_boot_spl_nodtb:
+
 Entry: u-boot-spl-nodtb: SPL binary without device tree appended
 ----------------------------------------------------------------
 
@@ -1633,6 +1741,8 @@ binman uses that to look up symbols to write into the SPL binary.
 
 
 
+.. _etype_u_boot_spl_with_ucode_ptr:
+
 Entry: u-boot-spl-with-ucode-ptr: U-Boot SPL with embedded microcode pointer
 ----------------------------------------------------------------------------
 
@@ -1643,6 +1753,8 @@ process.
 
 
 
+.. _etype_u_boot_tpl:
+
 Entry: u-boot-tpl: U-Boot TPL binary
 ------------------------------------
 
@@ -1670,6 +1782,8 @@ unless --no-expanded is used or the node has a 'no-expanded' property.
 
 
 
+.. _etype_u_boot_tpl_bss_pad:
+
 Entry: u-boot-tpl-bss-pad: U-Boot TPL binary padded with a BSS region
 ---------------------------------------------------------------------
 
@@ -1692,6 +1806,8 @@ binman uses that to look up the BSS address.
 
 
 
+.. _etype_u_boot_tpl_dtb:
+
 Entry: u-boot-tpl-dtb: U-Boot TPL device tree
 ---------------------------------------------
 
@@ -1704,6 +1820,8 @@ to activate.
 
 
 
+.. _etype_u_boot_tpl_dtb_with_ucode:
+
 Entry: u-boot-tpl-dtb-with-ucode: U-Boot TPL with embedded microcode pointer
 ----------------------------------------------------------------------------
 
@@ -1714,6 +1832,8 @@ process.
 
 
 
+.. _etype_u_boot_tpl_elf:
+
 Entry: u-boot-tpl-elf: U-Boot TPL ELF image
 -------------------------------------------
 
@@ -1725,6 +1845,8 @@ be relocated to any address for execution.
 
 
 
+.. _etype_u_boot_tpl_expanded:
+
 Entry: u-boot-tpl-expanded: U-Boot TPL flat binary broken out into its component parts
 --------------------------------------------------------------------------------------
 
@@ -1748,6 +1870,8 @@ this is non-empty (and not 'n' or '0') then this expanded entry is selected.
 
 
 
+.. _etype_u_boot_tpl_nodtb:
+
 Entry: u-boot-tpl-nodtb: TPL binary without device tree appended
 ----------------------------------------------------------------
 
@@ -1772,6 +1896,8 @@ binman uses that to look up symbols to write into the TPL binary.
 
 
 
+.. _etype_u_boot_tpl_with_ucode_ptr:
+
 Entry: u-boot-tpl-with-ucode-ptr: U-Boot TPL with embedded microcode pointer
 ----------------------------------------------------------------------------
 
@@ -1780,6 +1906,8 @@ process.
 
 
 
+.. _etype_u_boot_ucode:
+
 Entry: u-boot-ucode: U-Boot microcode block
 -------------------------------------------
 
@@ -1830,6 +1958,8 @@ Entry types that have a part to play in handling microcode:
 
 
 
+.. _etype_u_boot_with_ucode_ptr:
+
 Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
 --------------------------------------------------------------------
 
@@ -1846,6 +1976,8 @@ complicated. Otherwise it is the same as the u-boot entry.
 
 
 
+.. _etype_vblock:
+
 Entry: vblock: An entry which contains a Chromium OS verified boot block
 ------------------------------------------------------------------------
 
@@ -1869,6 +2001,8 @@ and kernel are genuine.
 
 
 
+.. _etype_x86_reset16:
+
 Entry: x86-reset16: x86 16-bit reset code for U-Boot
 ----------------------------------------------------
 
@@ -1885,6 +2019,8 @@ For 64-bit U-Boot, the 'x86_reset16_spl' entry type is used instead.
 
 
 
+.. _etype_x86_reset16_spl:
+
 Entry: x86-reset16-spl: x86 16-bit reset code for U-Boot
 --------------------------------------------------------
 
@@ -1901,6 +2037,8 @@ For 32-bit U-Boot, the 'x86_reset_spl' entry type is used instead.
 
 
 
+.. _etype_x86_reset16_tpl:
+
 Entry: x86-reset16-tpl: x86 16-bit reset code for U-Boot
 --------------------------------------------------------
 
@@ -1917,6 +2055,8 @@ For 32-bit U-Boot, the 'x86_reset_tpl' entry type is used instead.
 
 
 
+.. _etype_x86_start16:
+
 Entry: x86-start16: x86 16-bit start-up code for U-Boot
 -------------------------------------------------------
 
@@ -1935,6 +2075,8 @@ For 64-bit U-Boot, the 'x86_start16_spl' entry type is used instead.
 
 
 
+.. _etype_x86_start16_spl:
+
 Entry: x86-start16-spl: x86 16-bit start-up code for SPL
 --------------------------------------------------------
 
@@ -1953,6 +2095,8 @@ For 32-bit U-Boot, the 'x86-start16' entry type is used instead.
 
 
 
+.. _etype_x86_start16_tpl:
+
 Entry: x86-start16-tpl: x86 16-bit start-up code for TPL
 --------------------------------------------------------
 
diff --git a/tools/binman/entry.py b/tools/binman/entry.py
index a07a5888643..e3767aefa73 100644
--- a/tools/binman/entry.py
+++ b/tools/binman/entry.py
@@ -750,6 +750,11 @@ features to produce new behaviours.
                 first_line = lines[0]
                 rest = [line[4:] for line in lines[1:]]
                 hdr = 'Entry: %s: %s' % (name.replace('_', '-'), first_line)
+
+                # Create a reference for use by rST docs
+                ref_name = f'etype_{module.__name__[6:]}'.lower()
+                print('.. _%s:' % ref_name)
+                print()
                 print(hdr)
                 print('-' * len(hdr))
                 print('\n'.join(rest))
-- 
2.37.1.559.g78731f0fdb-goog

[PATCH 2/2] binman: Add more documentation about binman usage

[Simon Glass]

This is an attempt to answer the comments provided by Xavier [1].

[1] https://lore.kernel.org/all/Yulcol7HpTHtjXTX@begut/

Signed-off-by: Simon Glass <sjg@chromium.org>
---

 doc/Makefile            |   1 +
 tools/binman/binman.rst | 166 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 167 insertions(+)

diff --git a/doc/Makefile b/doc/Makefile
index 050d9dd2391..6081858726e 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -56,6 +56,7 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 	PYTHONDONTWRITEBYTECODE=1 \
 	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
 	$(SPHINXBUILD) \
+	-j$(shell nproc) \
 	-b $2 \
 	-c $(abspath $(srctree)/$(src)) \
 	-d $(abspath $(BUILDDIR)/.doctrees/$3) \
diff --git a/tools/binman/binman.rst b/tools/binman/binman.rst
index 935839c433e..2e5d301174d 100644
--- a/tools/binman/binman.rst
+++ b/tools/binman/binman.rst
@@ -118,6 +118,10 @@ flash.
 For U-Boot, binman should not be used to create ad-hoc images in place of
 FIT.
 
+Note that binman can itself can create a FIT. This helps to move mkimage
+invocations out of the Makefile and into binman image descriptions. It also
+helps by removing the need for ad-hoc tools like `make_fit_atf.py`.
+
 
 Relationship to mkimage
 -----------------------
@@ -140,6 +144,9 @@ seems better to use the mkimage tool to generate binaries and avoid blurring
 the boundaries between building input files (mkimage) and packaging then
 into a final image (binman).
 
+Note that binman can itself invoke mkimage. This helps to move mkimage
+invocations out of the Makefile and into binman image descriptions.
+
 
 Using binman
 ============
@@ -170,6 +177,164 @@ This simplifies the U-Boot Makefile somewhat, since various pieces of logic
 can be replaced by a call to binman.
 
 
+Invoking binman within U-Boot
+-----------------------------
+
+Within U-Boot, binman is invoked by the build system, i,e. when you type 'make'
+or use buildman to build U-Boot. There is no need to run binman independently
+during development. Everything happens automatically and is set up for your
+SoC or board so that binman produced the right things.
+
+The general policy is that the Makefile builds all the binaries in INPUTS-y
+(the 'inputs' rule), then binman is run to produce the final images (the 'all'
+rule).
+
+There should be only one invocation of binman in Makefile, the very last step
+that pulls everything together. At present there are some arch-specific
+invocations as well, but these should be dropped when those archs are converted
+to use binman propertly.
+
+As above, the term 'binary' is used for something in INPUTS-y and 'image' is
+used for the things that binman creates. So the binaries are inputs to the
+image(s) and it is the image that is actually loaded on the board.
+
+Again, at present, there are a number of things created in Makefile which should
+be done by binman (when we get around to it), like `u-boot-ivt.img`,
+`lpc32xx-spl.img`, `u-boot-with-nand-spl.imx`, `u-boot-spl-padx4.sfp` and
+`u-boot-mtk.bin`, just to pick on a few. When completed this will remove about
+400 lines from `Makefile`.
+
+Since binman is invoked only once, it must of course create all the images that
+are needed, in that one invocation. It does this by working through the image
+descriptions one by one, collecting the input binaries, processing them as
+needed and producing the final images.
+
+The same binaries may be used by multiple images. For example binman may be used
+to produce an SD-card image and a SPI-flash image. In this case the binaries
+going into the process are the same, but binman produces slifhtly different
+images in each case.
+
+For some SoCs, U-Boot is not the only project that produces the necessary
+binaries. For example, ARM Trusted Firmware (ATF) is a project that produces
+binaries which must be incorporate, such as `bl31.elf` or `bl31.bin`. For this
+to work you must have built ATF before you build U-Boot and you must tell U-Boot
+where to find the bl31 image, using the BL31 environemnt variable.
+
+How do you know how to incorporate ATF? It is handled by the atf-bl31 entry type
+(etype). An etype is an implementation of reading a binary into binman, in this
+case the `bl31.bin` file. When you build U-Boot but do not set the BL31
+environment variable, binman provides a help message, which comes from
+`missing-blob-help`::
+
+    See the documentation for your board. You may need to build ARM Trusted
+    Firmware and build with BL31=/path/to/bl31.bin
+
+The mechanism by which binman is advised of this is also in the Makefile. See
+the `-a atf-bl31-path=${BL31}` piece in `cmd_binman`. This tells binman to
+set the EntryArg `atf-bl31-path` to the value of the `BL31` environment
+variable. Within binman, this EntryArg is picked up by the `Entry_atf_bl31`
+etype. An EntryArg is simply an argument to the entry. The `atf-bl31-path`
+name is documented in :ref:`etype_atf_bl31`.
+
+
+Invoking binman outside U-Boot
+------------------------------
+
+While binman is invoked from within the U-Boot build system, it is also possible
+to invoke it separately. This is typically used in a production build system,
+where signing is completed (with real keys) and any missing binaries are
+provided.
+
+For example, for build testing there is no need to provide a real signature,
+nor is there any need to provide a real ATF BL31 binary (for example). These can
+be added later by invoking binman again, providing all the required inputs
+from the first time, plus any that were missing or placeholders.
+
+So in practice binman is often used twice:
+
+- once within the U-Boot build system, for development and testing
+- again outside U-Boot to assembly and final production images
+
+While the same inputbinaries are used in each case, you will of course you will
+need to create your own binman command line, similar to that in `cmd_binman` in
+the Makefile. You may find the -I and --toolpath options useful. The
+device tree file is provided to binman in binary form, so there is no need to
+have access to the original `.dts` sources.
+
+
+Assembling the image description
+--------------------------------
+
+Since binman uses device tree for its image description, you can use the same
+files that describe your board's hardware to describe how the image is assembled.
+Typically the images description is in a common file used by all boards with a
+particular SoC (e.g. `imx8mp-u-boot.dtsi`).
+
+Where a particular boards needs to make changes, it can override properties in
+the SoC file, just as it would for any other device tree property. It can also
+add a image that is specific to the board.
+
+Another way to control the image description to make use of CONFIG options in
+the description. For example, if the start offset of a particular entry varies
+by board, you can add a Kconfig for that and reference it in the description::
+
+    u-boot-spl {
+    };
+
+    fit {
+        offset = <CONFIG_SPL_PAD_TO>;
+        ...
+    };
+
+The SoC can provide a default value but boards can override that as needed and
+binman will take care of it.
+
+It is even possible to control which entries appear in the image, by using the
+C preprocessor::
+
+    #ifdef CONFIG_HAVE_MRC
+        intel-mrc {
+                offset = <CONFIG_X86_MRC_ADDR>;
+        };
+    #endif
+
+Only boards which enable `HAVE_MRC` will include this entry.
+
+Obviously a similar approach can be used to control which images are produced,
+with a Kconfig option to enable a SPI image, for example. However there is
+generally no harm in producing an image that is not used. If a board uses MMC
+but not SPI, but the SoC supports booting from both, then both images can be
+produced, with only on or other being used by particular boards. This can help
+reduce the need for having multiple defconfig targets for a board where the
+only difference is the boot media, enabling / disabling secure boot, etc.
+
+Of course you can use the device tree itself to pass any board-specific
+information that is needed by U-Boot at runtime (see binman_syms_ for how to
+make binman insert these values directly into executables like SPL).
+
+There is one more way this can be done: with individual .dtsi files for each
+image supported by the SoC. Then the board `.dts` file can include the ones it
+wants. This is not recommended, since it is likely to be difficult to maintain
+and harder to understand the relationship between the different boards.
+
+
+Producing images for multiple boards
+------------------------------------
+
+When invoked within U-Boot, binman only builds a single set of images, for
+the chosen board. This is set by the `CONFIG_DEFAULT_DEVICE_TREE` option.
+
+However, U-Boot generally builds all the device tree files associated with an
+SoC. These are written to the (e.g. for ARM) `arch/arm/dts` directory. Each of
+these contains the full binman description for that board. Often the best
+approach is to build a single image that includes all these device tree binaries
+and allow SPL to select the correct one on boot.
+
+However, it is also possible to build separate images for each board, sinply by
+invoking binman multiple times, once for each device tree file, using a
+different output directory. This will produce one set of images for each board.
+
+
 Example use of binman for x86
 -----------------------------
 
@@ -254,6 +419,7 @@ file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value.
 You can use other, more specific CONFIG options - see 'Automatic .dtsi
 inclusion' below.
 
+.. _binman_syms:
 
 Access to binman entry offsets at run time (symbols)
 ----------------------------------------------------
-- 
2.37.1.559.g78731f0fdb-goog

Re: [SPAM] [PATCH 2/2] binman: Add more documentation about binman usage

[Xavier Drudis Ferran]

El Sun, Aug 07, 2022 at 04:33:26PM -0600, Simon Glass deia:
> This is an attempt to answer the comments provided by Xavier [1].
> 

Thank you. Sorry if I point out silly things too. No agony intended.

>  
> +Note that binman can itself can create a FIT. This helps to move mkimage

one "can" too much

> +invocations out of the Makefile and into binman image descriptions. It also
> +helps by removing the need for ad-hoc tools like `make_fit_atf.py`.
> +
>

Maybe in future tense?
We're not there yet?, because of tee.bin, see Jerome's message.
Or is tee.bin not officialy supported yet in U-Boot?


> +How do you know how to incorporate ATF? It is handled by the atf-bl31 entry type
> +(etype). An etype is an implementation of reading a binary into binman, in this
> +case the `bl31.bin` file. When you build U-Boot but do not set the BL31
> +environment variable, binman provides a help message, which comes from
> +`missing-blob-help`::
> +
> +    See the documentation for your board. You may need to build ARM Trusted
> +    Firmware and build with BL31=/path/to/bl31.bin
> +
> +The mechanism by which binman is advised of this is also in the Makefile. See
> +the `-a atf-bl31-path=${BL31}` piece in `cmd_binman`. This tells binman to
> +set the EntryArg `atf-bl31-path` to the value of the `BL31` environment
> +variable. Within binman, this EntryArg is picked up by the `Entry_atf_bl31`
> +etype. An EntryArg is simply an argument to the entry. The `atf-bl31-path`
> +name is documented in :ref:`etype_atf_bl31`.
> +

Still confused. Shouldn't you mention split-elf ?
The way I use it bl31.elf is not simply copied into an image (atf_bl31.py
is just a Entry_blob_named_by_arg). It is sliced in pieces and put into 
u-boot.itb. Each piece carries a little metadada like the load address,
extracted from the elf by make_fit_atf.py or binman with split-elf. 

The problem is binman cannot incorporate an image it produced as a binary into
another, so we must still use make_fit_atf.py. But then binman does not use
atf-bl31, it simply includes a blob with filename="u-boot.itb".

Maybe it's not the best way to do it and people should just add a atf-bl31 {} 
section in their binman image and it somehow works ? Because that's what
I would assume from your text.

Or maybe you're talking of other boards, but then try not to write it as this
is the method one uses always when one has atf (TF-A)?

Anyway, thank you for writing it. The docs help understand many of the issues
and are a good improvement.

Re: [SPAM] [PATCH 2/2] binman: Add more documentation about binman usage

[Simon Glass]

Hi Xavier,

On Mon, 8 Aug 2022 at 09:48, Xavier Drudis Ferran <xdrudis@tinet.cat> wrote:
>
> El Sun, Aug 07, 2022 at 04:33:26PM -0600, Simon Glass deia:
> > This is an attempt to answer the comments provided by Xavier [1].
> >
>
> Thank you. Sorry if I point out silly things too. No agony intended.
>
> >
> > +Note that binman can itself can create a FIT. This helps to move mkimage
>
> one "can" too much

It looks like Heinrich applied this patch, or at least it seems to be
in mainline now. This 'can' was fixed.

>
> > +invocations out of the Makefile and into binman image descriptions. It also
> > +helps by removing the need for ad-hoc tools like `make_fit_atf.py`.
> > +
> >
>
> Maybe in future tense?
> We're not there yet?, because of tee.bin, see Jerome's message.
> Or is tee.bin not officialy supported yet in U-Boot?

I suppose we are not there yet for some cases. Patches are welcome but
I don't think we need to put this in the future tense.


>
>
> > +How do you know how to incorporate ATF? It is handled by the atf-bl31 entry type
> > +(etype). An etype is an implementation of reading a binary into binman, in this
> > +case the `bl31.bin` file. When you build U-Boot but do not set the BL31
> > +environment variable, binman provides a help message, which comes from
> > +`missing-blob-help`::
> > +
> > +    See the documentation for your board. You may need to build ARM Trusted
> > +    Firmware and build with BL31=/path/to/bl31.bin
> > +
> > +The mechanism by which binman is advised of this is also in the Makefile. See
> > +the `-a atf-bl31-path=${BL31}` piece in `cmd_binman`. This tells binman to
> > +set the EntryArg `atf-bl31-path` to the value of the `BL31` environment
> > +variable. Within binman, this EntryArg is picked up by the `Entry_atf_bl31`
> > +etype. An EntryArg is simply an argument to the entry. The `atf-bl31-path`
> > +name is documented in :ref:`etype_atf_bl31`.
> > +
>
> Still confused. Shouldn't you mention split-elf ?
> The way I use it bl31.elf is not simply copied into an image (atf_bl31.py
> is just a Entry_blob_named_by_arg). It is sliced in pieces and put into
> u-boot.itb. Each piece carries a little metadada like the load address,
> extracted from the elf by make_fit_atf.py or binman with split-elf.
>
> The problem is binman cannot incorporate an image it produced as a binary into
> another, so we must still use make_fit_atf.py. But then binman does not use
> atf-bl31, it simply includes a blob with filename="u-boot.itb".
>
> Maybe it's not the best way to do it and people should just add a atf-bl31 {}
> section in their binman image and it somehow works ? Because that's what
> I would assume from your text.
>
> Or maybe you're talking of other boards, but then try not to write it as this
> is the method one uses always when one has atf (TF-A)?

I was, but I'll send a patch with a try at this also.

>
> Anyway, thank you for writing it. The docs help understand many of the issues
> and are a good improvement.

OK good. Thanks for writing up your questions in such detail.

Regards,
SImon