[PATCH v9 03/14] binman: Update entry docs

[Simon Glass <sjg@chromium.org>]

These have got out of data recently. Regenerate them.

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

(no changes since v7)

Changes in v7:
- Correct an rST formatting error

Changes in v6:
- Add new patch to update entry docs

 tools/binman/entries.rst      | 171 ++++++++++++++++++++++++++++++----
 tools/binman/etype/mkimage.py |  28 +++---
 2 files changed, 169 insertions(+), 30 deletions(-)

diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst
index 3dc32db8a54..b2ce7960d3b 100644
--- a/tools/binman/entries.rst
+++ b/tools/binman/entries.rst
@@ -216,9 +216,9 @@ This is a blob containing a device tree. The contents of the blob are
 obtained from the list of available device-tree files, managed by the
 'state' module.
 
-Additional Properties / Entry arguments:
-    - prepend: Header type to use:
-        length: 32-bit length header
+Additional attributes:
+    prepend: Header used (e.g. 'length')
+
 
 
 .. _etype_blob_ext:
@@ -1178,11 +1178,13 @@ Properties / Entry arguments:
     - multiple-data-files: boolean to tell binman to pass all files as
       datafiles to mkimage instead of creating a temporary file the result
       of datafiles concatenation
+    - filename: filename of output binary generated by mkimage
 
 The data passed to mkimage via the -d flag is collected from subnodes of the
 mkimage node, e.g.::
 
     mkimage {
+        filename = "imximage.bin";
         args = "-n test -T imximage";
 
         u-boot-spl {
@@ -1190,13 +1192,14 @@ mkimage node, e.g.::
     };
 
 This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
-file, which mkimage being called like this::
+file, with mkimage being called like this::
 
     mkimage -d <data_file> -n test -T imximage <output_file>
 
 The output from mkimage then becomes part of the image produced by
-binman. If you need to put mulitple things in the data file, you can use
-a section, or just multiple subnodes like this::
+binman but also is written into `imximage.bin` file. If you need to put
+multiple things in the data file, you can use a section, or just multiple
+subnodes like this::
 
     mkimage {
         args = "-n test -T imximage";
@@ -1208,17 +1211,20 @@ a section, or just multiple subnodes like this::
         };
     };
 
+Note that binman places the contents (here SPL and TPL) into a single file
+and passes that to mkimage using the -d option.
+
 To pass all datafiles untouched to mkimage::
 
     mkimage {
-        args = "-n rk3399 -T rkspi";
-        multiple-data-files;
+            args = "-n rk3399 -T rkspi";
+            multiple-data-files;
 
-        u-boot-tpl {
-        };
+            u-boot-tpl {
+            };
 
-        u-boot-spl {
-        };
+            u-boot-spl {
+            };
     };
 
 This calls mkimage to create a Rockchip RK3399-specific first stage
@@ -1242,17 +1248,17 @@ the 'data-to-imagename' property::
 
     mkimage {
         args = "-T imximage";
-        data-to-imagename';
+        data-to-imagename;
 
         u-boot-spl {
         };
     };
 
 That will pass the data to mkimage both as the data file (with -d) and as
-the image name (with -n).
-
+the image name (with -n). In both cases, a filename is passed as the
+argument, with the actual data being in that file.
 
