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>master
parent
ef2d17fe21
commit
ffb4f6f95a
@ -0,0 +1,341 @@ |
||||
/* |
||||
* (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 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 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. |
Loading…
Reference in new issue