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