-If need to pass different data in with -n, then use an imagename subnode::
+If need to pass different data in with -n, then use an `imagename` subnode::
 
     mkimage {
         args = "-T imximage";
@@ -1271,6 +1277,7 @@ This will pass in u-boot-spl as the input data and the .cfgout file as the
 -n data.
 
 
+
 .. _etype_opensbi:
 
 Entry: opensbi: RISC-V OpenSBI fw_dynamic blob
@@ -1478,6 +1485,10 @@ skip-at-start
     be written at offset 4 in the image file, since the first 16 bytes are
     skipped when writing.
 
+filename
+    filename to write the unpadded section contents to within the output
+    directory (None to skip this).
+
 Since a section is also an entry, it inherits all the properies of entries
 too.
 
@@ -2034,6 +2045,134 @@ Entry types that have a part to play in handling microcode:
 
 
 
+.. _etype_u_boot_vpl:
+
+Entry: u-boot-vpl: U-Boot VPL binary
+------------------------------------
+
+Properties / Entry arguments:
+    - filename: Filename of u-boot-vpl.bin (default 'vpl/u-boot-vpl.bin')
+
+This is the U-Boot VPL (Verifying Program Loader) binary. This is a small
+binary which loads before SPL, typically into on-chip SRAM. It is
+responsible for locating, loading and jumping to SPL, the next-stage
+loader. Note that VPL is not relocatable so must be loaded to the correct
+address in SRAM, or written to run from the correct address if direct
+flash execution is possible (e.g. on x86 devices).
+
+SPL can access binman symbols at runtime. See:
+
+    'Access to binman entry offsets at run time (symbols)'
+
+in the binman README for more information.
+
+The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
+binman uses that to look up symbols to write into the VPL binary.
+
+
+
+.. _etype_u_boot_vpl_bss_pad:
+
+Entry: u-boot-vpl-bss-pad: U-Boot VPL binary padded with a BSS region
+---------------------------------------------------------------------
+
+Properties / Entry arguments:
+    None
+
+This holds the padding added after the VPL binary to cover the BSS (Block
+Started by Symbol) region. This region holds the various variables used by
+VPL. It is set to 0 by VPL when it starts up. If you want to append data to
+the VPL image (such as a device tree file), you must pad out the BSS region
+to avoid the data overlapping with U-Boot variables. This entry is useful in
+that case. It automatically pads out the entry size to cover both the code,
+data and BSS.
+
+The contents of this entry will a certain number of zero bytes, determined
+by __bss_size
+
+The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
+binman uses that to look up the BSS address.
+
+
+
+.. _etype_u_boot_vpl_dtb:
+
+Entry: u-boot-vpl-dtb: U-Boot VPL device tree
+---------------------------------------------
+
+Properties / Entry arguments:
+    - filename: Filename of u-boot.dtb (default 'vpl/u-boot-vpl.dtb')
+
+This is the VPL device tree, containing configuration information for
+VPL. VPL needs this to know what devices are present and which drivers
+to activate.
+
+
+
+.. _etype_u_boot_vpl_elf:
+
+Entry: u-boot-vpl-elf: U-Boot VPL ELF image
+-------------------------------------------
+
+Properties / Entry arguments:
+    - filename: Filename of VPL u-boot (default 'vpl/u-boot-vpl')
+
+This is the U-Boot VPL ELF image. It does not include a device tree but can
+be relocated to any address for execution.
+
+
+
+.. _etype_u_boot_vpl_expanded:
+
+Entry: u-boot-vpl-expanded: U-Boot VPL flat binary broken out into its component parts
+--------------------------------------------------------------------------------------
+
+Properties / Entry arguments:
+    - vpl-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-vpl-nodtb
+   u-boot-vpl-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 'vpl-dtb' entryarg. If
+this is non-empty (and not 'n' or '0') then this expanded entry is selected.
+
+
+
+.. _etype_u_boot_vpl_nodtb:
+
+Entry: u-boot-vpl-nodtb: VPL binary without device tree appended
+----------------------------------------------------------------
+
+Properties / Entry arguments:
+    - filename: Filename to include (default 'vpl/u-boot-vpl-nodtb.bin')
+
+This is the U-Boot VPL binary, It does not include a device tree blob at
+the end of it so may not be able to work without it, assuming VPL needs
+a device tree to operate on your platform. You can add a u_boot_vpl_dtb
+entry after this one, or use a u_boot_vpl entry instead, which normally
+expands to a section containing u-boot-vpl-dtb, u-boot-vpl-bss-pad and
+u-boot-vpl-dtb
+
+VPL can access binman symbols at runtime. See:
+
+    'Access to binman entry offsets at run time (symbols)'
+
+in the binman README for more information.
+
+The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
+binman uses that to look up symbols to write into the VPL binary.
+
+
+
 .. _etype_u_boot_with_ucode_ptr:
 
 Entry: u-boot-with-ucode-ptr: U-Boot with embedded microcode pointer
diff --git a/tools/binman/etype/mkimage.py b/tools/binman/etype/mkimage.py
index c2288c48eef..cb264c3cad0 100644
--- a/tools/binman/etype/mkimage.py
+++ b/tools/binman/etype/mkimage.py
@@ -57,24 +57,24 @@ class Entry_mkimage(Entry):
     Note that binman places the contents (here SPL and TPL) into a single file
     and passes that to mkimage using the -d option.
 
-	To pass all datafiles untouched to mkimage::
+    To pass all datafiles untouched to mkimage::
 
-		mkimage {
-			args = "-n rk3399 -T rkspi";
-			multiple-data-files;
+        mkimage {
+                args = "-n rk3399 -T rkspi";
+                multiple-data-files;
 
-			u-boot-tpl {
-			};
+                u-boot-tpl {
+                };
 
-			u-boot-spl {
-			};
-		};
+                u-boot-spl {
+                };
+        };
 
-	This calls mkimage to create a Rockchip RK3399-specific first stage
-	bootloader, made of TPL+SPL. Since this first stage bootloader requires to
-	align the TPL and SPL but also some weird hacks that is handled by mkimage
-	directly, binman is told to not perform the concatenation of datafiles prior
-	to passing the data to mkimage.
+    This calls mkimage to create a Rockchip RK3399-specific first stage
+    bootloader, made of TPL+SPL. Since this first stage bootloader requires to
+    align the TPL and SPL but also some weird hacks that is handled by mkimage
+    directly, binman is told to not perform the concatenation of datafiles prior
+    to passing the data to mkimage.
 
     To use CONFIG options in the arguments, use a string list instead, as in
     this example which also produces four arguments::
-- 
2.39.0.314.g84b9a713c41-goog