On 1/14/23 06:51, Heinrich Schuchardt wrote:
Provide a man-page for the source command.
Signed-off-by: Heinrich Schuchardt <[email protected]>
---
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 <[email protected]>
+
+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
