1.. SPDX-License-Identifier: GPL-2.0+
2
3bootm command
4=============
5
6Synopsis
7--------
8
9::
10
11    bootm [fit_addr]#<conf>[#extra-conf]
12    bootm [[fit_addr]:<os_subimg>] [[<fit_addr2>]:<rd_subimg2>] [[<fit_addr3>]:<fdt_subimg>]
13
14    bootm <addr1> [[<addr2> [<addr3>]]    # Legacy boot
15
16Description
17-----------
18
19The *bootm* command is used to boot an Operating System. It has a large number
20of options depending on what needs to be booted.
21
22Note that the second form supports the first and/or second arguments to be
23omitted by using a hyphen '-' instead.
24
25fit_addr / fit_addr2 / fit_addr3
26    address of FIT to boot, defaults to CONFIG_SYS_LOAD_ADDR. See notes below.
27
28conf
29    configuration unit to boot (must be preceded by hash '#')
30
31extra-conf
32    extra configuration to boot. This is supported only for additional
33    devicetree overlays to apply on the base device tree supplied by the first
34    configuration unit.
35
36os_subimg
37    OS sub-image to boot (must be preceded by colon ':')
38
39rd_subimg
40    ramdisk sub-image to boot. Use a hyphen '-' if there is no ramdisk but an
41    FDT is needed.
42
43fdt_subimg
44    FDT sub-image to boot
45
46See below for legacy boot. Booting using :doc:`../fit/index` is recommended.
47
48Note on current image address
49-----------------------------
50
51When bootm is called without arguments, the image at current image address is
52booted. The current image address is the address set most recently by a load
53command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example,
54consider the following commands::
55
56    tftp 200000 /tftpboot/kernel
57    bootm
58    # Last command is equivalent to:
59    # bootm 200000
60
61As shown above, with FIT the address portion of any argument
62can be omitted. If <addr3> is omitted, then it is assumed that image at
63<addr2> should be used. Similarly, when <addr2> is omitted, it is assumed that
64image at <addr1> should be used. If <addr1> is omitted, it is assumed that the
65current image address is to be used. For example, consider the following
66commands::
67
68    tftp 200000 /tftpboot/uImage
69    bootm :kernel-1
70    # Last command is equivalent to:
71    # bootm 200000:kernel-1
72
73    tftp 200000 /tftpboot/uImage
74    bootm 400000:kernel-1 :ramdisk-1
75    # Last command is equivalent to:
76    # bootm 400000:kernel-1 400000:ramdisk-1
77
78    tftp 200000 /tftpboot/uImage
79    bootm :kernel-1 400000:ramdisk-1 :fdt-1
80    # Last command is equivalent to:
81    # bootm 200000:kernel-1 400000:ramdisk-1 400000:fdt-1
82
83
84Legacy boot
85-----------
86
87U-Boot supports a legacy image format, enabled by `CONFIG_LEGACY_IMAGE_FORMAT`.
88This is not recommended as it is quite limited and insecure. Use
89:doc:`../fit/index` instead. It is documented here for old boards which still
90use it.
91
92Arguments are:
93
94addr1
95    address of legacy image to boot. If the image includes a second component
96    (ramdisk) it is used as well, unless the second parameter is hyphen '-'.
97
98addr2
99    address of legacy image to use as ramdisk
100
101addr3
102    address of legacy image to use as FDT
103
104
105Example syntax
106--------------
107
108This section provides various examples of possible usage::
109
110    1.  bootm       /* boot image at the current address, equivalent to 2,3,8 */
111
112This is equivalent to cases 2, 3 or 8, depending on the type of image at
113the current image address.
114
115Boot method: see cases 2,3,8
116
117Legacy uImage syntax
118~~~~~~~~~~~~~~~~~~~~
119
120::
121
122    2.  bootm <addr1>            /* single image at <addr1> */
123
124Boot kernel image located at <addr1>.
125
126Boot method: non-FDT
127
128::
129
130    3.  bootm <addr1>            /* multi-image at <addr1>  */
131
132First and second components of the image at <addr1> are assumed to be a
133kernel and a ramdisk, respectively. The kernel is booted with initrd loaded
134with the ramdisk from the image.
135
136Boot method: depends on the number of components at <addr1>, and on whether
137U-Boot is compiled with OF support, which it should be.
138
139    ==================== ======================== ========================
140    Configuration        2 components             3 components
141                         (kernel, initrd)         (kernel, initrd, fdt)
142    ==================== ======================== ========================
143    #ifdef CONFIG_OF_*                   non-FDT                     FDT
144    #ifndef CONFIG_OF_*                  non-FDT                 non-FDT
145    ==================== ======================== ========================
146
147::
148
149    4.  bootm <addr1> -            /* multi-image at <addr1>  */
150
151Similar to case 3, but the kernel is booted without initrd.  Second
152component of the multi-image is irrelevant (it can be a dummy, 1-byte file).
153
154Boot method: see case 3
155
156::
157
158    5.  bootm <addr1> <addr2>        /* single image at <addr1> */
159
160Boot kernel image located at <addr1> with initrd loaded with ramdisk
161from the image at <addr2>.
162
163Boot method: non-FDT
164
165::
166
167    6.  bootm <addr1> <addr2> <addr3>   /* single image at <addr1> */
168
169<addr1> is the address of a kernel image, <addr2> is the address of a
170ramdisk image, and <addr3> is the address of a FDT binary blob.  Kernel is
171booted with initrd loaded with ramdisk from the image at <addr2>.
172
173Boot method: FDT
174
175::
176
177    7.  bootm <addr1> -      <addr3>   /* single image at <addr1> */
178
179<addr1> is the address of a kernel image and <addr3> is the address of
180a FDT binary blob. Kernel is booted without initrd.
181
182Boot method: FDT
183
184FIT syntax
185~~~~~~~~~~
186
187::
188
189    8.  bootm <addr1>
190
191Image at <addr1> is assumed to contain a default configuration, which
192is booted.
193
194Boot method: FDT or non-FDT, depending on whether the default configuration
195defines FDT
196
197::
198
199    9.  bootm [<addr1>]:<subimg1>
200
201Similar to case 2: boot kernel stored in <subimg1> from the image at
202address <addr1>.
203
204Boot method: non-FDT
205
206::
207
208    10. bootm [<addr1>]#<conf>[#<extra-conf[#...]]
209
210Boot configuration <conf> from the image at <addr1>.
211
212Boot method: FDT or non-FDT, depending on whether the configuration given
213defines FDT
214
215::
216
217    11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
218
219Equivalent to case 5: boot kernel stored in <subimg1> from the image
220at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
221<addr2>.
222
223Boot method: non-FDT
224
225::
226
227    12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
228
229Equivalent to case 6: boot kernel stored in <subimg1> from the image
230at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
231<addr2>, and pass FDT blob <subimg3> from the image at <addr3>.
232
233Boot method: FDT
234
235::
236
237    13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
238
239Similar to case 12, the difference being that <addr3> is the address
240of FDT binary blob that is to be passed to the kernel.
241
242Boot method: FDT
243
244::
245
246    14. bootm [<addr1>]:<subimg1> -              [<addr3>]:<subimg3>
247
248Equivalent to case 7: boot kernel stored in <subimg1> from the image
249at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at
250<addr3>.
251
252Boot method: FDT
253
254    15. bootm [<addr1>]:<subimg1> -              <addr3>
255
256Similar to case 14, the difference being that <addr3> is the address
257of the FDT binary blob that is to be passed to the kernel.
258
259Boot method: FDT
260
261
262
263Example
264-------
265
266boot kernel "kernel-1" stored in a new uImage located at 200000::
267
268    bootm 200000:kernel-1
269
270boot configuration "cfg-1" from a new uImage located at 200000::
271
272    bootm 200000#cfg-1
273
274boot configuration "cfg-1" with extra "cfg-2" from a new uImage located
275at 200000::
276
277    bootm 200000#cfg-1#cfg-2
278
279boot "kernel-1" from a new uImage at 200000 with initrd "ramdisk-2" found in
280some other new uImage stored at address 800000::
281
282    bootm 200000:kernel-1 800000:ramdisk-2
283
284boot "kernel-2" from a new uImage at 200000, with initrd "ramdisk-1" and FDT
285"fdt-1", both stored in some other new uImage located at 800000::
286
287    bootm 200000:kernel-1 800000:ramdisk-1 800000:fdt-1
288
289boot kernel "kernel-2" with initrd "ramdisk-2", both stored in a new uImage
290at address 200000, with a raw FDT blob stored at address 600000::
291
292    bootm 200000:kernel-2 200000:ramdisk-2 600000
293
294boot kernel "kernel-2" from new uImage at 200000 with FDT "fdt-1" from the
295same new uImage::
296
297    bootm 200000:kernel-2 - 200000:fdt-1
298
299.. sectionauthor:: Bartlomiej Sieka <tur@semihalf.com>
300.. sectionauthor:: Simon Glass <sjg@chromium.org>
301