Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit ffb4f6f95a0b63a0e8eab81e006a26c9cd99ac5d

Authored by Dennis Gilmore
Committed by Tom Rini
1 parent ef2d17fe21
Exists in v2017.01-smarct4x and in 37 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, emb_lf_v2022.04, imx_v2015.04_4.1.15_1.0.0_ga, pitx_8mp_lf_v2020.04, smarc-8m-android-10.0.0_2.6.0, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc-imx6_v2018.03_4.14.98_2.0.0_ga, smarc-imx7_v2017.03_4.9.11_1.0.0_ga, smarc-imx7_v2018.03_4.14.98_2.0.0_ga, smarc-imx_v2015.04_4.1.15_1.0.0_ga, smarc-imx_v2017.03_4.9.11_1.0.0_ga, smarc-imx_v2017.03_4.9.88_2.0.0_ga, smarc-imx_v2017.03_o8.1.0_1.3.0_8m, smarc-imx_v2018.03_4.14.78_1.0.0_ga, smarc-m6.0.1_2.1.0-ga, smarc-n7.1.2_2.0.0-ga, smarc-rel_imx_4.1.15_2.0.0_ga, smarc_8m-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8m-imx_v2019.04_4.19.35_1.1.0, smarc_8m_00d0-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8mm-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0, smarc_8mp_lf_v2020.04, smarc_8mq-imx_v2020.04_5.4.24_2.1.0, smarc_8mq_lf_v2020.04, ti-u-boot-2015.07, v2015.07-smarct33, v2015.07-smarct33-emmc, v2015.07-smarct4x, v2016.05-dlt, v2016.05-smarct3x, v2016.05-smarct3x-emmc, v2016.05-smarct4x, v2017.01-smarct3x, v2017.01-smarct3x-emmc

add README.distro file 

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>

