blob: 2af559009bb58c4a9848587c79cafeedcb453e23 [file] [log] [blame]
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -07001/*
2 * (C) Copyright 2014 Red Hat Inc.
3 * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved.
Karsten Merker8c249292015-03-21 14:15:38 +01004 * Copyright (C) 2015 K. Merker <merker@debian.org>
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -07005 *
6 * SPDX-License-Identifier: GPL-2.0+
7 */
8
9Generic Distro Configuration Concept
10====================================
11
12Linux distributions are faced with supporting a variety of boot mechanisms,
13environments or bootloaders (PC BIOS, EFI, U-Boot, Barebox, ...). This makes
14life complicated. Worse, bootloaders such as U-Boot have a configurable set
15of features, and each board chooses to enable a different set of features.
16Hence, distros typically need to have board-specific knowledge in order to
17set up a bootable system.
18
19This document defines a common set of U-Boot features that are required for
20a distro to support the board in a generic fashion. Any board wishing to
21allow distros to install and boot in an out-of-the-box fashion should enable
22all these features. Linux distros can then create a single set of boot
23support/install logic that targets these features. This will allow distros
24to install on many boards without the need for board-specific logic.
25
26In fact, some of these features can be implemented by any bootloader, thus
27decoupling distro install/boot logic from any knowledge of the bootloader.
28
29This model assumes that boards will load boot configuration files from a
30regular storage mechanism (eMMC, SD card, USB Disk, SATA disk, etc.) with
Masahiro Yamada28fd00b2015-07-07 18:47:17 +090031a standard partitioning scheme (MBR, GPT). Boards that cannot support this
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070032storage model are outside the scope of this document, and may still need
33board-specific installer/boot-configuration support in a distro.
34
35To some extent, this model assumes that a board has a separate boot flash
36that contains U-Boot, and that the user has somehow installed U-Boot to this
37flash before running the distro installer. Even on boards that do not conform
38to this aspect of the model, the extent of the board-specific support in the
39distro installer logic would be to install a board-specific U-Boot package to
Masahiro Yamada28fd00b2015-07-07 18:47:17 +090040the boot partition during installation. This distro-supplied U-Boot can still
41implement the same features as on any other board, and hence the distro's boot
42configuration file generation logic can still be board-agnostic.
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070043
44Locating Bootable Disks
45-----------------------
46
47Typical desktop/server PCs search all (or a user-defined subset of) attached
48storage devices for a bootable partition, then load the bootloader or boot
49configuration files from there. A U-Boot board port that enables the features
50mentioned in this document will search for boot configuration files in the
51same way.
52
53Thus, distros do not need to manipulate any kind of bootloader-specific
54configuration data to indicate which storage device the system should boot
55from.
56
57Distros simply need to install the boot configuration files (see next
58section) in an ext2/3/4 or FAT partition, mark the partition bootable (via
59the MBR bootable flag, or GPT legacy_bios_bootable attribute), and U-Boot (or
60any other bootloader) will find those boot files and execute them. This is
61conceptually identical to creating a grub2 configuration file on a desktop
62PC.
63
Masahiro Yamada28fd00b2015-07-07 18:47:17 +090064Note that in the absence of any partition that is explicitly marked bootable,
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -070065U-Boot falls back to searching the first valid partition of a disk for boot
66configuration files. Other bootloaders are recommended to do the same, since
67I believe that partition table bootable flags aren't so commonly used outside
68the realm of x86 PCs.
69
70U-Boot can also search for boot configuration files from a TFTP server.
71
72Boot Configuration Files
73------------------------
74
75The standard format for boot configuration files is that of extlinux.conf, as
76handled by U-Boot's "syslinux" (disk) or "pxe boot" (network). This is roughly
77as specified at:
78
79http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
80
81... with the exceptions that the BootLoaderSpec document:
82
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
86 pxelinux.cfg/default over the network.
87
88* Does not document the fdtdir option, which automatically selects the DTB to
89 pass to the kernel.
90
91One example extlinux.conf generated by the Fedora installer is:
92
93------------------------------------------------------------
94# extlinux.conf generated by anaconda
95
96ui menu.c32
97
98menu autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options.
99menu title Fedora Boot Options.
100menu hidden
101
102timeout 50
103#totaltimeout 9000
104
105default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
106
107label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl) 22 (Rawhide)
108 kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl
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
111 initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl.img
112
113label Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
114 kernel /boot/vmlinuz-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae
115 append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 LANG=en_US.UTF-8 drm.debug=0xf
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
118
119label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc)
120 kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
121 initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
122 append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8
123 fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
124------------------------------------------------------------
125
126Another hand-crafted network boot configuration file is:
127
128------------------------------------------------------------
129TIMEOUT 100
130
131MENU TITLE TFTP boot options
132
133LABEL jetson-tk1-emmc
134 MENU LABEL ../zImage root on Jetson TK1 eMMC
135 LINUX ../zImage
136 FDTDIR ../
137 APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b
138
139LABEL venice2-emmc
140 MENU LABEL ../zImage root on Venice2 eMMC
141 LINUX ../zImage
142 FDTDIR ../
143 APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f
144
145LABEL sdcard
146 MENU LABEL ../zImage, root on 2GB sdcard
147 LINUX ../zImage
148 FDTDIR ../
149 APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7
150
151LABEL fedora-installer-fk
152 MENU LABEL Fedora installer w/ Fedora kernel
153 LINUX fedora-installer/vmlinuz
154 INITRD fedora-installer/initrd.img.orig
155 FDTDIR fedora-installer/dtb
156 APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M
157------------------------------------------------------------
158
159U-Boot Implementation
160=====================
161
162Enabling the distro options
163---------------------------
164
Hans de Goede9f823612016-06-20 23:16:28 +0200165In your board's defconfig, enable the DISTRO_DEFAULTS option by adding
166a line with "CONFIG_DISTRO_DEFAULTS=y". If you want to enable this
167from Kconfig itself, for e.g. all boards using a specific SoC then
168add a "default y if ARCH_FOO" to the DISTRO_DEFAULTS section of
169the Kconfig file in the root of the u-boot sources.
170
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700171In your board configuration file, include the following:
172
173------------------------------------------------------------
174#ifndef CONFIG_SPL_BUILD
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700175#include <config_distro_bootcmd.h>
176#endif
177------------------------------------------------------------
178
179The first of those headers primarily enables a core set of U-Boot features,
180such as support for MBR and GPT partitions, ext* and FAT filesystems, booting
181raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network
182boot support is also enabled here, which is useful in order to boot distro
183installers given that distros do not commonly distribute bootable install
184media for non-PC targets at present.
185
186Finally, a few options that are mostly relevant only when using U-Boot-
187specific boot.scr scripts are enabled. This enables distros to generate a
188U-Boot-specific boot.scr script rather than extlinux.conf as the boot
189configuration file. While doing so is fully supported, and
Adam Fordba8bf942018-02-06 07:49:32 -0600190CONFIG_DISTRO_DEFAULTS exposes enough parameterization to boot.scr to
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700191allow for board-agnostic boot.scr content, this document recommends that
192distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
193to work across multiple bootloaders, whereas boot.scr will only work with
194U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
195environment variables a generic boot.scr may rely upon.
196
197The second of those headers sets up the default environment so that $bootcmd
198is defined in a way that searches attached disks for boot configuration files,
199and executes them if found.
200
201Required Environment Variables
202------------------------------
203
204The U-Boot "syslinux" and "pxe boot" commands require a number of environment
205variables be set. Default values for these variables are often hard-coded into
206CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
207the user doesn't have to configure them.
208
209fdt_addr:
210
211 Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes
212 to pass that DTB to Linux, rather than loading a DTB from the boot
213 filesystem. Prohibited for any other system.
214
215 If specified a DTB to boot the system must be available at the given
216 address.
217
218fdt_addr_r:
219
220 Mandatory. The location in RAM where the DTB will be loaded or copied to when
221 processing the fdtdir/devicetreedir or fdt/devicetree options in
222 extlinux.conf.
223
224 This is mandatory even when fdt_addr is provided, since extlinux.conf must
225 always be able to provide a DTB which overrides any copy provided by the HW.
226
227 A size of 1MB for the FDT/DTB seems reasonable.
228
229ramdisk_addr_r:
230
231 Mandatory. The location in RAM where the initial ramdisk will be loaded to
232 when processing the initrd option in extlinux.conf.
233
234 It is recommended that this location be highest in RAM out of fdt_addr_,
235 kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size
236 and use any available RAM.
237
238kernel_addr_r:
239
240 Mandatory. The location in RAM where the kernel will be loaded to when
241 processing the kernel option in the extlinux.conf.
242
243 The kernel should be located within the first 128M of RAM in order for the
244 kernel CONFIG_AUTO_ZRELADDR option to work, which is likely enabled on any
245 distro kernel. Since the kernel will decompress itself to 0x8000 after the
Masahiro Yamada28fd00b2015-07-07 18:47:17 +0900246 start of RAM, kernel_addr_r should not overlap that area, or the kernel will
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700247 have to copy itself somewhere else first before decompression.
248
249 A size of 16MB for the kernel is likely adequate.
250
Vagrant Cascadian7101c4c2016-02-08 19:55:31 -0800251pxefile_addr_r:
Dennis Gilmoreffb4f6f2015-01-22 11:34:20 -0700252
253 Mandatory. The location in RAM where extlinux.conf will be loaded to prior
254 to processing.
255
256 A size of 1MB for extlinux.conf is more than adequate.
257
258scriptaddr:
259
260 Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
261 location in RAM where boot.scr will be loaded to prior to execution.
262
263 A size of 1MB for extlinux.conf is more than adequate.
264
265For suggestions on memory locations for ARM systems, you must follow the
266guidelines specified in Documentation/arm/Booting in the Linux kernel tree.
267
268For a commented example of setting these values, please see the definition of
269MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.
270
271Boot Target Configuration
272-------------------------
273
274<config_distro_bootcmd.h> defines $bootcmd and many helper command variables
275that automatically search attached disks for boot configuration files and
276execute them. Boards must provide configure <config_distro_bootcmd.h> so that
277it supports the correct set of possible boot device types. To provide this
278configuration, simply define macro BOOT_TARGET_DEVICES prior to including
279<config_distro_bootcmd.h>. For example:
280
281------------------------------------------------------------
282#ifndef CONFIG_SPL_BUILD
283#define BOOT_TARGET_DEVICES(func) \
284 func(MMC, mmc, 1) \
285 func(MMC, mmc, 0) \
286 func(USB, usb, 0) \
287 func(PXE, pxe, na) \
288 func(DHCP, dhcp, na)
289#include <config_distro_bootcmd.h>
290#endif
291------------------------------------------------------------
292
293Each entry in the macro defines a single boot device (e.g. a specific eMMC
294device or SD card) or type of boot device (e.g. USB disk). The parameters to
295the func macro (passed in by the internal implementation of the header) are:
296
297- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE).
298- Lower-case disk type (same options as above).
299- ID of the specific disk (MMC only) or ignored for other types.
300
301User Configuration
302==================
303
304Once the user has installed U-Boot, it is expected that the environment will
305be reset to the default values in order to enable $bootcmd and friends, as set
306up by <config_distro_bootcmd.h>. After this, various environment variables may
307be altered to influence the boot process:
308
309boot_targets:
310
311 The list of boot locations searched.
312
313 Example: mmc0, mmc1, usb, pxe
314
315 Entries may be removed or re-ordered in this list to affect the boot order.
316
317boot_prefixes:
318
319 For disk-based booting, the list of directories within a partition that are
320 searched for boot configuration files (extlinux.conf, boot.scr).
321
322 Example: / /boot/
323
324 Entries may be removed or re-ordered in this list to affect the set of
325 directories which are searched.
326
327boot_scripts:
328
329 The name of U-Boot style boot.scr files that $bootcmd searches for.
330
331 Example: boot.scr.uimg boot.scr
332
333 (Typically we expect extlinux.conf to be used, but execution of boot.scr is
334 maintained for backwards-compatibility.)
335
336 Entries may be removed or re-ordered in this list to affect the set of
337 filenames which are supported.
338
339scan_dev_for_extlinux:
340
341 If you want to disable extlinux.conf on all disks, set the value to something
342 innocuous, e.g. setenv scan_dev_for_extlinux true.
343
344scan_dev_for_scripts:
345
346 If you want to disable boot.scr on all disks, set the value to something
347 innocuous, e.g. setenv scan_dev_for_scripts true.
Karsten Merker8c249292015-03-21 14:15:38 +0100348
Stephen Warren3483b752016-01-26 11:10:12 -0700349boot_net_usb_start:
350
351 If you want to prevent USB enumeration by distro boot commands which execute
352 network operations, set the value to something innocuous, e.g. setenv
353 boot_net_usb_start true. This would be useful if you know your Ethernet
354 device is not attached to USB, and you wish to increase boot speed by
355 avoiding unnecessary actions.
Karsten Merker8c249292015-03-21 14:15:38 +0100356
Stephen Warren986691f2016-01-26 11:10:13 -0700357boot_net_pci_enum:
358
359 If you want to prevent PCI enumeration by distro boot commands which execute
360 network operations, set the value to something innocuous, e.g. setenv
361 boot_net_pci_enum true. This would be useful if you know your Ethernet
362 device is not attached to PCI, and you wish to increase boot speed by
363 avoiding unnecessary actions.
364
Karsten Merker8c249292015-03-21 14:15:38 +0100365Interactively booting from a specific device at the u-boot prompt
366=================================================================
367
368For interactively booting from a user-selected device at the u-boot command
369prompt, the environment provides predefined bootcmd_<target> variables for
370every target defined in boot_targets, which can be run be the user.
371
372If the target is a storage device, the format of the target is always
373<device type><device number>, e.g. mmc0. Specifying the device number is
374mandatory for storage devices, even if only support for a single instance
375of the storage device is actually implemented.
376
377For network targets (dhcp, pxe), only the device type gets specified;
378they do not have a device number.
379
380Examples:
381
382 - run bootcmd_usb0
383 boots from the first USB mass storage device
384
385 - run bootcmd_mmc1
386 boots from the second MMC device
387
388 - run bootcmd_pxe
389 boots by tftp using a pxelinux.cfg
390
391The list of possible targets consists of:
392
393- network targets
394 * dhcp
395 * pxe
396
397- storage targets (to which a device number must be appended)
398 * mmc
399 * sata
400 * scsi
401 * ide
402 * usb
403
404Other *boot* variables than the ones defined above are only for internal use
405of the boot environment and are not guaranteed to exist or work in the same
406way in future u-boot versions. In particular the <device type>_boot
407variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
408detail and must not be used as a public interface.