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

[Sean Anderson]

On 1/14/23 06:51, Heinrich Schuchardt wrote:
> 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

We need a note here about how these are optional:

image
     name of an image in a FIT file. May be omitted to pick the default image.

config
     name of a configuration in a FIT file. May be omitted to pick the default
     config. If addr is not specified, the # must be escaped or quoted to prevent
     it from being interpreted as a comment.

And probably a general note about priorities:

- If : is specified, then *source* will choose an image.
- If # is specified, then *source* will choose an image based on a configuration.
- If neither : nor # is specified, then *source* will try to choose the image in the
   default configuration. If no configurations are present, then it will pick the default
   image.

And a note about secure boot:

If you are using verified boot, signing keys are required based on the value of the "required"
property in the key's node in U-Boot's device tree. If the value of this property is "image",
then scripts will always be verified. However, if the value of this node is "conf", then scripts
will only be verified when a # is specified, as this forces the image to be determined based on
a configuration. For more information, refer to doc/uImage.FIT/signature.txt. Additionally, as
is typical, legacy images must be disabled for verified boot, as they do not support signing.

> +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";

We should use /incbin/ here, since that is more typical.

> +                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";
> +            };

And omit the second script/config.

> +        };
> +    };
> +
> +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

$loadaddr can be omitted, as it is the default

--Sean

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