[PATCH 1/1] doc: man-page for source command

[Heinrich Schuchardt]

Provide a man-page for the source command.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
---
 doc/usage/cmd/source.rst | 154 +++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst      |   1 +
 2 files changed, 155 insertions(+)
 create mode 100644 doc/usage/cmd/source.rst

diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst
new file mode 100644
index 0000000000..9622f1d5a8
--- /dev/null
+++ b/doc/usage/cmd/source.rst
@@ -0,0 +1,154 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2022, Heinrich Schuchardt <xypron.glpk at gmx.de>
+
+source command
+==============
+
+Synopsis
+--------
+
+::
+
+    source [<addr>][:[<image>]|#[<config>]]
+
+Description
+-----------
+
+The *source* command is used to execute a script file from memory.
+
+Two formats for script files exist:
+
+* legacy U-Boot image format
+* Flat Image Tree (FIT)
+
+Both formats can be created with the mkimage tool.
+
+addr
+    location of the script file in memory, defaults to CONFIG_SYS_LOAD_ADDR.
+
+image
+    name of an image in a FIT file
+
+config
+    name of a configuration in a FIT file
+
+Examples
+--------
+
+For creating a FIT image an image tree source file (\*.its) is needed. Here is
+an example (source.its).
+
+.. code-block::
+
+    /dts-v1/;
+
+    / {
+        description = "FIT image to test the source command";
+        #address-cells = <1>;
+
+        images {
+            default = "script-1";
+
+            script-1 {
+                data = "echo 1";
+                type = "script";
+                compression = "none";
+            };
+
+            script-2 {
+                data = "echo 2";
+                type = "script";
+                compression = "none";
+            };
+        };
+
+        configurations {
+            default = "conf-2";
+
+            conf-1 {
+                script = "script-1";
+            };
+
+            conf-2 {
+                script = "script-2";
+            };
+        };
+    };
+
+The FIT image file (boot.itb) is created with:
+
+.. code-block:: bash
+
+    mkimage -f source.its boot.itb
+
+In U-Boot the script can be loaded and execute like this
+
+.. code-block::
+
+    => load host 0:1 $loadaddr boot.itb
+    1552 bytes read in 0 ms
+    => source $loadaddr#conf-1
+    ## Executing script at 00000000
+    1
+    => source $loadaddr#conf-2
+    ## Executing script at 00000000
+    2
+    => source $loadaddr:script1
+    ## Executing script at 00000000
+    Can't find 'script1' FIT subimage
+    => source $loadaddr:script-1
+    ## Executing script at 00000000
+    1
+    => source $loadaddr:script-2
+    ## Executing script at 00000000
+    2
+    => source $loadaddr
+    ## Executing script at 00000000
+    2
+    => source
+    ## Executing script at 00000000
+    2
+    =>
+
+A legacy boot script can be created starting with a text file.
+Here is an example file (boot.txt):
+
+.. code-block:: bash
+
+	echo Hello from a script
+	echo -------------------
+
+The boot scripts (boot.scr) is created with:
+
+.. code-block:: bash
+
+    mkimage -T script -n 'Test script' -d boot.txt boot.scr
+
+The script can be execute in U-boot like this:
+
+.. code-block::
+
+    => load host 0:1 $loadaddr boot.scr
+    122 bytes read in 0 ms
+    => source $loadaddr
+    ## Executing script at 00000000
+    Hello from a script
+    -------------------
+    => source
+    ## Executing script at 00000000
+    Hello from a script
+    -------------------
+    =>
+
+Configuration
+-------------
+
+The source command is only available if CONFIG_CMD_SOURCE=y.
+The FIT image file format requires CONFIG_FIT=y.#
+The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y.
+
+Return value
+------------
+
+If the scripts is executed successfully, the return value $? is 0 (true).
+Otherwise it is 1 (false).
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index bbd40a6e18..14457aba69 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -74,6 +74,7 @@ Shell commands
    cmd/setexpr
    cmd/size
    cmd/sound
+   cmd/source
    cmd/temperature
    cmd/tftpput
    cmd/true
-- 
2.37.2