-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 <merker@debian.org>
- */
+.. SPDX-License-Identifier: GPL-2.0+
Generic Distro Configuration Concept
====================================
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:
+as specified at BootLoaderSpec_:
-http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
... with the exceptions that the BootLoaderSpec document:
* 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:
+One example extlinux.conf generated by the Fedora installer is::
-------------------------------------------------------------
-# extlinux.conf generated by anaconda
+ # extlinux.conf generated by anaconda
-ui menu.c32
+ 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
+ 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
+ timeout 50
+ #totaltimeout 9000
-default Fedora (3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae) 22 (Rawhide)
+ 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) 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 (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
-------------------------------------------------------------
+ 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
+Another hand-crafted network boot configuration file is::
-MENU TITLE TFTP boot options
+ TIMEOUT 100
-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
+ MENU TITLE TFTP boot options
-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 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 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 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 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
-------------------------------------------------------------
+ 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
=====================
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:
+In your board configuration file, include the following::
-------------------------------------------------------------
-#ifndef CONFIG_SPL_BUILD
-#include <config_distro_bootcmd.h>
-#endif
-------------------------------------------------------------
+ #ifndef CONFIG_SPL_BUILD
+ #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
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.
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.
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
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_,
+ 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.
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.
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
+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 <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
-------------------------------------------------------------
+<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
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).
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
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
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
The list of possible targets consists of:
- network targets
+
* dhcp
* pxe
- storage targets (to which a device number must be appended)
+
* mmc
* sata
* scsi
way in future u-boot versions. In particular the <device type>_boot
variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
detail and must not be used as a public interface.
+
+.. _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 <merker@debian.org>
projects / u-boot.git / commitdiff