doc/README.distro

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