doc/README.distro

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