doc: man-page for source command
Provide a man-page for the source command.
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Reviewed-by: Sean Anderson <seanga2@gmail.com>
diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst
new file mode 100644
index 0000000..61a4505
--- /dev/null
+++ b/doc/usage/cmd/source.rst
@@ -0,0 +1,193 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2022, Heinrich Schuchardt <xypron.glpk@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)
+
+The benefit of the FIT images is that they can be signed and verifed as
+decribed in :download:`signature.txt <../../uImage.FIT/signature.txt>`.
+
+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. A hash sign following white space
+ starts a comment. Hence, if no *addr* is specified, the hash sign has to be
+ escaped with a backslash or the argument must be quoted.
+
+If both *image* and *config* are omitted, the default configuration is used, or
+if no configuration is defined, the default image.
+
+Examples
+--------
+
+FIT image
+'''''''''
+
+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:script-1
+ ## Executing script at 00000000
+ 1
+ => source $loadaddr:script-2
+ ## Executing script at 00000000
+ 2
+ => source $loadaddr
+ ## Executing script at 00000000
+ 2
+ => source \#conf-1
+ ## Executing script at 00000000
+ 1
+ => source '#conf-1'
+ ## Executing script at 00000000
+ 1
+ => source ':script-1'
+ ## Executing script at 00000000
+ 1
+ => source
+ ## Executing script at 00000000
+ 2
+ =>
+
+Instead of specifying command line instructions directly in the *data* property
+of the image tree source file another file can be included. Here is a minimal
+example which encapsulates the file boot.txt:
+
+.. code-block::
+
+ /dts-v1/;
+ / {
+ description = "";
+ images {
+ script {
+ data = /incbin/("./boot.txt");
+ type = "script";
+ };
+ };
+ };
+
+Legacy U-Boot image
+'''''''''''''''''''
+
+A script file using the legacy U-Boot image file format can be created based on
+a text file. Let's use this example text 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.
+On hardened systems support for the legacy U-Boot image format should be
+disabled as these images cannot be signed and verified.
+
+Return value
+------------
+
+If the scripts is executed successfully, the return value $? is 0 (true).
+Otherwise it is 1 (false).