u-boot/doc/README.distro

12 Linux distributions are faced with supporting a variety of boot mechanisms,
13 environments or bootloaders (PC BIOS, EFI, U-Boot, Barebox, ...). This makes
14 life complicated. Worse, bootloaders such as U-Boot have a configurable set
19 This document defines a common set of U-Boot features that are required for
21 allow distros to install and boot in an out-of-the-box fashion should enable
22 all these features. Linux distros can then create a single set of boot
27 decoupling distro install/boot logic from any knowledge of the bootloader.
29 This model assumes that boards will load boot configuration files from a
33 board-specific installer/boot-configuration support in a distro.
35 To some extent, this model assumes that a board has a separate boot flash
36 that contains U-Boot, and that the user has somehow installed U-Boot to this
39 distro installer logic would be to install a board-specific U-Boot package to
40 the boot partition during installation. This distro-supplied U-Boot can still
41 implement the same features as on any other board, and hence the distro's boot
48 storage devices for a bootable partition, then load the bootloader or boot
49 configuration files from there. A U-Boot board port that enables the features
50 mentioned in this document will search for boot configuration files in the
54 configuration data to indicate which storage device the system should boot
57 Distros simply need to install the boot configuration files (see next
59 the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or
60 any other bootloader) will find those boot files and execute them. This is
65 U-Boot falls back to searching the first valid partition of a disk for boot
70 U-Boot can also search for boot configuration files from a TFTP server.
72 Boot Configuration Files
75 The standard format for boot configuration files is that of extlinux.conf, as
76 handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
83 * Prescribes a separate configuration per boot menu option, whereas U-Boot
84   lumps all options into a single extlinux.conf file. Hence, U-Boot searches
85   for /extlinux/extlinux.conf then /boot/extlinux/extlinux.conf on disk, or
98 menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options.
99 menu title Fedora Boot Options.
108 	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
110 	fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl
111 	initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img
114 	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
116 	fdtdir /boot/dtb-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
117 	initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img
120 	kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
121 	initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
123 	fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
126 Another hand-crafted network boot configuration file is:
131 MENU TITLE TFTP boot options
159 U-Boot Implementation
169 the Kconfig file in the root of the u-boot sources.
180 The first of those headers primarily enables a core set of U-Boot features,
183 boot support is also enabled here, which is useful in order to boot distro
187 Finally, a few options that are mostly relevant only when using U-Boot-
188 specific boot.scr scripts are enabled. This enables distros to generate a
189 U-Boot-specific boot.scr script rather than extlinux.conf as the boot
191 <config_distro_defaults.h> exposes enough parameterization to boot.scr to
192 allow for board-agnostic boot.scr content, this document recommends that
193 distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
194 to work across multiple bootloaders, whereas boot.scr will only work with
195 U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
196 environment variables a generic boot.scr may rely upon.
199 is defined in a way that searches attached disks for boot configuration files,
205 The U-Boot "syslinux" and "pxe boot" commands require a number of environment
207 CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
213   to pass that DTB to Linux, rather than loading a DTB from the boot
216   If specified a DTB to boot the system must be available at the given
261   Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
262   location in RAM where boot.scr will be loaded to prior to execution.
272 Boot Target Configuration
276 that automatically search attached disks for boot configuration files and
278 it supports the correct set of possible boot device types. To provide this
294 Each entry in the macro defines a single boot device (e.g. a specific eMMC
295 device or SD card) or type of boot device (e.g. USB disk). The parameters to
305 Once the user has installed U-Boot, it is expected that the environment will
308 be altered to influence the boot process:
312   The list of boot locations searched.
316   Entries may be removed or re-ordered in this list to affect the boot order.
321   searched for boot configuration files (extlinux.conf, boot.scr).
323   Example: / /boot/
330   The name of U-Boot style boot.scr files that $bootcmd searches for.
332   Example: boot.scr.uimg boot.scr
334   (Typically we expect extlinux.conf to be used, but execution of boot.scr is
347   If you want to disable boot.scr on all disks, set the value to something
352   If you want to prevent USB enumeration by distro boot commands which execute
355   device is not attached to USB, and you wish to increase boot speed by
360   If you want to prevent PCI enumeration by distro boot commands which execute
363   device is not attached to PCI, and you wish to increase boot speed by
366 Interactively booting from a specific device at the u-boot prompt
369 For interactively booting from a user-selected device at the u-boot command
405 Other *boot* variables than the ones defined above are only for internal use
406 of the boot environment and are not guaranteed to exist or work in the same
407 way in future u-boot versions.  In particular the <device type>_boot