xref: /openbmc/u-boot/doc/README.distro (revision 86bedaeb)
1/*
2 * (C) Copyright 2014 Red Hat Inc.
3 * Copyright (c) 2014-2015, NVIDIA CORPORATION.  All rights reserved.
4 *
5 * SPDX-License-Identifier:     GPL-2.0+
6 */
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
30a standard partitioning scheme (MBR, GPT). Boards that cannnot support this
31storage 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
39the boot partition partition during installation. This distro-supplied U-Boot
40can still implement the same features as on any other board, and hence the
41distro's boot configuration file generation logic can still be board-agnostic.
42
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
63Note that in the absense of any partition that is explicitly marked bootable,
64U-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
164In your board configuration file, include the following:
165
166------------------------------------------------------------
167#ifndef CONFIG_SPL_BUILD
168#include <config_distro_defaults.h>
169#include <config_distro_bootcmd.h>
170#endif
171------------------------------------------------------------
172
173The first of those headers primarily enables a core set of U-Boot features,
174such as support for MBR and GPT partitions, ext* and FAT filesystems, booting
175raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network
176boot support is also enabled here, which is useful in order to boot distro
177installers given that distros do not commonly distribute bootable install
178media for non-PC targets at present.
179
180Finally, a few options that are mostly relevant only when using U-Boot-
181specific boot.scr scripts are enabled. This enables distros to generate a
182U-Boot-specific boot.scr script rather than extlinux.conf as the boot
183configuration file. While doing so is fully supported, and
184<config_distro_defaults.h> exposes enough parameterization to boot.scr to
185allow for board-agnostic boot.scr content, this document recommends that
186distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
187to work across multiple bootloaders, whereas boot.scr will only work with
188U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
189environment variables a generic boot.scr may rely upon.
190
191The second of those headers sets up the default environment so that $bootcmd
192is defined in a way that searches attached disks for boot configuration files,
193and executes them if found.
194
195Required Environment Variables
196------------------------------
197
198The U-Boot "syslinux" and "pxe boot" commands require a number of environment
199variables be set. Default values for these variables are often hard-coded into
200CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
201the user doesn't have to configure them.
202
203fdt_addr:
204
205  Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes
206  to pass that DTB to Linux, rather than loading a DTB from the boot
207  filesystem. Prohibited for any other system.
208
209  If specified a DTB to boot the system must be available at the given
210  address.
211
212fdt_addr_r:
213
214  Mandatory. The location in RAM where the DTB will be loaded or copied to when
215  processing the fdtdir/devicetreedir or fdt/devicetree options in
216  extlinux.conf.
217
218  This is mandatory even when fdt_addr is provided, since extlinux.conf must
219  always be able to provide a DTB which overrides any copy provided by the HW.
220
221  A size of 1MB for the FDT/DTB seems reasonable.
222
223ramdisk_addr_r:
224
225  Mandatory. The location in RAM where the initial ramdisk will be loaded to
226  when processing the initrd option in extlinux.conf.
227
228  It is recommended that this location be highest in RAM out of fdt_addr_,
229  kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size
230  and use any available RAM.
231
232kernel_addr_r:
233
234  Mandatory. The location in RAM where the kernel will be loaded to when
235  processing the kernel option in the extlinux.conf.
236
237  The kernel should be located within the first 128M of RAM in order for the
238  kernel CONFIG_AUTO_ZRELADDR option to work, which is likely enabled on any
239  distro kernel. Since the kernel will decompress itself to 0x8000 after the
240  start of RAM, kernel_addr_rshould not overlap that area, or the kernel will
241  have to copy itself somewhere else first before decompression.
242
243  A size of 16MB for the kernel is likely adequate.
244
245pxe_addr_r:
246
247  Mandatory. The location in RAM where extlinux.conf will be loaded to prior
248  to processing.
249
250  A size of 1MB for extlinux.conf is more than adequate.
251
252scriptaddr:
253
254  Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
255  location in RAM where boot.scr will be loaded to prior to execution.
256
257  A size of 1MB for extlinux.conf is more than adequate.
258
259For suggestions on memory locations for ARM systems, you must follow the
260guidelines specified in Documentation/arm/Booting in the Linux kernel tree.
261
262For a commented example of setting these values, please see the definition of
263MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.
264
265Boot Target Configuration
266-------------------------
267
268<config_distro_bootcmd.h> defines $bootcmd and many helper command variables
269that automatically search attached disks for boot configuration files and
270execute them. Boards must provide configure <config_distro_bootcmd.h> so that
271it supports the correct set of possible boot device types. To provide this
272configuration, simply define macro BOOT_TARGET_DEVICES prior to including
273<config_distro_bootcmd.h>. For example:
274
275------------------------------------------------------------
276#ifndef CONFIG_SPL_BUILD
277#define BOOT_TARGET_DEVICES(func) \
278        func(MMC, mmc, 1) \
279        func(MMC, mmc, 0) \
280        func(USB, usb, 0) \
281        func(PXE, pxe, na) \
282        func(DHCP, dhcp, na)
283#include <config_distro_bootcmd.h>
284#endif
285------------------------------------------------------------
286
287Each entry in the macro defines a single boot device (e.g. a specific eMMC
288device or SD card) or type of boot device (e.g. USB disk). The parameters to
289the func macro (passed in by the internal implementation of the header) are:
290
291- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE).
292- Lower-case disk type (same options as above).
293- ID of the specific disk (MMC only) or ignored for other types.
294
295User Configuration
296==================
297
298Once the user has installed U-Boot, it is expected that the environment will
299be reset to the default values in order to enable $bootcmd and friends, as set
300up by <config_distro_bootcmd.h>. After this, various environment variables may
301be altered to influence the boot process:
302
303boot_targets:
304
305  The list of boot locations searched.
306
307  Example: mmc0, mmc1, usb, pxe
308
309  Entries may be removed or re-ordered in this list to affect the boot order.
310
311boot_prefixes:
312
313  For disk-based booting, the list of directories within a partition that are
314  searched for boot configuration files (extlinux.conf, boot.scr).
315
316  Example: / /boot/
317
318  Entries may be removed or re-ordered in this list to affect the set of
319  directories which are searched.
320
321boot_scripts:
322
323  The name of U-Boot style boot.scr files that $bootcmd searches for.
324
325  Example: boot.scr.uimg boot.scr
326
327  (Typically we expect extlinux.conf to be used, but execution of boot.scr is
328  maintained for backwards-compatibility.)
329
330  Entries may be removed or re-ordered in this list to affect the set of
331  filenames which are supported.
332
333scan_dev_for_extlinux:
334
335  If you want to disable extlinux.conf on all disks, set the value to something
336  innocuous, e.g. setenv scan_dev_for_extlinux true.
337
338scan_dev_for_scripts:
339
340  If you want to disable boot.scr on all disks, set the value to something
341  innocuous, e.g. setenv scan_dev_for_scripts true.
342