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