1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright 2022, Heinrich Schuchardt <xypron.glpk@gmx.de>
3
4source command
5==============
6
7Synopsis
8--------
9
10::
11
12    source [<addr>][:[<image>]|#[<config>]]
13
14Description
15-----------
16
17The *source* command is used to execute a script file from memory.
18
19Two formats for script files exist:
20
21* legacy U-Boot image format
22* Flat Image Tree (FIT)
23
24The benefit of the FIT images is that they can be signed and verifed as
25described in :doc:`../fit/signature`.
26
27Both formats can be created with the mkimage tool.
28
29addr
30    location of the script file in memory, defaults to CONFIG_SYS_LOAD_ADDR.
31
32image
33    name of an image in a FIT file
34
35config
36    name of a configuration in a FIT file. A hash sign following white space
37    starts a comment. Hence, if no *addr* is specified, the hash sign has to be
38    escaped with a backslash or the argument must be quoted.
39
40If both *image* and *config* are omitted, the default configuration is used, or
41if no configuration is defined, the default image.
42
43Examples
44--------
45
46FIT image
47'''''''''
48
49For creating a FIT image an image tree source file (\*.its) is needed. Here is
50an example (source.its).
51
52.. code-block::
53
54    /dts-v1/;
55
56    / {
57        description = "FIT image to test the source command";
58        #address-cells = <1>;
59
60        images {
61            default = "script-1";
62
63            script-1 {
64                data = "echo 1";
65                type = "script";
66                compression = "none";
67            };
68
69            script-2 {
70                data = "echo 2";
71                type = "script";
72                compression = "none";
73            };
74        };
75
76        configurations {
77            default = "conf-2";
78
79            conf-1 {
80                script = "script-1";
81            };
82
83            conf-2 {
84                script = "script-2";
85            };
86        };
87    };
88
89The FIT image file (boot.itb) is created with:
90
91.. code-block:: bash
92
93    mkimage -f source.its boot.itb
94
95In U-Boot the script can be loaded and execute like this
96
97.. code-block::
98
99    => load host 0:1 $loadaddr boot.itb
100    1552 bytes read in 0 ms
101    => source $loadaddr#conf-1
102    ## Executing script at 00000000
103    1
104    => source $loadaddr#conf-2
105    ## Executing script at 00000000
106    2
107    => source $loadaddr:script-1
108    ## Executing script at 00000000
109    1
110    => source $loadaddr:script-2
111    ## Executing script at 00000000
112    2
113    => source $loadaddr
114    ## Executing script at 00000000
115    2
116    => source \#conf-1
117    ## Executing script at 00000000
118    1
119    => source '#conf-1'
120    ## Executing script at 00000000
121    1
122    => source ':script-1'
123    ## Executing script at 00000000
124    1
125    => source
126    ## Executing script at 00000000
127    2
128    =>
129
130Instead of specifying command line instructions directly in the *data* property
131of the image tree source file another file can be included. Here is a minimal
132example which encapsulates the file boot.txt:
133
134.. code-block::
135
136    /dts-v1/;
137    / {
138        description = "";
139        images {
140            script {
141                data = /incbin/("./boot.txt");
142                type = "script";
143            };
144        };
145    };
146
147Legacy U-Boot image
148'''''''''''''''''''
149
150A script file using the legacy U-Boot image file format can be created based on
151a text file. Let's use this example text file (boot.txt):
152
153.. code-block:: bash
154
155    echo Hello from a script
156    echo -------------------
157
158The boot scripts (boot.scr) is created with:
159
160.. code-block:: bash
161
162    mkimage -T script -n 'Test script' -d boot.txt boot.scr
163
164The script can be execute in U-boot like this:
165
166.. code-block::
167
168    => load host 0:1 $loadaddr boot.scr
169    122 bytes read in 0 ms
170    => source $loadaddr
171    ## Executing script at 00000000
172    Hello from a script
173    -------------------
174    => source
175    ## Executing script at 00000000
176    Hello from a script
177    -------------------
178    =>
179
180Configuration
181-------------
182
183The source command is only available if CONFIG_CMD_SOURCE=y.
184The FIT image file format requires CONFIG_FIT=y.#
185The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y.
186On hardened systems support for the legacy U-Boot image format should be
187disabled as these images cannot be signed and verified.
188
189Return value
190------------
191
192If the scripts is executed successfully, the return value $? is 0 (true).
193Otherwise it is 1 (false).
194