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)

The benefit of the FIT images is that they can be signed and verifed as described in U-Boot FIT Signature Verification.

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).

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

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):

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

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).