Mirrors/u-boot
2
0
Fork 0
mirror of https://github.com/AsahiLinux/u-boot synced 2024-11-28 07:31:15 +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

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

@ -1,9 +1,4 @@
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
====================================
@ -73,9 +68,8 @@ 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:
as specified at BootLoaderSpec_:
http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
... with the exceptions that the BootLoaderSpec document:
@ -87,9 +81,8 @@ http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/
* 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
ui menu.c32
@ -120,11 +113,10 @@ label Fedora-0-rescue-8f6ba7b039524e0eb957d2c9203f04bc (0-rescue-8f6ba7b039524e0
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:
------------------------------------------------------------
Another hand-crafted network boot configuration file is::
TIMEOUT 100
MENU TITLE TFTP boot options
@ -153,7 +145,6 @@ LABEL fedora-installer-fk
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
=====================
@ -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
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
------------------------------------------------------------
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
@ -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.
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.
@ -214,7 +202,6 @@ fdt_addr:
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.
@ -225,7 +212,6 @@ fdt_addr_r:
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
@ -236,16 +222,14 @@ fdtfile:
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.
@ -270,14 +254,12 @@ kernel_comp_size:
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.
@ -292,14 +274,13 @@ 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
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:
<config_distro_bootcmd.h>. For example::
------------------------------------------------------------
#ifndef CONFIG_SPL_BUILD
#define BOOT_TARGET_DEVICES(func) \
func(MMC, mmc, 1) \
@ -309,7 +290,6 @@ configuration, simply define macro BOOT_TARGET_DEVICES prior to including
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
@ -328,7 +308,6 @@ 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
@ -336,7 +315,6 @@ boot_targets:
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).
@ -346,7 +324,6 @@ boot_prefixes:
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
@ -358,17 +335,14 @@ boot_scripts:
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
@ -376,7 +350,6 @@ boot_net_usb_start:
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
@ -412,10 +385,12 @@ Examples:
The list of possible targets consists of:
- network targets
* dhcp
* pxe
- storage targets (to which a device number must be appended)
* mmc
* sata
* 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
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>

1
doc/develop/index.rst
View file

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