From: Dennis Gilmore dennis@ausil.us
Add documentation on how to setup a system to use the generic distro configs and boot commands. This spells out what is needed to make a system conformant, but does not limit the board to only the defaults.
Signed-off-by: Dennis Gilmore dennis@ausil.us [swarren, added concept, user config, BOOT_TARGET_DEVICES sections. edited the rest] Signed-off-by: Stephen Warren swarren@nvidia.com --- v4: * Fix description of fdt_addr_r; it's mandatory in all cases, since extlinux.conf must always be able to override any ROM-provided DTB. * Indicate that boot.scr is fully supported, not a legacy option. Still, recommend use of extlinux.conf over boot.scr. v3: * Fix description of fdt_addr/fdt_addr_r to be clearer re: when the variables are mandatory. * Recommend setting scan_dev_for_* to an innocuous value, rather than unsetting them, to avoid errors during script execution. * Fixed a typo. --- doc/README.distro | 342 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 342 insertions(+) create mode 100644 doc/README.distro
diff --git a/doc/README.distro b/doc/README.distro new file mode 100644 index 000000000000..1969026c9a4b --- /dev/null +++ b/doc/README.distro @@ -0,0 +1,342 @@ +/* + * (C) Copyright 2014 Red Hat Inc. + * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. + * + * 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 cannnot 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 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 absense 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: + +* That 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 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_rshould 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. + +pxe_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.