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