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