blob: bc72aa951ef75dd2992ced7fa6109ceb0ee8c25f [file] [log] [blame]
Simon Glass37c51952021-10-14 12:48:10 -06001.. SPDX-License-Identifier: GPL-2.0+
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -07002
3Generic Distro Configuration Concept
4====================================
5
6Linux distributions are faced with supporting a variety of boot mechanisms,
7environments or bootloaders (PC BIOS, EFI, U-Boot, Barebox, ...). This makes
8life complicated. Worse, bootloaders such as U-Boot have a configurable set
9of features, and each board chooses to enable a different set of features.
10Hence, distros typically need to have board-specific knowledge in order to
11set up a bootable system.
12
13This document defines a common set of U-Boot features that are required for
14a distro to support the board in a generic fashion. Any board wishing to
15allow distros to install and boot in an out-of-the-box fashion should enable
16all these features. Linux distros can then create a single set of boot
17support/install logic that targets these features. This will allow distros
18to install on many boards without the need for board-specific logic.
19
20In fact, some of these features can be implemented by any bootloader, thus
21decoupling distro install/boot logic from any knowledge of the bootloader.
22
23This model assumes that boards will load boot configuration files from a
24regular storage mechanism (eMMC, SD card, USB Disk, SATA disk, etc.) with
Masahiro Yamada28fd00b2015-07-07 18:47:17 +090025a standard partitioning scheme (MBR, GPT). Boards that cannot support this
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070026storage model are outside the scope of this document, and may still need
27board-specific installer/boot-configuration support in a distro.
28
29To some extent, this model assumes that a board has a separate boot flash
30that contains U-Boot, and that the user has somehow installed U-Boot to this
31flash before running the distro installer. Even on boards that do not conform
32to this aspect of the model, the extent of the board-specific support in the
33distro installer logic would be to install a board-specific U-Boot package to
Masahiro Yamada28fd00b2015-07-07 18:47:17 +090034the boot partition during installation. This distro-supplied U-Boot can still
35implement the same features as on any other board, and hence the distro's boot
36configuration file generation logic can still be board-agnostic.
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070037
38Locating Bootable Disks
39-----------------------
40
41Typical desktop/server PCs search all (or a user-defined subset of) attached
42storage devices for a bootable partition, then load the bootloader or boot
43configuration files from there. A U-Boot board port that enables the features
44mentioned in this document will search for boot configuration files in the
45same way.
46
47Thus, distros do not need to manipulate any kind of bootloader-specific
48configuration data to indicate which storage device the system should boot
49from.
50
51Distros simply need to install the boot configuration files (see next
52section) in an ext2/3/4 or FAT partition, mark the partition bootable (via
53the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or
54any other bootloader) will find those boot files and execute them. This is
55conceptually identical to creating a grub2 configuration file on a desktop
56PC.
57
Masahiro Yamada28fd00b2015-07-07 18:47:17 +090058Note that in the absence of any partition that is explicitly marked bootable,
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070059U-Boot falls back to searching the first valid partition of a disk for boot
60configuration files. Other bootloaders are recommended to do the same, since
61I believe that partition table bootable flags aren't so commonly used outside
62the realm of x86 PCs.
63
64U-Boot can also search for boot configuration files from a TFTP server.
65
66Boot Configuration Files
67------------------------
68
69The standard format for boot configuration files is that of extlinux.conf, as
70handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
Edoardo Tomelleri35821a22022-09-21 15:26:33 +020071as specified at `Boot Loader Specification`_:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070072
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070073
Edoardo Tomelleri35821a22022-09-21 15:26:33 +020074... with the exceptions that the Boot Loader Specification document:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070075
76* Prescribes a separate configuration per boot menu option, whereas U-Boot
77 lumps all options into a single extlinux.conf file. Hence, U-Boot searches
78 for /extlinux/extlinux.conf then /boot/extlinux/extlinux.conf on disk, or
79 pxelinux.cfg/default over the network.
80
81* Does not document the fdtdir option, which automatically selects the DTB to
82 pass to the kernel.
83
Edoardo Tomelleri35821a22022-09-21 15:26:33 +020084See also doc/README.pxe under 'pxe file format'.
85
Simon Glass37c51952021-10-14 12:48:10 -060086One example extlinux.conf generated by the Fedora installer is::
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070087
Simon Glass37c51952021-10-14 12:48:10 -060088 # extlinux.conf generated by anaconda
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070089
Simon Glass37c51952021-10-14 12:48:10 -060090 ui menu.c32
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070091
Simon Glass37c51952021-10-14 12:48:10 -060092 menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options.
93 menu title Fedora Boot Options.
94 menu hidden
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070095
Simon Glass37c51952021-10-14 12:48:10 -060096 timeout 50
97 #totaltimeout 9000
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070098
Simon Glass37c51952021-10-14 12:48:10 -060099 default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700100
Simon Glass37c51952021-10-14 12:48:10 -0600101 label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide)
102 kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
103 append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
104 fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl
105 initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700106
Simon Glass37c51952021-10-14 12:48:10 -0600107 label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
108 kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
109 append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
110 fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
111 initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700112
Simon Glass37c51952021-10-14 12:48:10 -0600113 label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc)
114 kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
115 initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
116 append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8
117 fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700118
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700119
Edoardo Tomelleri35821a22022-09-21 15:26:33 +0200120One example of hand-crafted extlinux.conf::
121
122 menu title Select kernel
123 timeout 100
124
125 label Arch with uart devicetree overlay
126 kernel /arch/Image.gz
127 initrd /arch/initramfs-linux.img
128 fdt /dtbs/arch/board.dtb
129 fdtoverlays /dtbs/arch/overlay/uart0-gpio0-1.dtbo
130 append console=ttyS0,115200 console=tty1 rw root=UUID=fc0d0284-ca84-4194-bf8a-4b9da8d66908
131
132 label Arch with uart devicetree overlay but with Boot Loader Specification keys
133 kernel /arch/Image.gz
134 initrd /arch/initramfs-linux.img
135 devicetree /dtbs/arch/board.dtb
136 devicetree-overlay /dtbs/arch/overlay/uart0-gpio0-1.dtbo
137 append console=ttyS0,115200 console=tty1 rw root=UUID=fc0d0284-ca84-4194-bf8a-4b9da8d66908
138
Simon Glass37c51952021-10-14 12:48:10 -0600139Another hand-crafted network boot configuration file is::
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700140
Simon Glass37c51952021-10-14 12:48:10 -0600141 TIMEOUT 100
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700142
Simon Glass37c51952021-10-14 12:48:10 -0600143 MENU TITLE TFTP boot options
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700144
Simon Glass37c51952021-10-14 12:48:10 -0600145 LABEL jetson-tk1-emmc
146 MENU LABEL ../zImage root on Jetson TK1 eMMC
147 LINUX ../zImage
148 FDTDIR ../
149 APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700150
Simon Glass37c51952021-10-14 12:48:10 -0600151 LABEL venice2-emmc
152 MENU LABEL ../zImage root on Venice2 eMMC
153 LINUX ../zImage
154 FDTDIR ../
155 APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700156
Simon Glass37c51952021-10-14 12:48:10 -0600157 LABEL sdcard
158 MENU LABEL ../zImage, root on 2GB sdcard
159 LINUX ../zImage
160 FDTDIR ../
161 APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7
162
163 LABEL fedora-installer-fk
164 MENU LABEL Fedora installer w/ Fedora kernel
165 LINUX fedora-installer/vmlinuz
166 INITRD fedora-installer/initrd.img.orig
167 FDTDIR fedora-installer/dtb
168 APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700169
170U-Boot Implementation
171=====================
172
173Enabling the distro options
174---------------------------
175
Hans de Goede9f823612016-06-20 23:16:28 +0200176In your board's defconfig, enable the DISTRO_DEFAULTS option by adding
177a line with "CONFIG_DISTRO_DEFAULTS=y". If you want to enable this
178from Kconfig itself, for e.g. all boards using a specific SoC then
Masahiro Yamada7325f6c2018-04-25 18:47:52 +0900179add a "imply DISTRO_DEFAULTS" to your SoC CONFIG option.
Hans de Goede9f823612016-06-20 23:16:28 +0200180
Simon Glasse7b2ce12022-04-24 23:31:26 -0600181
182TO BE UPDATED:
183
Simon Glass37c51952021-10-14 12:48:10 -0600184In your board configuration file, include the following::
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700185
Simon Glass37c51952021-10-14 12:48:10 -0600186 #ifndef CONFIG_SPL_BUILD
187 #include <config_distro_bootcmd.h>
188 #endif
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700189
190The first of those headers primarily enables a core set of U-Boot features,
191such as support for MBR and GPT partitions, ext* and FAT filesystems, booting
192raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network
193boot support is also enabled here, which is useful in order to boot distro
194installers given that distros do not commonly distribute bootable install
195media for non-PC targets at present.
196
197Finally, a few options that are mostly relevant only when using U-Boot-
198specific boot.scr scripts are enabled. This enables distros to generate a
199U-Boot-specific boot.scr script rather than extlinux.conf as the boot
200configuration file. While doing so is fully supported, and
Adam Fordba8bf942018-02-06 07:49:32 -0600201CONFIG_DISTRO_DEFAULTS exposes enough parameterization to boot.scr to
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700202allow for board-agnostic boot.scr content, this document recommends that
203distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
204to work across multiple bootloaders, whereas boot.scr will only work with
205U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
206environment variables a generic boot.scr may rely upon.
207
208The second of those headers sets up the default environment so that $bootcmd
209is defined in a way that searches attached disks for boot configuration files,
210and executes them if found.
211
212Required Environment Variables
213------------------------------
214
215The U-Boot "syslinux" and "pxe boot" commands require a number of environment
216variables be set. Default values for these variables are often hard-coded into
217CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
218the user doesn't have to configure them.
219
220fdt_addr:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700221 Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes
222 to pass that DTB to Linux, rather than loading a DTB from the boot
223 filesystem. Prohibited for any other system.
224
225 If specified a DTB to boot the system must be available at the given
226 address.
227
228fdt_addr_r:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700229 Mandatory. The location in RAM where the DTB will be loaded or copied to when
230 processing the fdtdir/devicetreedir or fdt/devicetree options in
231 extlinux.conf.
232
233 This is mandatory even when fdt_addr is provided, since extlinux.conf must
234 always be able to provide a DTB which overrides any copy provided by the HW.
235
236 A size of 1MB for the FDT/DTB seems reasonable.
237
Edoardo Tomelleri35821a22022-09-21 15:26:33 +0200238fdtoverlay_addr_r:
239 Mandatory. The location in RAM where DTB overlays will be temporarily
240 stored and then applied in the load order to the fdt blob stored at the
241 address indicated in the fdt_addr_r environment variable.
242
Dennis Gilmore74f89772020-09-11 11:56:59 -0500243fdtfile:
Dennis Gilmore74f89772020-09-11 11:56:59 -0500244 Mandatory. the name of the DTB file for the specific board for instance
245 the espressobin v5 board the value is "marvell/armada-3720-espressobin.dtb"
246 while on a clearfog pro it is "armada-388-clearfog-pro.dtb" in the case of
247 a board providing its firmware based DTB this value can be used to override
248 the DTB with a different DTB. fdtfile will automatically be set for you if
249 it matches the format ${soc}-${board}.dtb which covers most 32 bit use cases.
250 AArch64 generally does not match as the Linux kernel put the dtb files under
Wolfgang Denk0a50b3c2021-09-27 17:42:38 +0200251 SoC vendor directories.
Dennis Gilmore74f89772020-09-11 11:56:59 -0500252
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700253ramdisk_addr_r:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700254 Mandatory. The location in RAM where the initial ramdisk will be loaded to
255 when processing the initrd option in extlinux.conf.
256
Simon Glass37c51952021-10-14 12:48:10 -0600257 It is recommended that this location be highest in RAM out of fdt_addr_r,
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700258 kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size
259 and use any available RAM.
260
261kernel_addr_r:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700262 Mandatory. The location in RAM where the kernel will be loaded to when
263 processing the kernel option in the extlinux.conf.
264
265 The kernel should be located within the first 128M of RAM in order for the
266 kernel CONFIG_AUTO_ZRELADDR option to work, which is likely enabled on any
267 distro kernel. Since the kernel will decompress itself to 0x8000 after the
Masahiro Yamada28fd00b2015-07-07 18:47:17 +0900268 start of RAM, kernel_addr_r should not overlap that area, or the kernel will
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700269 have to copy itself somewhere else first before decompression.
270
271 A size of 16MB for the kernel is likely adequate.
272
Atish Patra414c34e2020-03-05 16:24:23 -0800273kernel_comp_addr_r:
274 Optional. This is only required if user wants to boot Linux from a compressed
Heinrich Schuchardt3af8d1c2021-02-17 08:06:05 +0100275 Image(.gz, .bz2, .lzma, .lzo) using the booti command. It represents the
276 location in RAM where the compressed Image will be decompressed temporarily.
277 Once the decompression is complete, the decompressed data will be moved to
278 kernel_addr_r for booting.
Atish Patra414c34e2020-03-05 16:24:23 -0800279
280kernel_comp_size:
281 Optional. This is only required if user wants to boot Linux from a compressed
282 Image using booti command. It represents the size of the compressed file. The
283 size has to at least the size of loaded image for decompression to succeed.
284
Vagrant Cascadian7101c4c2016-02-08 19:55:31 -0800285pxefile_addr_r:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700286 Mandatory. The location in RAM where extlinux.conf will be loaded to prior
287 to processing.
288
289 A size of 1MB for extlinux.conf is more than adequate.
290
291scriptaddr:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700292 Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
293 location in RAM where boot.scr will be loaded to prior to execution.
294
295 A size of 1MB for extlinux.conf is more than adequate.
296
297For suggestions on memory locations for ARM systems, you must follow the
298guidelines specified in Documentation/arm/Booting in the Linux kernel tree.
299
300For a commented example of setting these values, please see the definition of
301MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.
302
303Boot Target Configuration
304-------------------------
305
Simon Glass37c51952021-10-14 12:48:10 -0600306The `config_distro_bootcmd.h` file defines $bootcmd and many helper command
307variables that automatically search attached disks for boot configuration files
308and execute them. Boards must provide configure <config_distro_bootcmd.h> so
309that it supports the correct set of possible boot device types. To provide this
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700310configuration, simply define macro BOOT_TARGET_DEVICES prior to including
Simon Glass37c51952021-10-14 12:48:10 -0600311<config_distro_bootcmd.h>. For example::
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700312
Simon Glass37c51952021-10-14 12:48:10 -0600313 #ifndef CONFIG_SPL_BUILD
314 #define BOOT_TARGET_DEVICES(func) \
315 func(MMC, mmc, 1) \
316 func(MMC, mmc, 0) \
317 func(USB, usb, 0) \
318 func(PXE, pxe, na) \
319 func(DHCP, dhcp, na)
320 #include <config_distro_bootcmd.h>
321 #endif
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700322
323Each entry in the macro defines a single boot device (e.g. a specific eMMC
324device or SD card) or type of boot device (e.g. USB disk). The parameters to
325the func macro (passed in by the internal implementation of the header) are:
326
Pali Rohár2f5c9ad2022-04-06 11:35:46 +0200327- Upper-case disk type (DHCP, HOST, IDE, MMC, NVME, PXE, SATA, SCSI, UBIFS, USB,
328 VIRTIO).
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700329- Lower-case disk type (same options as above).
330- ID of the specific disk (MMC only) or ignored for other types.
331
332User Configuration
333==================
334
335Once the user has installed U-Boot, it is expected that the environment will
336be reset to the default values in order to enable $bootcmd and friends, as set
337up by <config_distro_bootcmd.h>. After this, various environment variables may
338be altered to influence the boot process:
339
340boot_targets:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700341 The list of boot locations searched.
342
343 Example: mmc0, mmc1, usb, pxe
344
345 Entries may be removed or re-ordered in this list to affect the boot order.
346
347boot_prefixes:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700348 For disk-based booting, the list of directories within a partition that are
349 searched for boot configuration files (extlinux.conf, boot.scr).
350
351 Example: / /boot/
352
353 Entries may be removed or re-ordered in this list to affect the set of
354 directories which are searched.
355
356boot_scripts:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700357 The name of U-Boot style boot.scr files that $bootcmd searches for.
358
359 Example: boot.scr.uimg boot.scr
360
361 (Typically we expect extlinux.conf to be used, but execution of boot.scr is
362 maintained for backwards-compatibility.)
363
364 Entries may be removed or re-ordered in this list to affect the set of
365 filenames which are supported.
366
367scan_dev_for_extlinux:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700368 If you want to disable extlinux.conf on all disks, set the value to something
369 innocuous, e.g. setenv scan_dev_for_extlinux true.
370
371scan_dev_for_scripts:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700372 If you want to disable boot.scr on all disks, set the value to something
373 innocuous, e.g. setenv scan_dev_for_scripts true.
Karsten Merker8c249292015-03-21 14:15:38 +0100374
Stephen Warren3483b752016-01-26 11:10:12 -0700375boot_net_usb_start:
Stephen Warren3483b752016-01-26 11:10:12 -0700376 If you want to prevent USB enumeration by distro boot commands which execute
377 network operations, set the value to something innocuous, e.g. setenv
378 boot_net_usb_start true. This would be useful if you know your Ethernet
379 device is not attached to USB, and you wish to increase boot speed by
380 avoiding unnecessary actions.
Karsten Merker8c249292015-03-21 14:15:38 +0100381
Stephen Warren986691f2016-01-26 11:10:13 -0700382boot_net_pci_enum:
Stephen Warren986691f2016-01-26 11:10:13 -0700383 If you want to prevent PCI enumeration by distro boot commands which execute
384 network operations, set the value to something innocuous, e.g. setenv
385 boot_net_pci_enum true. This would be useful if you know your Ethernet
386 device is not attached to PCI, and you wish to increase boot speed by
387 avoiding unnecessary actions.
388
Karsten Merker8c249292015-03-21 14:15:38 +0100389Interactively booting from a specific device at the u-boot prompt
390=================================================================
391
392For interactively booting from a user-selected device at the u-boot command
393prompt, the environment provides predefined bootcmd_<target> variables for
394every target defined in boot_targets, which can be run be the user.
395
396If the target is a storage device, the format of the target is always
397<device type><device number>, e.g. mmc0. Specifying the device number is
398mandatory for storage devices, even if only support for a single instance
399of the storage device is actually implemented.
400
401For network targets (dhcp, pxe), only the device type gets specified;
402they do not have a device number.
403
404Examples:
405
406 - run bootcmd_usb0
407 boots from the first USB mass storage device
408
409 - run bootcmd_mmc1
410 boots from the second MMC device
411
412 - run bootcmd_pxe
413 boots by tftp using a pxelinux.cfg
414
415The list of possible targets consists of:
416
417- network targets
Simon Glass37c51952021-10-14 12:48:10 -0600418
Karsten Merker8c249292015-03-21 14:15:38 +0100419 * dhcp
420 * pxe
421
422- storage targets (to which a device number must be appended)
Simon Glass37c51952021-10-14 12:48:10 -0600423
Karsten Merker8c249292015-03-21 14:15:38 +0100424 * mmc
425 * sata
426 * scsi
427 * ide
428 * usb
Lukas Auera8da9ff2018-11-22 11:26:33 +0100429 * virtio
Karsten Merker8c249292015-03-21 14:15:38 +0100430
431Other *boot* variables than the ones defined above are only for internal use
432of the boot environment and are not guaranteed to exist or work in the same
433way in future u-boot versions. In particular the <device type>_boot
434variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
435detail and must not be used as a public interface.
Simon Glass37c51952021-10-14 12:48:10 -0600436
Edoardo Tomelleri35821a22022-09-21 15:26:33 +0200437.. _`Boot Loader Specification`: https://systemd.io/BOOT_LOADER_SPECIFICATION/
Simon Glass37c51952021-10-14 12:48:10 -0600438
439.. sectionauthor:: (C) Copyright 2014 Red Hat Inc.
440.. sectionauthor:: Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved.
441.. sectionauthor:: Copyright (C) 2015 K. Merker <merker@debian.org>