aboutsummaryrefslogtreecommitdiff
path: root/doc/usage/cmd/source.rst
blob: 61a4505909667b0c6a545a8326465072bc00abee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
.. 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).