From e9b5e31a12b9a459ca4c35161851674aba84f9af Mon Sep 17 00:00:00 2001
From: Simon Glass <sjg@chromium.org>
Date: Sat, 13 Aug 2022 11:40:47 -0600
Subject: [PATCH] binman: Improve mkimage documentation

Expand this a little to make things clearer. Also drop the invalid
entry arg.

Series-changes 2
- Make it clear that -d data is concatenated/collected by binman
- Fix mulitple typoe
- Reword a sentence for grammar

Signed-off-by: Simon Glass <sjg@chromium.org>
---
 tools/binman/entries.rst      | 28 +++++++++++++++++++++-------
 tools/binman/etype/mkimage.py | 31 ++++++++++++++++++++++++-------
 2 files changed, 45 insertions(+), 14 deletions(-)

diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst
index 283751e393..fc15c45d29 100644
--- a/tools/binman/entries.rst
+++ b/tools/binman/entries.rst
@@ -1166,11 +1166,10 @@ Entry: mkimage: Binary produced by mkimage
 ------------------------------------------
 
 Properties / Entry arguments:
-    - datafile: Filename for -d argument
-    - args: Other arguments to pass
+    - args: Arguments to pass
 
-The data passed to mkimage is collected from subnodes of the mkimage node,
-e.g.::
+The data passed to mkimage via the -d flag is collected from subnodes of the
+mkimage node, e.g.::
 
     mkimage {
         args = "-n test -T imximage";
@@ -1179,9 +1178,24 @@ e.g.::
         };
     };
 
-This calls mkimage to create an imximage with u-boot-spl.bin as the input
-file. The output from mkimage then becomes part of the image produced by
-binman.
+This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
+file, which 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::
+
+    mkimage {
+        args = "-n test -T imximage";
+
+        u-boot-spl {
+        };
+
+        u-boot-tpl {
+        };
+    };
 
 To use CONFIG options in the arguments, use a string list instead, as in
 this example which also produces four arguments::
diff --git a/tools/binman/etype/mkimage.py b/tools/binman/etype/mkimage.py
index f3b3df6fe0..a5d94da6a9 100644
--- a/tools/binman/etype/mkimage.py
+++ b/tools/binman/etype/mkimage.py
@@ -15,11 +15,10 @@ class Entry_mkimage(Entry):
     """Binary produced by mkimage
 
     Properties / Entry arguments:
-        - datafile: Filename for -d argument
-        - args: Other arguments to pass
+        - args: Arguments to pass
 
-    The data passed to mkimage is collected from subnodes of the mkimage node,
-    e.g.::
+    The data passed to mkimage via the -d flag is collected from subnodes of the
+    mkimage node, e.g.::
 
         mkimage {
             args = "-n test -T imximage";
@@ -28,9 +27,27 @@ class Entry_mkimage(Entry):
             };
         };
 
-    This calls mkimage to create an imximage with u-boot-spl.bin as the input
-    file. The output from mkimage then becomes part of the image produced by
-    binman.
+    This calls mkimage to create an imximage with `u-boot-spl.bin` as the data
+    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 multiple things in the data file, you can use
+    a section, or just multiple subnodes like this::
+
+        mkimage {
+            args = "-n test -T imximage";
+
+            u-boot-spl {
+            };
+
+            u-boot-tpl {
+            };
+        };
+
+    Note that binman places the contents (here SPL and TPL) into a single file
+    and passes that to mkimage using the -d option.
 
     To use CONFIG options in the arguments, use a string list instead, as in
     this example which also produces four arguments::
-- 
2.39.5