Mirrors/u-boot
2
0
Fork 0
mirror of https://github.com/AsahiLinux/u-boot synced 2025-02-17 22:49:02 +00:00
Code Issues Projects Releases Packages Wiki Activity

doc: Move distro boot doc to rST

Browse source 
Move this over to the new rST format.

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Artem Lapkin <email2tema@gmail.com>
Reviewed-by: Ramon Fried <rfried.dev@gmail.com>
This commit is contained in:
Simon Glass 2021-10-14 12:48:10 -06:00 • committed by Tom Rini
parent 81a2f8d34b
commit 37c5195dfc
2 changed files with 79 additions and 97 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

175
doc/README.distro → doc/develop/distro.rst
View file

@ -1,9 +1,4 @@
SPDX-License-Identifier: GPL-2.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 <merker@debian.org>
*/
Generic Distro Configuration Concept Generic Distro Configuration Concept
==================================== ====================================
@ -73,9 +68,8 @@ Boot Configuration Files
The standard format for boot configuration files is that of extlinux.conf, as 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 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: ... with the exceptions that the BootLoaderSpec document:
@ -87,73 +81,70 @@ http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
* Does not document the fdtdir option, which automatically selects the DTB to * Does not document the fdtdir option, which automatically selects the DTB to
pass to the kernel. 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 autoboot Welcome to Fedora. Automatic boot in # second{,s}. Press a key for options.
menu title Fedora Boot Options. menu title Fedora Boot Options.
menu hidden menu hidden
timeout 50 timeout 50
#totaltimeout 9000 #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) 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 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 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 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 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) 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 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 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 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 initrd /boot/initramfs-3.17.0-0.rc4.git2.1.fc22.armv7hl+lpae.img
label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc) label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0eb957d2c9203f04bc)
kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc kernel /boot/vmlinuz-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc
initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img initrd /boot/initramfs-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc.img
append ro root=UUID=8eac677f-8ea8-4270-8479-d5ddbb797450 console=ttyS0,115200n8 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 fdtdir /boot/dtb-3.16.0-0.rc6.git1.1.fc22.armv7hl+lpae
------------------------------------------------------------
Another hand-crafted network boot configuration file is:
------------------------------------------------------------ Another hand-crafted network boot configuration file is::
TIMEOUT 100
MENU TITLE TFTP boot options TIMEOUT 100
LABEL jetson-tk1-emmc MENU TITLE TFTP boot options
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 LABEL jetson-tk1-emmc
MENU LABEL ../zImage root on Venice2 eMMC MENU LABEL ../zImage root on Jetson TK1 eMMC
LINUX ../zImage LINUX ../zImage
FDTDIR ../ FDTDIR ../
APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=80a5a8e9-c744-491a-93c1-4f4194fd690b
LABEL sdcard LABEL venice2-emmc
MENU LABEL ../zImage, root on 2GB sdcard MENU LABEL ../zImage root on Venice2 eMMC
LINUX ../zImage LINUX ../zImage
FDTDIR ../ FDTDIR ../
APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7 APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=5f71e06f-be08-48ed-b1ef-ee4800cc860f
LABEL fedora-installer-fk LABEL sdcard
MENU LABEL Fedora installer w/ Fedora kernel MENU LABEL ../zImage, root on 2GB sdcard
LINUX fedora-installer/vmlinuz LINUX ../zImage
INITRD fedora-installer/initrd.img.orig FDTDIR ../
FDTDIR fedora-installer/dtb APPEND console=ttyS0,115200n8 console=tty1 loglevel=8 rootwait rw earlyprintk root=PARTUUID=b2f82cda-2535-4779-b467-094a210fbae7
APPEND loglevel=8 ip=dhcp inst.repo=http://10.0.0.2/mirrors/fedora/linux/development/rawhide/armhfp/os/ rd.shell cma=64M
------------------------------------------------------------ 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 U-Boot Implementation
===================== =====================
@ -166,13 +157,11 @@ 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 from Kconfig itself, for e.g. all boards using a specific SoC then
add a "imply DISTRO_DEFAULTS" to your SoC CONFIG option. 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
#ifndef CONFIG_SPL_BUILD #include <config_distro_bootcmd.h>
#include <config_distro_bootcmd.h> #endif
#endif
------------------------------------------------------------
The first of those headers primarily enables a core set of U-Boot features, 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 such as support for MBR and GPT partitions, ext* and FAT filesystems, booting
@ -205,7 +194,6 @@ CONFIG_EXTRA_ENV_SETTINGS in the board's U-Boot configuration file, so that
the user doesn't have to configure them. the user doesn't have to configure them.
fdt_addr: fdt_addr:
Mandatory for any system that provides the DTB in HW (e.g. ROM) and wishes 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 to pass that DTB to Linux, rather than loading a DTB from the boot
filesystem. Prohibited for any other system. filesystem. Prohibited for any other system.
@ -214,7 +202,6 @@ fdt_addr:
address. address.
fdt_addr_r: fdt_addr_r:
Mandatory. The location in RAM where the DTB will be loaded or copied to when Mandatory. The location in RAM where the DTB will be loaded or copied to when
processing the fdtdir/devicetreedir or fdt/devicetree options in processing the fdtdir/devicetreedir or fdt/devicetree options in
extlinux.conf. extlinux.conf.
@ -225,7 +212,6 @@ fdt_addr_r:
A size of 1MB for the FDT/DTB seems reasonable. A size of 1MB for the FDT/DTB seems reasonable.
fdtfile: fdtfile:
Mandatory. the name of the DTB file for the specific board for instance 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" 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 while on a clearfog pro it is "armada-388-clearfog-pro.dtb" in the case of
@ -236,16 +222,14 @@ fdtfile:
SoC vendor directories. SoC vendor directories.
ramdisk_addr_r: ramdisk_addr_r:
Mandatory. The location in RAM where the initial ramdisk will be loaded to Mandatory. The location in RAM where the initial ramdisk will be loaded to
when processing the initrd option in extlinux.conf. 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 kernel_addr_r, and ramdisk_addr_r, so that the RAM disk can vary in size
and use any available RAM. and use any available RAM.
kernel_addr_r: kernel_addr_r:
Mandatory. The location in RAM where the kernel will be loaded to when Mandatory. The location in RAM where the kernel will be loaded to when
processing the kernel option in the extlinux.conf. processing the kernel option in the extlinux.conf.
@ -270,14 +254,12 @@ kernel_comp_size:
size has to at least the size of loaded image for decompression to succeed. size has to at least the size of loaded image for decompression to succeed.
pxefile_addr_r: pxefile_addr_r:
Mandatory. The location in RAM where extlinux.conf will be loaded to prior Mandatory. The location in RAM where extlinux.conf will be loaded to prior
to processing. to processing.
A size of 1MB for extlinux.conf is more than adequate. A size of 1MB for extlinux.conf is more than adequate.
scriptaddr: scriptaddr:
Mandatory, if the boot script is boot.scr rather than extlinux.conf. The 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. location in RAM where boot.scr will be loaded to prior to execution.
@ -292,24 +274,22 @@ MEM_LAYOUT_ENV_SETTINGS in include/configs/tegra124-common.h.
Boot Target Configuration Boot Target Configuration
------------------------- -------------------------
<config_distro_bootcmd.h> defines $bootcmd and many helper command variables The `config_distro_bootcmd.h` file defines $bootcmd and many helper command
that automatically search attached disks for boot configuration files and variables that automatically search attached disks for boot configuration files
execute them. Boards must provide configure <config_distro_bootcmd.h> so that and execute them. Boards must provide configure <config_distro_bootcmd.h> so
it supports the correct set of possible boot device types. To provide this that it supports the correct set of possible boot device types. To provide this
configuration, simply define macro BOOT_TARGET_DEVICES prior to including configuration, simply define macro BOOT_TARGET_DEVICES prior to including
<config_distro_bootcmd.h>. For example: <config_distro_bootcmd.h>. For example::
------------------------------------------------------------ #ifndef CONFIG_SPL_BUILD
#ifndef CONFIG_SPL_BUILD #define BOOT_TARGET_DEVICES(func) \
#define BOOT_TARGET_DEVICES(func) \ func(MMC, mmc, 1) \
func(MMC, mmc, 1) \ func(MMC, mmc, 0) \
func(MMC, mmc, 0) \ func(USB, usb, 0) \
func(USB, usb, 0) \ func(PXE, pxe, na) \
func(PXE, pxe, na) \ func(DHCP, dhcp, na)
func(DHCP, dhcp, na) #include <config_distro_bootcmd.h>
#include <config_distro_bootcmd.h> #endif
#endif
------------------------------------------------------------
Each entry in the macro defines a single boot device (e.g. a specific eMMC 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 device or SD card) or type of boot device (e.g. USB disk). The parameters to
@ -328,7 +308,6 @@ up by <config_distro_bootcmd.h>. After this, various environment variables may
be altered to influence the boot process: be altered to influence the boot process:
boot_targets: boot_targets:
The list of boot locations searched. The list of boot locations searched.
Example: mmc0, mmc1, usb, pxe Example: mmc0, mmc1, usb, pxe
@ -336,7 +315,6 @@ boot_targets:
Entries may be removed or re-ordered in this list to affect the boot order. Entries may be removed or re-ordered in this list to affect the boot order.
boot_prefixes: boot_prefixes:
For disk-based booting, the list of directories within a partition that are For disk-based booting, the list of directories within a partition that are
searched for boot configuration files (extlinux.conf, boot.scr). searched for boot configuration files (extlinux.conf, boot.scr).
@ -346,7 +324,6 @@ boot_prefixes:
directories which are searched. directories which are searched.
boot_scripts: boot_scripts:
The name of U-Boot style boot.scr files that $bootcmd searches for. The name of U-Boot style boot.scr files that $bootcmd searches for.
Example: boot.scr.uimg boot.scr Example: boot.scr.uimg boot.scr
@ -358,17 +335,14 @@ boot_scripts:
filenames which are supported. filenames which are supported.
scan_dev_for_extlinux: scan_dev_for_extlinux:
If you want to disable extlinux.conf on all disks, set the value to something If you want to disable extlinux.conf on all disks, set the value to something
innocuous, e.g. setenv scan_dev_for_extlinux true. innocuous, e.g. setenv scan_dev_for_extlinux true.
scan_dev_for_scripts: scan_dev_for_scripts:
If you want to disable boot.scr on all disks, set the value to something If you want to disable boot.scr on all disks, set the value to something
innocuous, e.g. setenv scan_dev_for_scripts true. innocuous, e.g. setenv scan_dev_for_scripts true.
boot_net_usb_start: boot_net_usb_start:
If you want to prevent USB enumeration by distro boot commands which execute If you want to prevent USB enumeration by distro boot commands which execute
network operations, set the value to something innocuous, e.g. setenv 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 boot_net_usb_start true. This would be useful if you know your Ethernet
@ -376,7 +350,6 @@ boot_net_usb_start:
avoiding unnecessary actions. avoiding unnecessary actions.
boot_net_pci_enum: boot_net_pci_enum:
If you want to prevent PCI enumeration by distro boot commands which execute If you want to prevent PCI enumeration by distro boot commands which execute
network operations, set the value to something innocuous, e.g. setenv 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 boot_net_pci_enum true. This would be useful if you know your Ethernet
@ -412,10 +385,12 @@ Examples:
The list of possible targets consists of: The list of possible targets consists of:
- network targets - network targets
* dhcp * dhcp
* pxe * pxe
- storage targets (to which a device number must be appended) - storage targets (to which a device number must be appended)
* mmc * mmc
* sata * sata
* scsi * scsi
@ -428,3 +403,9 @@ of the boot environment and are not guaranteed to exist or work in the same
way in future u-boot versions. In particular the <device type>_boot way in future u-boot versions. In particular the <device type>_boot
variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation variables (e.g. mmc_boot, usb_boot) are a strictly internal implementation
detail and must not be used as a public interface. 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>

1
doc/develop/index.rst
View file

@ -14,6 +14,7 @@ Implementation
commands commands
config_binding config_binding
devicetree/index devicetree/index
distro
driver-model/index driver-model/index
global_data global_data
logging logging