| /* |
| * (C) Copyright 2014 Red Hat Inc. |
| * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. |
| * Copyright (C) 2015 K. Merker <merker@debian.org> |
| * |
| * SPDX-License-Identifier: GPL-2.0+ |
| */ |
| |
| 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 "default y if ARCH_FOO" to the DISTRO_DEFAULTS section of |
| the Kconfig file in the root of the u-boot sources. |
| |
| In your board configuration file, include the following: |
| |
| ------------------------------------------------------------ |
| #ifndef CONFIG_SPL_BUILD |
| #include <config_distro_defaults.h> |
| #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.h> 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. |
| |
| 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). |
| - 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 |
| |
| 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. |