u-boot/doc/README.distro

1 SPDX-License-Identifier: GPL-2.0+
4  * Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.
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
14 of features, and each board chooses to enable a different set of features.
15 Hence, distros typically need to have board-specific knowledge in order to
18 This document defines a common set of U-Boot features that are required for
19 a distro to support the board in a generic fashion. Any board wishing to
20 allow distros to install and boot in an out-of-the-box fashion should enable
23 to install on many boards without the need for board-specific logic.
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
37 to this aspect of the model, the extent of the board-specific support in the
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
41 configuration file generation logic can still be board-agnostic.
44 -----------------------
46 Typical desktop/server PCs search all (or a user-defined subset of) attached
48 configuration files from there. A U-Boot board port that enables the features
52 Thus, distros do not need to manipulate any kind of bootloader-specific
58 the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or
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.
72 ------------------------
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
92 ------------------------------------------------------------
104 default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
106 label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide)
107 	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
108 …append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 d…
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
112 label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
113 	kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
114 …append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 d…
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
118 label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc)
119 	kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
120 	initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
121 	append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8
122 	fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
123 ------------------------------------------------------------
125 Another hand-crafted network boot configuration file is:
127 ------------------------------------------------------------
132 LABEL jetson-tk1-emmc
136 … console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b
138 LABEL venice2-emmc
142 … console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f
148 … console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7
150 LABEL fedora-installer-fk
152         LINUX fedora-installer/vmlinuz
153         INITRD fedora-installer/initrd.img.orig
154         FDTDIR fedora-installer/dtb
156 ------------------------------------------------------------
158 U-Boot Implementation
162 ---------------------------
164 In your board's defconfig, enable the DISTRO_DEFAULTS option by adding
166 from Kconfig itself, for e.g. all boards using a specific SoC then
169 In your board configuration file, include the following:
171 ------------------------------------------------------------
175 ------------------------------------------------------------
177 The first of those headers primarily enables a core set of U-Boot features,
179 raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network
182 media for non-PC targets at present.
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
189 allow for board-agnostic boot.scr content, this document recommends that
192 U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
200 ------------------------------
202 The U-Boot "syslinux" and "pxe boot" commands require a number of environment
203 variables be set. Default values for these variables are often hard-coded into
204 CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
267 MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.
270 -------------------------
279 ------------------------------------------------------------
289 ------------------------------------------------------------
291 Each entry in the macro defines a single boot device (e.g. a specific eMMC
295 - Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE, VIRTIO).
296 - Lower-case disk type (same options as above).
297 - ID of the specific disk (MMC only) or ignored for other types.
302 Once the user has installed U-Boot, it is expected that the environment will
313   Entries may be removed or re-ordered in this list to affect the boot order.
317   For disk-based booting, the list of directories within a partition that are
322   Entries may be removed or re-ordered in this list to affect the set of
327   The name of U-Boot style boot.scr files that $bootcmd searches for.
332   maintained for backwards-compatibility.)
334   Entries may be removed or re-ordered in this list to affect the set of
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
380  - run bootcmd_usb0
383  - run bootcmd_mmc1
386  - run bootcmd_pxe
391 - network targets
395 - storage targets (to which a device number must be appended)
405 way in future u-boot versions.  In particular the <device type>_boot