Provide a man-page for the source command.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@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@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