u-boot/doc/README.distro

11 Linux distributions are faced with supporting a variety of boot mechanisms,
12 environments or bootloaders (PC BIOS, EFI, U-Boot, Barebox, ...). This makes
13 life complicated. Worse, bootloaders such as U-Boot have a configurable set
18 This document defines a common set of U-Boot features that are required for
20 allow distros to install and boot in an out-of-the-box fashion should enable
21 all these features. Linux distros can then create a single set of boot
26 decoupling distro install/boot logic from any knowledge of the bootloader.
28 This model assumes that boards will load boot configuration files from a
32 board-specific installer/boot-configuration support in a distro.
34 To some extent, this model assumes that a board has a separate boot flash
35 that contains U-Boot, and that the user has somehow installed U-Boot to this
38 distro installer logic would be to install a board-specific U-Boot package to
39 the boot partition during installation. This distro-supplied U-Boot can still
40 implement the same features as on any other board, and hence the distro's boot
47 storage devices for a bootable partition, then load the bootloader or boot
48 configuration files from there. A U-Boot board port that enables the features
49 mentioned in this document will search for boot configuration files in the
53 configuration data to indicate which storage device the system should boot
56 Distros simply need to install the boot configuration files (see next
58 the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or
59 any other bootloader) will find those boot files and execute them. This is
64 U-Boot falls back to searching the first valid partition of a disk for boot
69 U-Boot can also search for boot configuration files from a TFTP server.
71 Boot Configuration Files
74 The standard format for boot configuration files is that of extlinux.conf, as
75 handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
82 * Prescribes a separate configuration per boot menu option, whereas U-Boot
83   lumps all options into a single extlinux.conf file. Hence, U-Boot searches
84   for /extlinux/extlinux.conf then /boot/extlinux/extlinux.conf on disk, or
97 menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options.
98 menu title Fedora Boot Options.
107 	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
109 	fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl
110 	initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img
113 	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
115 	fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
116 	initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img
119 	kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
120 	initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
122 	fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
125 Another hand-crafted network boot configuration file is:
130 MENU TITLE TFTP boot options
158 U-Boot Implementation
177 The first of those headers primarily enables a core set of U-Boot features,
180 boot support is also enabled here, which is useful in order to boot distro
184 Finally, a few options that are mostly relevant only when using U-Boot-
185 specific boot.scr scripts are enabled. This enables distros to generate a
186 U-Boot-specific boot.scr script rather than extlinux.conf as the boot
188 CONFIG_DISTRO_DEFAULTS exposes enough parameterization to boot.scr to
189 allow for board-agnostic boot.scr content, this document recommends that
190 distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
191 to work across multiple bootloaders, whereas boot.scr will only work with
192 U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
193 environment variables a generic boot.scr may rely upon.
196 is defined in a way that searches attached disks for boot configuration files,
202 The U-Boot "syslinux" and "pxe boot" commands require a number of environment
204 CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
210   to pass that DTB to Linux, rather than loading a DTB from the boot
213   If specified a DTB to boot the system must be available at the given
258   Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
259   location in RAM where boot.scr will be loaded to prior to execution.
269 Boot Target Configuration
273 that automatically search attached disks for boot configuration files and
275 it supports the correct set of possible boot device types. To provide this
291 Each entry in the macro defines a single boot device (e.g. a specific eMMC
292 device or SD card) or type of boot device (e.g. USB disk). The parameters to
302 Once the user has installed U-Boot, it is expected that the environment will
305 be altered to influence the boot process:
309   The list of boot locations searched.
313   Entries may be removed or re-ordered in this list to affect the boot order.
318   searched for boot configuration files (extlinux.conf, boot.scr).
320   Example: / /boot/
327   The name of U-Boot style boot.scr files that $bootcmd searches for.
329   Example: boot.scr.uimg boot.scr
331   (Typically we expect extlinux.conf to be used, but execution of boot.scr is
344   If you want to disable boot.scr on all disks, set the value to something
349   If you want to prevent USB enumeration by distro boot commands which execute
352   device is not attached to USB, and you wish to increase boot speed by
357   If you want to prevent PCI enumeration by distro boot commands which execute
360   device is not attached to PCI, and you wish to increase boot speed by
363 Interactively booting from a specific device at the u-boot prompt
366 For interactively booting from a user-selected device at the u-boot command
403 Other *boot* variables than the ones defined above are only for internal use
404 of the boot environment and are not guaranteed to exist or work in the same
405 way in future u-boot versions.  In particular the <device type>_boot