Re: [PATCH v3 17/18] doc: Move distro boot doc to rST

[Ramon Fried <rfried.dev@gmail.com>]

On Thu, Oct 14, 2021 at 9:52 PM Simon Glass <sjg@chromium.org> wrote:
>
> Move this over to the new rST format.
>
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
>
> (no changes since v1)
>
>  doc/{README.distro => develop/distro.rst} | 177 ++++++++++------------
>  doc/develop/index.rst                     |   1 +
>  2 files changed, 80 insertions(+), 98 deletions(-)
>  rename doc/{README.distro => develop/distro.rst} (76%)
>
> diff --git a/doc/README.distro b/doc/develop/distro.rst
> similarity index 76%
> rename from doc/README.distro
> rename to doc/develop/distro.rst
> index fa8cec11028..c522be69349 100644
> --- a/doc/README.distro
> +++ b/doc/develop/distro.rst
> @@ -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,73 +81,70 @@ 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
> +    # 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
>  =====================
> @@ -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
> -------------------------------------------------------------
> +    #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,24 +274,22 @@ 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:
> -
> -------------------------------------------------------------
> -#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
> @@ -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>
> 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
> --
> 2.33.0.1079.g6e70778dc9-goog
>
Reviewed-by: Ramon Fried <rfried.dev@gmail.com>