194 lines
4.3 KiB
ReStructuredText
194 lines
4.3 KiB
ReStructuredText
.. 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)
|
|
|
|
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).
|