Showing 1 changed file with 341 additions and 0 deletions Side-by-side Diff

  1 +/*
  2 + * (C) Copyright 2014 Red Hat Inc.
  3 + * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved.
  4 + *
  5 + * SPDX-License-Identifier: GPL-2.0+
  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 cannnot 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 partition during installation. This distro-supplied U-Boot
  40 +can still implement the same features as on any other board, and hence the
  41 +distro's boot 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 absense 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 configuration file, include the following:
  165 +
  166 +------------------------------------------------------------
  167 +#ifndef CONFIG_SPL_BUILD
  168 +#include <config_distro_defaults.h>
  169 +#include <config_distro_bootcmd.h>
  170 +#endif
  171 +------------------------------------------------------------
  172 +
  173 +The first of those headers primarily enables a core set of U-Boot features,
  174 +such as support for MBR and GPT partitions, ext* and FAT filesystems, booting
  175 +raw zImage and initrd (rather than FIT- or uImage-wrapped files), etc. Network
  176 +boot support is also enabled here, which is useful in order to boot distro
  177 +installers given that distros do not commonly distribute bootable install
  178 +media for non-PC targets at present.
  179 +
  180 +Finally, a few options that are mostly relevant only when using U-Boot-
  181 +specific boot.scr scripts are enabled. This enables distros to generate a
  182 +U-Boot-specific boot.scr script rather than extlinux.conf as the boot
  183 +configuration file. While doing so is fully supported, and
  184 +<config_distro_defaults.h> exposes enough parameterization to boot.scr to
  185 +allow for board-agnostic boot.scr content, this document recommends that
  186 +distros generate extlinux.conf rather than boot.scr. extlinux.conf is intended
  187 +to work across multiple bootloaders, whereas boot.scr will only work with
  188 +U-Boot. TODO: document the contract between U-Boot and boot.scr re: which
  189 +environment variables a generic boot.scr may rely upon.
  190 +
  191 +The second of those headers sets up the default environment so that $bootcmd
  192 +is defined in a way that searches attached disks for boot configuration files,
  193 +and executes them if found.
  194 +
  195 +Required Environment Variables
  196 +------------------------------
  197 +
  198 +The U-Boot "syslinux" and "pxe boot" commands require a number of environment
  199 +variables be set. Default values for these variables are often hard-coded into
  200 +CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
  201 +the user doesn't have to configure them.
  202 +
  203 +fdt_addr:
  204 +
  205 + Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes
  206 + to pass that DTB to Linux, rather than loading a DTB from the boot
  207 + filesystem. Prohibited for any other system.
  208 +
  209 + If specified a DTB to boot the system must be available at the given
  210 + address.
  211 +
  212 +fdt_addr_r:
  213 +
  214 + Mandatory. The location in RAM where the DTB will be loaded or copied to when
  215 + processing the fdtdir/devicetreedir or fdt/devicetree options in
  216 + extlinux.conf.
  217 +
  218 + This is mandatory even when fdt_addr is provided, since extlinux.conf must
  219 + always be able to provide a DTB which overrides any copy provided by the HW.
  220 +
  221 + A size of 1MB for the FDT/DTB seems reasonable.
  222 +
  223 +ramdisk_addr_r:
  224 +
  225 + Mandatory. The location in RAM where the initial ramdisk will be loaded to
  226 + when processing the initrd option in extlinux.conf.
  227 +
  228 + It is recommended that this location be highest in RAM out of fdt_addr_,
  229 + kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size
  230 + and use any available RAM.
  231 +
  232 +kernel_addr_r:
  233 +
  234 + Mandatory. The location in RAM where the kernel will be loaded to when
  235 + processing the kernel option in the extlinux.conf.
  236 +
  237 + The kernel should be located within the first 128M of RAM in order for the
  238 + kernel CONFIG_AUTO_ZRELADDR option to work, which is likely enabled on any
  239 + distro kernel. Since the kernel will decompress itself to 0x8000 after the
  240 + start of RAM, kernel_addr_rshould not overlap that area, or the kernel will
  241 + have to copy itself somewhere else first before decompression.
  242 +
  243 + A size of 16MB for the kernel is likely adequate.
  244 +
  245 +pxe_addr_r:
  246 +
  247 + Mandatory. The location in RAM where extlinux.conf will be loaded to prior
  248 + to processing.
  249 +
  250 + A size of 1MB for extlinux.conf is more than adequate.
  251 +
  252 +scriptaddr:
  253 +
  254 + Mandatory, if the boot script is boot.scr rather than extlinux.conf. The
  255 + location in RAM where boot.scr will be loaded to prior to execution.
  256 +
  257 + A size of 1MB for extlinux.conf is more than adequate.
  258 +
  259 +For suggestions on memory locations for ARM systems, you must follow the
  260 +guidelines specified in Documentation/arm/Booting in the Linux kernel tree.
  261 +
  262 +For a commented example of setting these values, please see the definition of
  263 +MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.
  264 +
  265 +Boot Target Configuration
  266 +-------------------------
  267 +
  268 +<config_distro_bootcmd.h> defines $bootcmd and many helper command variables
  269 +that automatically search attached disks for boot configuration files and
  270 +execute them. Boards must provide configure <config_distro_bootcmd.h> so that
  271 +it supports the correct set of possible boot device types. To provide this
  272 +configuration, simply define macro BOOT_TARGET_DEVICES prior to including
  273 +<config_distro_bootcmd.h>. For example:
  274 +
  275 +------------------------------------------------------------
  276 +#ifndef CONFIG_SPL_BUILD
  277 +#define BOOT_TARGET_DEVICES(func) \
  278 + func(MMC, mmc, 1) \
  279 + func(MMC, mmc, 0) \
  280 + func(USB, usb, 0) \
  281 + func(PXE, pxe, na) \
  282 + func(DHCP, dhcp, na)
  283 +#include <config_distro_bootcmd.h>
  284 +#endif
  285 +------------------------------------------------------------
  286 +
  287 +Each entry in the macro defines a single boot device (e.g. a specific eMMC
  288 +device or SD card) or type of boot device (e.g. USB disk). The parameters to
  289 +the func macro (passed in by the internal implementation of the header) are:
  290 +
  291 +- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE).
  292 +- Lower-case disk type (same options as above).
  293 +- ID of the specific disk (MMC only) or ignored for other types.
  294 +
  295 +User Configuration
  296 +==================
  297 +
  298 +Once the user has installed U-Boot, it is expected that the environment will
  299 +be reset to the default values in order to enable $bootcmd and friends, as set
  300 +up by <config_distro_bootcmd.h>. After this, various environment variables may
  301 +be altered to influence the boot process:
  302 +
  303 +boot_targets:
  304 +
  305 + The list of boot locations searched.
  306 +
  307 + Example: mmc0, mmc1, usb, pxe
  308 +
  309 + Entries may be removed or re-ordered in this list to affect the boot order.
  310 +
  311 +boot_prefixes:
  312 +
  313 + For disk-based booting, the list of directories within a partition that are
  314 + searched for boot configuration files (extlinux.conf, boot.scr).
  315 +
  316 + Example: / /boot/
  317 +
  318 + Entries may be removed or re-ordered in this list to affect the set of
  319 + directories which are searched.
  320 +
  321 +boot_scripts:
  322 +
  323 + The name of U-Boot style boot.scr files that $bootcmd searches for.
  324 +
  325 + Example: boot.scr.uimg boot.scr
  326 +
  327 + (Typically we expect extlinux.conf to be used, but execution of boot.scr is
  328 + maintained for backwards-compatibility.)
  329 +
  330 + Entries may be removed or re-ordered in this list to affect the set of
  331 + filenames which are supported.
  332 +
  333 +scan_dev_for_extlinux:
  334 +
  335 + If you want to disable extlinux.conf on all disks, set the value to something
  336 + innocuous, e.g. setenv scan_dev_for_extlinux true.
  337 +
  338 +scan_dev_for_scripts:
  339 +
  340 + If you want to disable boot.scr on all disks, set the value to something
  341 + innocuous, e.g. setenv scan_dev_for_scripts true.