[U-Boot] [PATCH V2] add README.distro file
From: Dennis Gilmore dennis@ausil.us
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 --- Back at the end of September, Otavio requested I or Dennis get this finished and submitted. Better late than never, right:-)
doc/README.distro | 327 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 327 insertions(+) create mode 100644 doc/README.distro
diff --git a/doc/README.distro b/doc/README.distro new file mode 100644 index 000000000000..da21aef4973a --- /dev/null +++ b/doc/README.distro @@ -0,0 +1,327 @@ +/* + * (C) Copyright 2014 Red Hat Inc. + * Copyright (c) 2014, 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: + +* That 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 boot configuration files are enabled This enables +compatibility with various board configurations that existed before these +distro default existed, and assumed boot.scr-based booting. + +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: + + Optional. 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. + + 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 any disk, delete this. + +scan_dev_for_scripts: + + If you want to disable boot.scr on any disk, delete this.
On Mon, 2014-12-22 at 13:46 -0700, Stephen Warren wrote:
From: Dennis Gilmore dennis@ausil.us
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
Looks good thanks. A few comments below.
+Finally, a few options that are mostly relevant only when using U-Boot- +specific boot.scr boot configuration files are enabled This enables +compatibility with various board configurations that existed before these +distro default existed, and assumed boot.scr-based booting.
Missing a "." in "are enabled This enables", I think.
+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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it? I hope it will remain, in which case I'd be happier if this parenthetical were remove or replaced with something like "(not used in extlinux.conf mode)".
+scan_dev_for_extlinux:
- If you want to disable extlinux.conf on any disk, delete this.
+scan_dev_for_scripts:
- If you want to disable boot.scr on any disk, delete this.
Does deleting them not result in a message about an undefined command during boot? Would it be better to replace with some sort of null command (e.g. ":" in shell, not sure what the u-boto equivalent is).
Ian.
On 12/28/2014 02:26 AM, Ian Campbell wrote:
On Mon, 2014-12-22 at 13:46 -0700, Stephen Warren wrote:
From: Dennis Gilmore dennis@ausil.us
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
Looks good thanks. A few comments below.
+Finally, a few options that are mostly relevant only when using U-Boot- +specific boot.scr boot configuration files are enabled This enables +compatibility with various board configurations that existed before these +distro default existed, and assumed boot.scr-based booting.
Missing a "." in "are enabled This enables", I think.
+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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it? I hope it will remain, in which case I'd be happier if this parenthetical were remove or replaced with something like "(not used in extlinux.conf mode)".
The intent here isn't really to deprecate anything but rather to introduce something new.
The new thing introduced here is a common way for distros to boot systems using extlinux.conf. The One True Way(TM) according to this feature is extlinux.conf:-)
However, since many boards already support boot.scr, and some (Tegra, RPi at least) automatically search for it in the same way this new feature searches for extlinux.conf, the scripts in config_distro_bootcmd.h fold in direct (compatibility) support for boot.scr too, so that boards don't have to implement that themselves and duplicate all the logic.
So, I don't expect anyone to remove boot.scr support. That said, I would hope for Debian to transition to using extlinux.conf so that when new boards enable it, Debian won't have to do work to update its boot.scr to cope with those boards.
+scan_dev_for_extlinux:
- If you want to disable extlinux.conf on any disk, delete this.
+scan_dev_for_scripts:
- If you want to disable boot.scr on any disk, delete this.
Does deleting them not result in a message about an undefined command during boot? Would it be better to replace with some sort of null command (e.g. ":" in shell, not sure what the u-boto equivalent is).
Yes, unsetting the variables does cause an error. I see I misremembered what I was doing here when I actually did NULL those out; the text should recommend "setenv scan_dev_for_extlinux true", not completely clearing the variables.
On Sun, 2014-12-28 at 09:26 +0000, Ian Campbell wrote:
+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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it?
Can someone confirm that there is no long term plan to drop boot.scr support?
I hope it will remain, in which case I'd be happier if this parenthetical were remove or replaced with something like "(not used in extlinux.conf mode)".
On 01/11/2015 02:45 AM, Ian Campbell wrote:
On Sun, 2014-12-28 at 09:26 +0000, Ian Campbell wrote:
+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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it?
Can someone confirm that there is no long term plan to drop boot.scr support?
extlinux.conf *is* the standard Linux boot process that config_distro_bootcmd.h enables. boot.scr is *not*. The whole point is to introduce a new simple standard that works the same everywhere (for Linux: across boards, across distros, across bootloaders).
I would expect boot.scr support to be maintained indefinitely for any board the currently supports it. I certainly know of no plan to remove any existing support for it, and am not going to make such a plan.
When adding support for config_distro_bootcmd.h to any board that doesn't support boot.scr already, I would not expect boards to want to start supporting boot.scr; it's a legacy method as far as config_distro_bootcmd.h is concerned.
(config_distro_bootcmd.h should be updated to make the boot.scr support optional, so it doesn't get enabled unless specifically requested, when boards add #include <config_distro_bootcmd.h>).
Supporting boot.scr may well be useful for a variety of non-Linux or legacy environments, so I'm not proposing anyone rip out support for it. Simply not add support for it if it hasn't been necessary already.
On Sun, Jan 11, 2015 at 10:54:03AM -0700, Stephen Warren wrote:
On 01/11/2015 02:45 AM, Ian Campbell wrote:
On Sun, 2014-12-28 at 09:26 +0000, Ian Campbell wrote:
+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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it?
Can someone confirm that there is no long term plan to drop boot.scr support?
extlinux.conf *is* the standard Linux boot process that config_distro_bootcmd.h enables. boot.scr is *not*. The whole point is to introduce a new simple standard that works the same everywhere (for Linux: across boards, across distros, across bootloaders).
Well, the only problem I see with this statement is that, uh, do we have buy-in from Debian?
I would expect boot.scr support to be maintained indefinitely for any board the currently supports it. I certainly know of no plan to remove any existing support for it, and am not going to make such a plan.
"boot.scr" is just a "boot script" with the appropriate legacy image header on it. That won't go away until U-Boot no longer supports legacy images, and there is currently no plan to actually drop that support.
On 01/11/2015 11:15 AM, Tom Rini wrote:
On Sun, Jan 11, 2015 at 10:54:03AM -0700, Stephen Warren wrote:
On 01/11/2015 02:45 AM, Ian Campbell wrote:
On Sun, 2014-12-28 at 09:26 +0000, Ian Campbell wrote:
+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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it?
Can someone confirm that there is no long term plan to drop boot.scr support?
extlinux.conf *is* the standard Linux boot process that config_distro_bootcmd.h enables. boot.scr is *not*. The whole point is to introduce a new simple standard that works the same everywhere (for Linux: across boards, across distros, across bootloaders).
Well, the only problem I see with this statement is that, uh, do we have buy-in from Debian?
Well, there was some discussion about standard boot setups on the cross-distro mailing list. I believe someone from Debian is at least familiar with Dennis's proposal to use extlinux.conf as the standard. There was certainly no definitive agreement in those discussions though.
That said, I don't think there's much choice but to standardize on /something/ other than boot.scr. boot.scr really isn't scalable for generic distros (as opposed to board-specific BSPs):
* boot.scr works differently on different boards, since the set of environment variables and U-Boot commands/features available to the script are different. This leads to extremely complex boot.scr implementations that distros each have to maintain.
I suppose we could fix this by standardizing the boot.scr execution environment; providing a consistent set of variables indicating where to load kernel/DTB/..., the board name (to auto-generate DTB filename), etc. However, standardizing this is more complex that standardizing on extlinux.conf and still doesn't solve:
* boot.scr doesn't work across different bootloaders. There's no reason generic distros should know anything much about bootloaders, other than how to generate a config file so the bootloader knows which kernel/initrd/DTB binaries to load.
* boot.scr must be generated (to boot.scr.uimg) using bootloader-specific tools, rather than extlinux.conf, grub.conf, ... all just need the generation of a text file.
On Mon, 2015-01-12 at 10:34 -0700, Stephen Warren wrote:
On 01/11/2015 11:15 AM, Tom Rini wrote:
On Sun, Jan 11, 2015 at 10:54:03AM -0700, Stephen Warren wrote:
On 01/11/2015 02:45 AM, Ian Campbell wrote:
On Sun, 2014-12-28 at 09:26 +0000, Ian Campbell wrote:
+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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it?
Can someone confirm that there is no long term plan to drop boot.scr support?
extlinux.conf *is* the standard Linux boot process that config_distro_bootcmd.h enables. boot.scr is *not*. The whole point is to introduce a new simple standard that works the same everywhere (for Linux: across boards, across distros, across bootloaders).
Well, the only problem I see with this statement is that, uh, do we have buy-in from Debian?
Well, there was some discussion about standard boot setups on the cross-distro mailing list. I believe someone from Debian is at least familiar with Dennis's proposal to use extlinux.conf as the standard. There was certainly no definitive agreement in those discussions though
I hadn't appreciated that that this proposal was so heavily geared towards the extlinux.conf aspect, as opposed to standardising a bunch of useful env variables, which is what I thought it was mainly doing.
That said, I don't think there's much choice but to standardize on /something/ other than boot.scr. boot.scr really isn't scalable for generic distros (as opposed to board-specific BSPs):
- boot.scr works differently on different boards, since the set of
environment variables and U-Boot commands/features available to the script are different. This leads to extremely complex boot.scr implementations that distros each have to maintain.
A side effect (which I actually thought was part of the purpose until now) of config_distro_bootcmd.h was to standardize these variables. Debian now ships a common boot.scr which should work on any config_distro_bootcmd-enabled system.
I suppose we could fix this by standardizing the boot.scr execution environment; providing a consistent set of variables indicating where to load kernel/DTB/..., the board name (to auto-generate DTB filename), etc. However, standardizing this is more complex that standardizing on extlinux.conf
AFAICT you've already done it ;-)
and still doesn't solve:
- boot.scr doesn't work across different bootloaders. There's no reason
generic distros should know anything much about bootloaders, other than how to generate a config file so the bootloader knows which kernel/initrd/DTB binaries to load.
The distro needs to know enough about the bootloader to know it speaks extlinux.conf, which means in practice it needs to know if it is u-boot or not.
From Debian's PoV the usual default bootloader is grub, which is pretty
much a no-go on top of u-boot in practice.
So whether it's extlinux.conf or boot.scr we have to treat things specially at the distro level and have some firmware awareness, and boot.scr is there and working today.
- boot.scr must be generated (to boot.scr.uimg) using
bootloader-specific tools, rather than extlinux.conf, grub.conf, ... all just need the generation of a text file.
Debian already has the tooling (and has for years) to reproduce boot.scr automatically on upgrades of various relevant components, the user never needs to see the mkimage stuff (that tooling also handles various legacy non-config_distro_bootcmd systems, so it's going to have to remain for the time being either way).
Currently the extlinux.conf generating stuff is tied to the x86 syslinux packages, it could be reworked and pulled out into arch indep packages, but there doesn't seem to be all that much benefit compared with what we have now which is working fairly well for us (not to imply that it's perfect).
Ian.
On 01/12/2015 10:57 AM, Ian Campbell wrote:
On Mon, 2015-01-12 at 10:34 -0700, Stephen Warren wrote:
On 01/11/2015 11:15 AM, Tom Rini wrote:
On Sun, Jan 11, 2015 at 10:54:03AM -0700, Stephen Warren wrote:
On 01/11/2015 02:45 AM, Ian Campbell wrote:
On Sun, 2014-12-28 at 09:26 +0000, Ian Campbell wrote:
> +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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it?
Can someone confirm that there is no long term plan to drop boot.scr support?
extlinux.conf *is* the standard Linux boot process that config_distro_bootcmd.h enables. boot.scr is *not*. The whole point is to introduce a new simple standard that works the same everywhere (for Linux: across boards, across distros, across bootloaders).
Well, the only problem I see with this statement is that, uh, do we have buy-in from Debian?
Well, there was some discussion about standard boot setups on the cross-distro mailing list. I believe someone from Debian is at least familiar with Dennis's proposal to use extlinux.conf as the standard. There was certainly no definitive agreement in those discussions though
I hadn't appreciated that that this proposal was so heavily geared towards the extlinux.conf aspect, as opposed to standardising a bunch of useful env variables, which is what I thought it was mainly doing.
That said, I don't think there's much choice but to standardize on /something/ other than boot.scr. boot.scr really isn't scalable for generic distros (as opposed to board-specific BSPs):
- boot.scr works differently on different boards, since the set of
environment variables and U-Boot commands/features available to the script are different. This leads to extremely complex boot.scr implementations that distros each have to maintain.
A side effect (which I actually thought was part of the purpose until now) of config_distro_bootcmd.h was to standardize these variables. Debian now ships a common boot.scr which should work on any config_distro_bootcmd-enabled system.
Oh, I didn't realize that at all.
I know that in the discussions on the cross-distro@ mailing list, there were arguments against standardizing on extlinux.conf. I hadn't read any of the replies as meaning Debian was picking up the boot.scr standardization work I had been doing though. Rather, since no agreement seemed to have been reach, I had assumed that Debian (and other distros) were sticking with the per-board-custom-boot.scr stuff they'd always had before.
I suppose we could fix this by standardizing the boot.scr execution environment; providing a consistent set of variables indicating where to load kernel/DTB/..., the board name (to auto-generate DTB filename), etc. However, standardizing this is more complex that standardizing on extlinux.conf
AFAICT you've already done it ;-)
Oh, so there's enough there to be considered complete?
I certainly was originally working towards standardizing boot.scr, so it's good to hear that was pretty successful.
However, since realizing that extlinux.conf was a cross-bootloader standard, I changed my mind and decided that was a better approach, so I've been looking to see that move forward.
I suppose for config_disto_bootcmd.h to be useful for non-Linux OSs too (which aren't supported by extlinux.conf AFAIK unless their boot protocol is compatible with Linux), we likely want to keep the boot.scr logic in config_distro_bootcmd.h fully enabled in all cases. As such, perhaps it does make sense to remove any reference to the boot.scr support config_distro_bootcmd.h as being legacy.
and still doesn't solve:
- boot.scr doesn't work across different bootloaders. There's no reason
generic distros should know anything much about bootloaders, other than how to generate a config file so the bootloader knows which kernel/initrd/DTB binaries to load.
The distro needs to know enough about the bootloader to know it speaks extlinux.conf, which means in practice it needs to know if it is u-boot or not.
Well, at least Barebox also supports extlinux.conf IIUC. The idea is that if the distro assumes extlinux.conf, it shouldn't have to know which bootloader is installed. More x86 implies Grub, ARM implies extlinux.conf.
From Debian's PoV the usual default bootloader is grub, which is pretty much a no-go on top of u-boot in practice.
So whether it's extlinux.conf or boot.scr we have to treat things specially at the distro level and have some firmware awareness, and boot.scr is there and working today.
- boot.scr must be generated (to boot.scr.uimg) using
bootloader-specific tools, rather than extlinux.conf, grub.conf, ... all just need the generation of a text file.
Debian already has the tooling (and has for years) to reproduce boot.scr automatically on upgrades of various relevant components, the user never needs to see the mkimage stuff (that tooling also handles various legacy non-config_distro_bootcmd systems, so it's going to have to remain for the time being either way).
Currently the extlinux.conf generating stuff is tied to the x86 syslinux packages, it could be reworked and pulled out into arch indep packages, but there doesn't seem to be all that much benefit compared with what we have now which is working fairly well for us (not to imply that it's perfect).
Ian.
On Mon, 2015-01-12 at 17:57 +0000, Ian Campbell wrote:
On Mon, 2015-01-12 at 10:34 -0700, Stephen Warren wrote:
- boot.scr must be generated (to boot.scr.uimg) using
bootloader-specific tools, rather than extlinux.conf, grub.conf, ... all just need the generation of a text file.
Debian already has the tooling (and has for years) to reproduce boot.scr automatically on upgrades of various relevant components, the user never needs to see the mkimage stuff (that tooling also handles various legacy non-config_distro_bootcmd systems, so it's going to have to remain for the time being either way).
Currently the extlinux.conf generating stuff is tied to the x86 syslinux packages, it could be reworked and pulled out into arch indep packages, but there doesn't seem to be all that much benefit compared with what we have now which is working fairly well for us (not to imply that it's perfect).
One big downside of the boot.scr as generated by flash-kernel in Debian is that it doesn't have a menu, which extlinux can provide currently. Thus with extlinux we could provide a more similar experience to what folks get on x86 with e.g. Grub, iotw select provide menu options to boot previous kernels or single user mode etc.
I do hope to get to experimenting a bit with this for the boards, i care about soon. My patchset that was in discussion there was actually some pre-work for those things ;). It would be nice if, in the end, flash-kernel wouldn't be needed for boards with modern u-boot and follwing the distro_boot_cmds, but I'm not actually involved with Debians u-boot package so not my call :)
On Mon, 12 Jan 2015 20:57:29 +0100 Sjoerd Simons sjoerd.simons@collabora.co.uk wrote:
On Mon, 2015-01-12 at 17:57 +0000, Ian Campbell wrote:
On Mon, 2015-01-12 at 10:34 -0700, Stephen Warren wrote:
- boot.scr must be generated (to boot.scr.uimg) using
bootloader-specific tools, rather than extlinux.conf, grub.conf, ... all just need the generation of a text file.
Debian already has the tooling (and has for years) to reproduce boot.scr automatically on upgrades of various relevant components, the user never needs to see the mkimage stuff (that tooling also handles various legacy non-config_distro_bootcmd systems, so it's going to have to remain for the time being either way).
Currently the extlinux.conf generating stuff is tied to the x86 syslinux packages, it could be reworked and pulled out into arch indep packages, but there doesn't seem to be all that much benefit compared with what we have now which is working fairly well for us (not to imply that it's perfect).
One big downside of the boot.scr as generated by flash-kernel in Debian is that it doesn't have a menu, which extlinux can provide currently. Thus with extlinux we could provide a more similar experience to what folks get on x86 with e.g. Grub, iotw select provide menu options to boot previous kernels or single user mode etc.
I do hope to get to experimenting a bit with this for the boards, i care about soon. My patchset that was in discussion there was actually some pre-work for those things ;). It would be nice if, in the end, flash-kernel wouldn't be needed for boards with modern u-boot and follwing the distro_boot_cmds, but I'm not actually involved with Debians u-boot package so not my call :)
I am carrying some patches in Fedora that were written by someone from debian porting a board to use the generic options, though it was incomplete and was missing variables for pxe booting to work. while we get a menu and you can choose older kernels currently there is no way to edit things dynamically. this is a feature I want to add. make it easy to append boot arguments etc. there seems to at least be interest in the debian camp. to what extent that interest goes I am not sure.
I will cover how things are in Fedora. It is still not perfect but is getting better every release. grubby updates extlinux.conf on kernel install/update/removal etc the exact same code is used on x86 and arm. we have a extlinux-bootloader package on arm that provides the framework needed that comes with syslinux-extlinux. anaconda writes out extlinux.conf on install. I have some scripting work to do to update it and add the fdtdir entry to extlinux.conf on install. the anaconda code to deal with extlinux.conf is shared between x86 and arm. appliance-creator which is the tool we use to make disk images writes out correct extlinux.conf files for both x86 and arm
from a end user perspective the experience is similar but not quite exactly the same. longer term id like to use u-boots menu code to offer up a menu to select the kernel and add editing features. But it is much easier now to support new boards than it ever has been in the past.
Dennis
On Mon, Jan 12, 2015 at 11:57 AM, Ian Campbell ijc@hellion.org.uk wrote:
On Mon, 2015-01-12 at 10:34 -0700, Stephen Warren wrote:
On 01/11/2015 11:15 AM, Tom Rini wrote:
On Sun, Jan 11, 2015 at 10:54:03AM -0700, Stephen Warren wrote:
On 01/11/2015 02:45 AM, Ian Campbell wrote:
On Sun, 2014-12-28 at 09:26 +0000, Ian Campbell wrote:
> +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.)
I'm slightly concerned by the implied deprecation of the boot.scr method here, since at least Debian uses boot.scr exclusively and not the extlinux stuff. Will boot.scr be maintained going forward or are there plans to eventually remove it?
Can someone confirm that there is no long term plan to drop boot.scr support?
extlinux.conf *is* the standard Linux boot process that config_distro_bootcmd.h enables. boot.scr is *not*. The whole point is to introduce a new simple standard that works the same everywhere (for Linux: across boards, across distros, across bootloaders).
Well, the only problem I see with this statement is that, uh, do we have buy-in from Debian?
Well, there was some discussion about standard boot setups on the cross-distro mailing list. I believe someone from Debian is at least familiar with Dennis's proposal to use extlinux.conf as the standard. There was certainly no definitive agreement in those discussions though
I hadn't appreciated that that this proposal was so heavily geared towards the extlinux.conf aspect, as opposed to standardising a bunch of useful env variables, which is what I thought it was mainly doing.
That said, I don't think there's much choice but to standardize on /something/ other than boot.scr. boot.scr really isn't scalable for generic distros (as opposed to board-specific BSPs):
- boot.scr works differently on different boards, since the set of
environment variables and U-Boot commands/features available to the script are different. This leads to extremely complex boot.scr implementations that distros each have to maintain.
A side effect (which I actually thought was part of the purpose until now) of config_distro_bootcmd.h was to standardize these variables. Debian now ships a common boot.scr which should work on any config_distro_bootcmd-enabled system.
I suppose we could fix this by standardizing the boot.scr execution environment; providing a consistent set of variables indicating where to load kernel/DTB/..., the board name (to auto-generate DTB filename), etc. However, standardizing this is more complex that standardizing on extlinux.conf
AFAICT you've already done it ;-)
and still doesn't solve:
- boot.scr doesn't work across different bootloaders. There's no reason
generic distros should know anything much about bootloaders, other than how to generate a config file so the bootloader knows which kernel/initrd/DTB binaries to load.
The distro needs to know enough about the bootloader to know it speaks extlinux.conf, which means in practice it needs to know if it is u-boot or not.
From Debian's PoV the usual default bootloader is grub, which is pretty much a no-go on top of u-boot in practice.
So whether it's extlinux.conf or boot.scr we have to treat things specially at the distro level and have some firmware awareness, and boot.scr is there and working today.
- boot.scr must be generated (to boot.scr.uimg) using
bootloader-specific tools, rather than extlinux.conf, grub.conf, ... all just need the generation of a text file.
Debian already has the tooling (and has for years) to reproduce boot.scr automatically on upgrades of various relevant components, the user never needs to see the mkimage stuff (that tooling also handles various legacy non-config_distro_bootcmd systems, so it's going to have to remain for the time being either way).
Currently the extlinux.conf generating stuff is tied to the x86 syslinux packages, it could be reworked and pulled out into arch indep packages, but there doesn't seem to be all that much benefit compared with what we have now which is working fairly well for us (not to imply that it's perfect).
I had a patch for syslinux doing just this sometime back. My mistake was giving it to Canonical to do something with. I could dig this up. It is pretty straightforward moving of files into the syslinux-common package. There were also some settings controlling generating the menu files needed on the target rootfs to get it to work with u-boot's limited syslinux. It wasn't something we could work-around or add support for in u-boot IIRC.
Rob
On Mon, 2014-12-22 at 13:46 -0700, Stephen Warren wrote:
[...]
+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:
- Optional. If specified a dtb to boot the system must be available at the
- given address.
+fdt_addr_r:
- Mandatory.
Isn't this one only mandatory if ${fdt_addr} is not given?
Ian.
On 12/28/2014 03:09 AM, Ian Campbell wrote:
On Mon, 2014-12-22 at 13:46 -0700, Stephen Warren wrote:
[...]
+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:
- Optional. If specified a dtb to boot the system must be available at the
- given address.
+fdt_addr_r:
- Mandatory.
Isn't this one only mandatory if ${fdt_addr} is not given?
Yes. I guess it's mandatory for at least one of fdt_addr or fdt_addr_r to be set, according to common/cmd_pxe.c:
* fdt usage is optional: * It handles the following scenarios. All scenarios are exclusive * * Scenario 1: If fdt_addr_r specified and "fdt" label is defined in * pxe file, retrieve fdt blob from server. Pass fdt_addr_r to bootm, * and adjust argc appropriately. * * Scenario 2: If there is an fdt_addr specified, pass it along to * bootm, and adjust argc appropriately. * * Scenario 3: fdt blob is not available.
So, I'll need to reword that a little to make that clear.
On Mon, 05 Jan 2015 12:55:46 -0700 Stephen Warren swarren@wwwdotorg.org wrote:
On 12/28/2014 03:09 AM, Ian Campbell wrote:
On Mon, 2014-12-22 at 13:46 -0700, Stephen Warren wrote:
[...]
+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:
- Optional. If specified a dtb to boot the system must be
available at the
- given address.
+fdt_addr_r:
- Mandatory.
Isn't this one only mandatory if ${fdt_addr} is not given?
Yes. I guess it's mandatory for at least one of fdt_addr or fdt_addr_r to be set, according to common/cmd_pxe.c:
fdt_addr_r is actually mandatory unless you do not support device tree at all, which is not expected at all anymore. The reason being that the user/distro can override the vendor supplied dtb for whatever reason, by supplying a fdt/dtb fdtdir/dtbdir entry in extlinux.conf in the past at times on calxeda hardware we had to override the dtb to work with newer kernels until we could update the systems firmware.
* fdt usage is optional: * It handles the following scenarios. All scenarios areexclusive * * Scenario 1: If fdt_addr_r specified and "fdt" label is defined in * pxe file, retrieve fdt blob from server. Pass fdt_addr_r to bootm, * and adjust argc appropriately. * * Scenario 2: If there is an fdt_addr specified, pass it along to * bootm, and adjust argc appropriately. * * Scenario 3: fdt blob is not available.
So, I'll need to reword that a little to make that clear.
going forward Scenario 3 is not a supportable option. board files are being removed from the kernel and dtb files are needed to boot machines. at least for Fedora we do not support any systems that do not support devicetree. so while the code in cmd_pxe.c is written for it to be optional it is not. having fdt_addr_r does not force the use of a dtb as it requires the config to specify it, so you could boot a legacy kernel just fine by omitting the definition in the config file.
Dennis
On 01/10/2015 11:44 AM, Dennis Gilmore wrote:
On Mon, 05 Jan 2015 12:55:46 -0700 Stephen Warren swarren@wwwdotorg.org wrote:
On 12/28/2014 03:09 AM, Ian Campbell wrote:
On Mon, 2014-12-22 at 13:46 -0700, Stephen Warren wrote:
[...]
+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:
- Optional. If specified a dtb to boot the system must be
available at the
- given address.
+fdt_addr_r:
- Mandatory.
Isn't this one only mandatory if ${fdt_addr} is not given?
Yes. I guess it's mandatory for at least one of fdt_addr or fdt_addr_r to be set, according to common/cmd_pxe.c:
fdt_addr_r is actually mandatory unless you do not support device tree at all, which is not expected at all anymore. The reason being that the user/distro can override the vendor supplied dtb for whatever reason, by supplying a fdt/dtb fdtdir/dtbdir entry in extlinux.conf in the past at times on calxeda hardware we had to override the dtb to work with newer kernels until we could update the systems firmware.
That's a good point. I'll revise the README again and repost a V4.
participants (6)
-
Dennis Gilmore -
Ian Campbell -
Rob Herring -
Sjoerd Simons -
Stephen Warren -
Tom Rini