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

[Sean Anderson]

On 1/14/23 14:15, Heinrich Schuchardt wrote:
> Provide a man-page for the source command.
> 
> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> ---
> v2:
> 	describe defaults for arguments
> 	mention signing and verifying FIT images
> 	link to uImage.FIT/signature.txt
> 	add an example with incbin
> 	describe escaping hash sign
> 	provide examples without script address
> ---
>   doc/usage/cmd/source.rst | 193 +++++++++++++++++++++++++++++++++++++++
>   doc/usage/index.rst      |   1 +
>   2 files changed, 194 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..61a4505909
> --- /dev/null
> +++ b/doc/usage/cmd/source.rst
> @@ -0,0 +1,193 @@
> +.. 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)
> +
> +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.

Although I would like to see mentioned that # and : can be used without image and
config (which is quite useful when you e.g. only have one config).

> +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).
> 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

Reviewed-by: Sean Anderson <seanga2 at gmail.com>