From 8a7301b1fabdbe60c50a3ab03b83d2884a23a4ba Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Sat, 14 Jan 2023 20:15:15 +0100 Subject: [PATCH] doc: man-page for source command Provide a man-page for the source command. Signed-off-by: Heinrich Schuchardt Reviewed-by: Sean Anderson --- 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 0000000..61a4505 --- /dev/null +++ b/doc/usage/cmd/source.rst @@ -0,0 +1,193 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2022, Heinrich Schuchardt + +source command +============== + +Synopsis +-------- + +:: + + source [][:[]|#[]] + +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). diff --git a/doc/usage/index.rst b/doc/usage/index.rst index cf3666a..53e4aee 100644 --- a/doc/usage/index.rst +++ b/doc/usage/index.rst @@ -75,6 +75,7 @@ Shell commands cmd/setexpr cmd/size cmd/sound + cmd/source cmd/temperature cmd/tftpput cmd/true -- 2.7.4