From 19a91f2464a89402a925fd4a2d8b7e28c804c7cc Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Oct 2021 12:47:54 -0600 Subject: Create a new boot/ directory Quite a lot of the code in common/relates to booting and images. Before adding more it seems like a good time to move the code into its own directory. Most files with 'boot' or 'image' in them are moved, except: - autoboot.c which relates to U-Boot automatically running a script - bootstage.c which relates to U-Boot timing Drop the removal of boot* files from the output directory, since this interfers with the symlinks created by tools and there does not appear to be any such file from my brief testing. Signed-off-by: Simon Glass Reviewed-by: Artem Lapkin Tested-by: Artem Lapkin --- doc/android/boot-image.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/android/boot-image.rst b/doc/android/boot-image.rst index fa8f2a47ee3..71db02521b0 100644 --- a/doc/android/boot-image.rst +++ b/doc/android/boot-image.rst @@ -139,7 +139,7 @@ overview on the whole Android 10 boot process can be found at [8]_. C API for working with Android Boot Image format ------------------------------------------------ -.. kernel-doc:: common/image-android.c +.. kernel-doc:: boot/image-android.c :internal: References -- cgit v1.2.3 From 37c5195dfcd15781db9e9f7f414611dc1af3bd2e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Thu, 14 Oct 2021 12:48:10 -0600 Subject: doc: Move distro boot doc to rST Move this over to the new rST format. Signed-off-by: Simon Glass Reviewed-by: Artem Lapkin Reviewed-by: Ramon Fried --- doc/README.distro | 430 ------------------------------------------------- doc/develop/distro.rst | 411 ++++++++++++++++++++++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 3 files changed, 412 insertions(+), 430 deletions(-) delete mode 100644 doc/README.distro create mode 100644 doc/develop/distro.rst (limited to 'doc') diff --git a/doc/README.distro b/doc/README.distro deleted file mode 100644 index fa8cec11028..00000000000 --- a/doc/README.distro +++ /dev/null @@ -1,430 +0,0 @@ -SPDX-License-Identifier: GPL-2.0+ -/* - * (C) Copyright 2014 Red Hat Inc. - * Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. - * Copyright (C) 2015 K. Merker - */ - -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 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. - -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 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 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 -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'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 -#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 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. - -fdtfile: - - Mandatory. the name of the DTB file for the specific board for instance - the espressobin v5 board the value is "marvell/armada-3720-espressobin.dtb" - while on a clearfog pro it is "armada-388-clearfog-pro.dtb" in the case of - a board providing its firmware based DTB this value can be used to override - the DTB with a different DTB. fdtfile will automatically be set for you if - it matches the format ${soc}-${board}.dtb which covers most 32 bit use cases. - AArch64 generally does not match as the Linux kernel put the dtb files under - SoC vendor directories. - -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_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. - -kernel_comp_addr_r: - Optional. This is only required if user wants to boot Linux from a compressed - Image(.gz, .bz2, .lzma, .lzo) using the booti command. It represents the - location in RAM where the compressed Image will be decompressed temporarily. - Once the decompression is complete, the decompressed data will be moved to - 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. - - 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 -------------------------- - - defines $bootcmd and many helper command variables -that automatically search attached disks for boot configuration files and -execute them. Boards must provide configure 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 -. 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 -#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, VIRTIO). -- 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 . 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. - -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. diff --git a/doc/develop/distro.rst b/doc/develop/distro.rst new file mode 100644 index 00000000000..c522be69349 --- /dev/null +++ b/doc/develop/distro.rst @@ -0,0 +1,411 @@ +.. 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 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. + +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 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 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 +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 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'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 + #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 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. + +fdtfile: + Mandatory. the name of the DTB file for the specific board for instance + the espressobin v5 board the value is "marvell/armada-3720-espressobin.dtb" + while on a clearfog pro it is "armada-388-clearfog-pro.dtb" in the case of + a board providing its firmware based DTB this value can be used to override + the DTB with a different DTB. fdtfile will automatically be set for you if + it matches the format ${soc}-${board}.dtb which covers most 32 bit use cases. + AArch64 generally does not match as the Linux kernel put the dtb files under + SoC vendor directories. + +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_r, + 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_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. + +kernel_comp_addr_r: + Optional. This is only required if user wants to boot Linux from a compressed + Image(.gz, .bz2, .lzma, .lzo) using the booti command. It represents the + location in RAM where the compressed Image will be decompressed temporarily. + Once the decompression is complete, the decompressed data will be moved to + 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. + + 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 +------------------------- + +The `config_distro_bootcmd.h` file defines $bootcmd and many helper command +variables that automatically search attached disks for boot configuration files +and execute them. Boards must provide configure 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 +. 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 + #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, VIRTIO). +- 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 . 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. + +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. + +.. _BootLoaderSpec: http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/ + +.. sectionauthor:: (C) Copyright 2014 Red Hat Inc. +.. sectionauthor:: Copyright (c) 2014-2015, NVIDIA CORPORATION. All rights reserved. +.. sectionauthor:: Copyright (C) 2015 K. Merker diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 5e064a4dac1..b3871b16f35 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -14,6 +14,7 @@ Implementation commands config_binding devicetree/index + distro driver-model/index global_data logging -- cgit v1.2.3 From 7e713067eef3f713b989416df0dfd061b087ac0f Mon Sep 17 00:00:00 2001 From: Thomas Huth Date: Tue, 26 Oct 2021 14:31:18 +0200 Subject: Remove LYNX KDI remainders The last board that used to set CONFIG_LYNXKDI has been removed in commit 242836a893ae ("powerpc: ppc4xx: remove pcs440ep support"), doc/README.lynxkdi only talks about a MPC8260 board being supported, and the mpc8260 support has been removed four years ago in commit 2eb48ff7a210d ("powerpc, 8260: remove support for mpc8260") already, and common/lynxkdi.c only consists of an "#error" statement these days, so it seems like the LYNX KDI code is dead code nowadays. Let's remove it now. Signed-off-by: Thomas Huth --- doc/README.lynxkdi | 57 ------------------------------------------------------ 1 file changed, 57 deletions(-) delete mode 100644 doc/README.lynxkdi (limited to 'doc') diff --git a/doc/README.lynxkdi b/doc/README.lynxkdi deleted file mode 100644 index 076f01862a1..00000000000 --- a/doc/README.lynxkdi +++ /dev/null @@ -1,57 +0,0 @@ - LYNX KDI SUPPORT - - Last Update: July 20, 2003 -======================================================================= - -This file describes support for LynuxWorks KDI within U-Boot. Support -is enabled by defining CONFIG_LYNXKDI. - - -LYNXOS AND BLUECAT SUPPORTED -============================ -Both LynxOS and BlueCat linux KDIs are supported. The implementation -automatically detects which is being booted. When you use mkimage -you should specify "lynxos" for both (see target-specific notes). - - -SUPPORTED ARCHITECTURE/TARGETS -============================== -The following targets have been tested: - --PowerPC MPC8260ADS - - -FILES TO LOOK AT -================ -include/lynxkdi.h -defines a simple struct passed to a kdi. -common/lynxkdi.c -implements the call to the kdi. -common/cmd_bootm.c -top-level command implementation ("bootm"). - - -==================================================================== -TARGET SPECIFIC NOTES -==================================================================== - -MPC8260ADS -=========== -The default LynxOS and BlueCat implementations require some -modifications to the config file. - -Edit include/configs/MPC8260ADS.h to use the following: - -#define CONFIG_SYS_IMMR 0xFA200000 -#define CONFIG_SYS_BCSR 0xFA100000 -#define CONFIG_SYS_BR1_PRELIM 0xFA101801 - -When creating a LynxOS or BlueCat u-boot image using mkimage, -you must specify the following: - -Both: -A ppc -O lynxos -T kernel -C none -LynxOS: -a 0x00004000 -e 0x00004020 -BlueCat: -a 0x00500000 -e 0x00507000 - -To pass the MAC address to BlueCat you should define the -"fcc2_ether_addr" parameter in the "bootargs" environment -variable. E.g.: - -==> setenv bootargs fcc2_ether_addr=00:11:22:33:44:55:66 -- cgit v1.2.3