Blame view
doc/README.distro
16.1 KB
83d290c56 SPDX: Convert all... |
1 |
SPDX-License-Identifier: GPL-2.0+ |
ffb4f6f95 add README.distro... |
2 3 4 |
/* * (C) Copyright 2014 Red Hat Inc. * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. |
8c2492901 Document config_d... |
5 |
* Copyright (C) 2015 K. Merker <merker@debian.org> |
ffb4f6f95 add README.distro... |
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
*/ 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 |
28fd00b77 README.distro: fi... |
30 |
a standard partitioning scheme (MBR, GPT). Boards that cannot support this |
ffb4f6f95 add README.distro... |
31 32 33 34 35 36 37 38 |
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 |
28fd00b77 README.distro: fi... |
39 40 41 |
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. |
ffb4f6f95 add README.distro... |
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
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. |
28fd00b77 README.distro: fi... |
62 |
Note that in the absence of any partition that is explicitly marked bootable, |
ffb4f6f95 add README.distro... |
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 |
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 --------------------------- |
9f823615a Kconfig: Add a ne... |
162 163 164 |
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 |
7325f6cfd distro: use imply... |
165 |
add a "imply DISTRO_DEFAULTS" to your SoC CONFIG option. |
9f823615a Kconfig: Add a ne... |
166 |
|
ffb4f6f95 add README.distro... |
167 168 169 170 |
In your board configuration file, include the following: ------------------------------------------------------------ #ifndef CONFIG_SPL_BUILD |
ffb4f6f95 add README.distro... |
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 |
#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 |
ba8bf9481 Remove config_dis... |
186 |
CONFIG_DISTRO_DEFAULTS exposes enough parameterization to boot.scr to |
ffb4f6f95 add README.distro... |
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 |
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 |
28fd00b77 README.distro: fi... |
242 |
start of RAM, kernel_addr_r should not overlap that area, or the kernel will |
ffb4f6f95 add README.distro... |
243 244 245 |
have to copy itself somewhere else first before decompression. A size of 16MB for the kernel is likely adequate. |
7101c4ce8 Fix variable docu... |
246 |
pxefile_addr_r: |
ffb4f6f95 add README.distro... |
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 |
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: |
a8da9ff46 distro_bootcmd: a... |
291 |
- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE, VIRTIO). |
ffb4f6f95 add README.distro... |
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 |
- 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. |
8c2492901 Document config_d... |
342 |
|
3483b75d9 distro bootcmd: m... |
343 344 345 346 347 348 349 |
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. |
8c2492901 Document config_d... |
350 |
|
986691fb9 distro bootcmd: e... |
351 352 353 354 355 356 357 |
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. |
8c2492901 Document config_d... |
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 |
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 |
a8da9ff46 distro_bootcmd: a... |
396 |
* virtio |
8c2492901 Document config_d... |
397 398 399 400 401 402 |
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. |