source [<addr>][:[<image>]|#[<config>]]
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 described in :doc:`../fit/signature`.
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.
For creating a FIT image an image tree source file (*.its) is needed. Here is an example (source.its).
/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:
mkimage -f source.its boot.itb
In U-Boot the script can be loaded and execute like this
=> 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:
/dts-v1/; / { description = ""; images { script { data = /incbin/("./boot.txt"); type = "script"; }; }; };
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):
echo Hello from a script
echo -------------------
The boot scripts (boot.scr) is created with:
mkimage -T script -n 'Test script' -d boot.txt boot.scr
The script can be execute in U-Boot like this:
=> 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 ------------------- =>
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.
If the scripts is executed successfully, the return value $? is 0 (true). Otherwise it is 1 (false).