X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2FREADME.distro;h=ab6e6f4e74be1407001add427fcabab6253a81fc;hb=ca5655d8006cfbaa4ff8ff450e4a5931e57fe050;hp=dd0f1c7b6afa812bb9bfa9830dcd0d40a6c9365f;hpb=e72d344386bf80738fab7a6bd37cb321f443093a;p=oweals%2Fu-boot.git diff --git a/doc/README.distro b/doc/README.distro index dd0f1c7b6a..ab6e6f4e74 100644 --- a/doc/README.distro +++ b/doc/README.distro @@ -1,8 +1,8 @@ +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 */ Generic Distro Configuration Concept @@ -27,7 +27,7 @@ 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 +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. @@ -36,9 +36,9 @@ 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. +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 ----------------------- @@ -60,7 +60,7 @@ 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, +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 @@ -161,11 +161,15 @@ 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 "imply DISTRO_DEFAULTS" to your SoC CONFIG option. + In your board configuration file, include the following: ------------------------------------------------------------ #ifndef CONFIG_SPL_BUILD -#include #include #endif ------------------------------------------------------------ @@ -181,7 +185,7 @@ 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 - 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 @@ -237,12 +241,12 @@ kernel_addr_r: 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: +pxefile_addr_r: Mandatory. The location in RAM where extlinux.conf will be loaded to prior to processing. @@ -288,7 +292,7 @@ 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). +- 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. @@ -339,3 +343,65 @@ 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_ 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 +, 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 _boot +variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation +detail and must not be used as a public interface.