+SPDX-License-Identifier: GPL-2.0+
/*
* (C) Copyright 2014 Red Hat Inc.
* Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved.
- *
- * SPDX-License-Identifier: GPL-2.0+
+ * Copyright (C) 2015 K. Merker <merker@debian.org>
*/
Generic Distro Configuration Concept
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
+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.
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.
+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
-----------------------
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,
+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
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 "imply DISTRO_DEFAULTS" to your SoC CONFIG option.
+
In your board configuration file, include the following:
------------------------------------------------------------
#ifndef CONFIG_SPL_BUILD
-#include <config_distro_defaults.h>
#include <config_distro_bootcmd.h>
#endif
------------------------------------------------------------
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
+CONFIG_DISTRO_DEFAULTS 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
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
+ 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.
-pxe_addr_r:
+kernel_comp_addr_r:
+ Optional. This is only required if user wants to boot Linux from a compressed
+ Image(.gz, .bz2, .lzma, .lzo) using booti command. It represents the location
+ in RAM where the compressed Image will be decompressed temporarily. Once the
+ decompression is complete, decompressed data will be moved kernel_addr_r for
+ booting.
+
+kernel_comp_size:
+ Optional. This is only required if user wants to boot Linux from a compressed
+ Image using booti command. It represents the size of the compressed file. The
+ size has to at least the size of loaded image for decompression to succeed.
+
+pxefile_addr_r:
Mandatory. The location in RAM where extlinux.conf will be loaded to prior
to processing.
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).
+- Upper-case disk type (MMC, SATA, SCSI, IDE, USB, DHCP, PXE, VIRTIO).
- Lower-case disk type (same options as above).
- ID of the specific disk (MMC only) or ignored for other types.
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
+ * virtio
+
+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.
projects / oweals / u-boot.git / blobdiff