[PATCH 17/28] doc: Move distro boot doc to rST

[Simon Glass <sjg@chromium.org>]

Move this over to the new rST format.

Signed-off-by: Simon Glass <sjg@chromium.org>
---

 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 c4f041ca712..105dcf28190 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 83c929babda..1fb0f06f6e8 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -12,6 +12,7 @@ Implementation
    ci_testing
    commands
    devicetree/index
+   distro
    driver-model/index
    global_data
    logging
-- 
2.33.0.rc1.237.g0d66db33f3-goog