doc: Convert Chromium OS docs to rst

Move this documentation over to reST. Move the example files into a files/
directory so they are still separate.

Do a few minor updates while we are here:
- Tidy up sandbox build instructions
- Update my github account name
- Add some talks and links

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

9 files changed, 183 insertions, 83 deletions

diff --git a/doc/README.chromium-chainload b/doc/chromium/chainload.rst
index 45eaece..7b6bb10 100644
--- a/doc/README.chromium-chainload
+++ b/doc/chromium/chainload.rst
@@ -1,3 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2020 Google LLC
+
 Running U-Boot from coreboot on Chromebooks
 ===========================================
 
@@ -15,7 +18,7 @@ replace the ROM unless you have a servo board and cable to restore it with.
 
 
 For all of these the standard U-Boot build instructions apply. For example on
-ARM:
+ARM::
 
    sudo apt install gcc-arm-linux-gnueabi
    mkdir b
@@ -37,14 +40,17 @@ https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-t
 Nyan-big
 --------
 
-Compiled based on information here:
-https://lists.denx.de/pipermail/u-boot/2015-March/209530.html
-https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big
-https://lists.denx.de/pipermail/u-boot/2017-May/289491.html
-https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card
+Compiled based on information here::
+
+   https://lists.denx.de/pipermail/u-boot/2015-March/209530.html
+   https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big
+   https://lists.denx.de/pipermail/u-boot/2017-May/289491.html
+   https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card
 
 1. Build U-Boot
 
+Steps::
+
    mkdir b
    make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all
 
@@ -61,16 +67,21 @@ kernel, and crashes if it is not present.
 
 3. Build and sign an image
 
-   ./b/nyan-big/tools/mkimage -f doc/chromium/nyan-big.its u-boot-chromium.fit
+Steps::
+
+   ./b/nyan-big/tools/mkimage -f doc/chromium/files/nyan-big.its u-boot-chromium.fit
    echo test >dummy.txt
-   vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
-	--signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
-	--version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
-	--bootloader dummy.txt --pack u-boot.kpart
+   vbutil_kernel --arch arm \
+     --keyblock doc/chromium/files/devkeys/kernel.keyblock \
+     --signprivate doc/chromium/files/devkeys/kernel_data_key.vbprivk \
+     --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
+     --bootloader dummy.txt --pack u-boot.kpart
 
 
 4. Prepare an SD card
 
+Steps::
+
    DISK=/dev/sdc   # Replace with your actual SD card device
    sudo cgpt create $DISK
    sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK
@@ -80,6 +91,8 @@ kernel, and crashes if it is not present.
 
 5. Write U-Boot to the SD card
 
+Steps::
+
    sudo dd if=u-boot.kpart of=/dev/sdc1; sync
 
 
@@ -90,7 +103,7 @@ do this, login as root (via Ctrl-Alt-forward_arrow) and type
 'enable_dev_usb_boot'. You only need to do this once.
 
 Reboot the device with the SD card inserted. Press Clrl-U at the developer
-mode screen. It should show something like the following on the display:
+mode screen. It should show something like the following on the display::
 
    U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600)
 
@@ -104,9 +117,9 @@ mode screen. It should show something like the following on the display:
 
 7. Known problems
 
-On the serial console the word MMC is chopped at the start of the line:
+On the serial console the word MMC is chopped at the start of the line::
 
-C:   sdhci@700b0000: 2, sdhci@700b0400: 1, sdhci@700b0600: 0
+   C:   sdhci@700b0000: 2, sdhci@700b0400: 1, sdhci@700b0600: 0
 
 This is likely due to some problem with change-over of the serial driver
 during relocation (or perhaps updating the clock setup in board_init()).
@@ -116,7 +129,7 @@ during relocation (or perhaps updating the clock setup in board_init()).
 
 To check that you copied the u-boot.its file correctly, use these commands.
 You should see that the data at 0x100 in u-boot-chromium.fit is the first few
-bytes of U-Boot:
+bytes of U-Boot::
 
    hd u-boot-chromium.fit |head -20
    ...
@@ -141,34 +154,39 @@ The instruction are similar to those for Nyan with changes as noted below:
 
 Open include/configs/rk3288_common.h
 
-Change:
+Change::
 
-#define CONFIG_SYS_TEXT_BASE		0x00100000
+   #define CONFIG_SYS_TEXT_BASE		0x00100000
 
-to:
+to::
 
-#define CONFIG_SYS_TEXT_BASE		0x02000100
+   #define CONFIG_SYS_TEXT_BASE		0x02000100
 
 
 
 2. Build U-Boot
 
+Steps::
+
    mkdir b
    make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \
-	chromebook_jerry_defconfig all
+      chromebook_jerry_defconfig all
 
 
 3. See above
 
 4. Build and sign an image
 
+Steps::
+
    ./b/chromebook_jerry/tools/mkimage -f doc/chromium/chromebook_jerry.its \
-	u-boot-chromium.fit
+      u-boot-chromium.fit
    echo test >dummy.txt
-   vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
-	--signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
-	--version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
-	--bootloader dummy.txt --pack u-boot.kpart
+   vbutil_kernel --arch arm \
+      --keyblock doc/chromium/files/devkeys/kernel.keyblock \
+      --signprivate doc/chromium/files/devkeys/kernel_data_key.vbprivk \
+      --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
+      --bootloader dummy.txt --pack u-boot.kpart
 
 
 5. See above
@@ -182,7 +200,7 @@ do this, login as root (via Ctrl-Alt-forward_arrow) and type
 'enable_dev_usb_boot'. You only need to do this once.
 
 Reboot the device with the SD card inserted. Press Clrl-U at the developer
-mode screen. It should show something like the following on the display:
+mode screen. It should show something like the following on the display::
 
    U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600)
 
@@ -203,18 +221,18 @@ None as yet.
 
 
 Other notes
-===========
+-----------
 
 flashrom
---------
+~~~~~~~~
 
-   Used to make a backup of your firmware, or to replace it.
+Used to make a backup of your firmware, or to replace it.
 
-   See: https://www.chromium.org/chromium-os/packages/cros-flashrom
+See: https://www.chromium.org/chromium-os/packages/cros-flashrom
 
 
 coreboot
---------
+~~~~~~~~
 
 Coreboot itself is not designed to actually boot an OS. Instead, a program
 called Depthcharge is used. This originally came out of U-Boot and was then
diff --git a/doc/chromium/chromebook_jerry.its b/doc/chromium/files/chromebook_jerry.its
index 7505a20..7505a20 100644
--- a/doc/chromium/chromebook_jerry.its
+++ b/doc/chromium/files/chromebook_jerry.its
diff --git a/doc/chromium/devkeys/kernel.keyblock b/doc/chromium/files/devkeys/kernel.keyblock
index 9740be4..9740be4 100644
--- a/doc/chromium/devkeys/kernel.keyblock
+++ b/doc/chromium/files/devkeys/kernel.keyblock
diff --git a/doc/chromium/devkeys/kernel_data_key.vbprivk b/doc/chromium/files/devkeys/kernel_data_key.vbprivk
index 8d392fb..8d392fb 100644
--- a/doc/chromium/devkeys/kernel_data_key.vbprivk
+++ b/doc/chromium/files/devkeys/kernel_data_key.vbprivk
diff --git a/doc/chromium/nyan-big.its b/doc/chromium/files/nyan-big.its
index bd41291..bd41291 100644
--- a/doc/chromium/nyan-big.its
+++ b/doc/chromium/files/nyan-big.its
diff --git a/doc/chromium/index.rst b/doc/chromium/index.rst
new file mode 100644
index 0000000..0722c25
--- /dev/null
+++ b/doc/chromium/index.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2020 Google LLC
+
+Chromium OS-specific doc
+========================
+
+This provides some information about Chromium OS and U-Boot.
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   run_vboot
+   chainload
diff --git a/doc/chromium/overview.rst b/doc/chromium/overview.rst
new file mode 100644
index 0000000..5498ed9
--- /dev/null
+++ b/doc/chromium/overview.rst
@@ -0,0 +1,74 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2020 Google LLC
+
+Chromium OS Support in U-Boot
+=============================
+
+Introduction
+------------
+
+This describes how to use U-Boot with Chromium OS. Several options are
+available:
+
+   - Running U-Boot from the 'altfw' feature, which is available on selected
+     Chromebooks from 2019 onwards (initially Grunt). Press '1' from the
+     developer-mode screen to get into U-Boot. See here for details:
+     https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_mode.md
+
+   - Running U-Boot from the disk partition. This involves signing U-Boot and
+     placing it on the disk, for booting as a 'kernel'. See
+     :doc:`chainload` for information on this. This is the only
+     option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat
+     more involved.
+
+   - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be
+     used instead of either or both of depthcharge (a bootloader which forked
+     from U-Boot in 2013) and coreboot. See :doc:`run_vboot` for more
+     information on this.
+
+   - Running U-Boot from coreboot. This allows U-Boot to run on more devices
+     since many of them only support coreboot as the bootloader and have
+     no bare-metal support in U-Boot. For this, use the 'coreboot' target.
+
+   - Running U-Boot and booting into a Chrome OS image, but without verified
+     boot. This can be useful for testing.
+
+
+Talks and documents
+-------------------
+
+Here is some material relevant to Chromium OS verified boot with U-Boot:
+
+   - "U-Boot with Chrome OS and firmware packaging"
+
+     - Author: Simon Glass
+     - Presented at Open Source Firmware Conference 2018, Erlangen
+     - Describes the work in progress as at the end of 2018
+     - Slides at `OSFC <https://2018.osfc.io/uploads/talk/paper/26/U-Boot_with_Chrome_OS_and_firmware_packaging.pdf>`_
+     - Video on `Youtube <https://www.youtube.com/watch?v=1jknxUvmwpo>`_
+
+   - "Verified Boot in Chrome OS and how to make it work for you"
+
+     - Author: Simon Glass
+     - Presented at ELCE 2013, Edinburgh
+     - Describes the original 2013 implementation as shipped on snow (first
+       `ARM Chromebook was a Samsung Chromebook <https://www.cnet.com/products/samsung-series-3-chromebook-xe303c12-11-6-exynos-5250-2-gb-ram-16-gb-ssd-bilingual-english-french/>`_
+       with Samsung Exynos5250 `review <https://www.cnet.com/reviews/samsung-chromebook-series-3-review/>`_),
+       spring (`HP Chromebook 11 <https://www.cnet.com/products/hp-chromebook-11-g2-11-6-exynos-5250-4-gb-ram-16-gb-emmc/>`_)
+       and pit/pi (`Samsung Chromebook 2 <https://www.cnet.com/products/samsung-chromebook-2-xe503c12-11-6-exynos-5-octa-4-gb-ram-16-gb-ssd/>`_
+       with Exynos 5 Octa 5420 in 2014).
+     - Slides at `Google research <https://research.google/pubs/pub42038/>`_
+     - Video at `Youtube <https://www.youtube.com/watch?v=kdpZC9jFzZA>`_
+
+   - "Chrome University 2018: Chrome OS Firmware and Verified Boot 201"
+
+     - Author: Duncan Laurie
+     - Describes Chrome OS firmware as of 2018 and includes a wide range of
+       topics. This has no U-Boot information, but does cover coreboot and also
+       talks about the Chrome OS EC and Security chip. This is probably the
+       best introduction talk.
+     - Video at `YouTube <https://www.youtube.com/watch?v=WY2sWpuda2g>`_
+
+   - `Chromium OS U-Boot <https://www.chromium.org/developers/u-boot>`_
+
+   - `Firmware porting Guide <https://www.chromium.org/chromium-os/firmware-porting-guide>`_
diff --git a/doc/README.chromium b/doc/chromium/run_vboot.rst
index 75f2f24..41b4f63 100644
--- a/doc/README.chromium
+++ b/doc/chromium/run_vboot.rst
@@ -1,42 +1,14 @@
-Chromium OS Support in U-Boot
-=============================
-
-Introduction
-------------
-
-This describes how to use U-Boot with Chromium OS. Several options are
-available:
-
-   - Running U-Boot from the 'altfw' feature, which is available on selected
-        Chromebooks from 2019 onwards (initially Grunt). Press '1' from the
-        developer-mode screen to get into U-Boot. See here for details:
-        https://sites.google.com/a/chromium.org/dev/chromium-os/poking-around-your-chrome-os-device?pli=1
-
-   - Running U-Boot from the disk partition. This involves signing U-Boot and
-        placing it on the disk, for booting as a 'kernel'. See
-        README.chromium-chainload for information on this. This is the only
-        option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat
-        more involved.
-
-   - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be
-        used instead of either or both of depthcharge (a bootloader which forked
-        from U-Boot in 2013) and coreboot. See below for more information on
-        this.
-
-   - Running U-Boot from coreboot. This allows U-Boot to run on more devices
-        since many of them only support coreboot as the bootloader and have
-        no bare-metal support in U-Boot. For this, use the 'coreboot' target.
-
-   - Running U-Boot and booting into a Chrome OS image, but without verified
-        boot. This can be useful for testing.
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2020 Google LLC
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
 
 
-U-Boot with Chromium OS verified boot
--------------------------------------
+Running U-Boot with Chromium OS verified boot
+=============================================
 
-To obtain:
+To obtain::
 
-   git clone https://github.com/sglass68/u-boot.git
+   git clone https://github.com/sjg20/u-boot.git
    cd u-boot
    git checkout cros-master
 
@@ -46,28 +18,35 @@ To obtain:
    git checkout 45964294
    #  futility: updater: Correct output version for Snow
 
-To build for sandbox:
+To build for sandbox::
 
    UB=/tmp/b/chromeos_sandbox    # U-Boot build directory
    cd u-boot
    make O=$UB chromeos_sandbox_defconfig
    make O=$UB -j20 -s VBOOT_SOURCE=/path/to/vboot_reference \
-	MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1
+     MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1
 
 Replace sandbox with another supported target.
 
 This produces $UB/image.bin which contains the firmware binaries in a SPI
 flash image.
 
-To run on sandbox:
+To run on sandbox::
 
+   CROS=~/cosarm
+   IMG=$CROS/src/build/images/coral/latest/chromiumos_image.bin
    $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out \
-	-L6 -c "host bind 0 $CROS/src/build/images/cheza/latest/chromiumos_image.bin; vboot go auto" \
-	-l -w -s state.dtb -r
+     -L6 -c "host bind 0 $IMG; vboot go auto" \
+     -l -w -s state.dtb -r -n -m $UB/ram
+
+   $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out -L6 -l \
+     -c "host bind 0 $IMG; vboot go auto" -w -s $UB/state.dtb -r -n -m $UB/mem
+
 
 To run on other boards:
-   Install image.bin in the SPI flash of your device
-   Boot your system
+
+   - Install image.bin in the SPI flash of your device
+   - Boot your system
 
 
 Sandbox
@@ -83,7 +62,7 @@ a device tree and binding a Chromium OS disk image for use to find kernels
 phases into state.dtb and will automatically ensure that memory is shared
 between all phases. TPL will jump to SPL and then on to U-Boot proper.
 
-It is possible to run with debugging on, e.g.
+It is possible to run with debugging on, e.g.::
 
    gdb --args $UB/tpl/u-boot-tpl -d ....
 
@@ -95,7 +74,7 @@ Samus
 -----
 
 Basic support is available for samus, using the chromeos_samus target. If you
-have an em100, use:
+have an em100, use::
 
    sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r
 
@@ -119,11 +98,20 @@ New uclasses
 
 Several uclasses are provided in cros/:
 
-	UCLASS_CROS_AUX_FW		Chrome OS auxiliary firmware
-	UCLASS_CROS_FWSTORE		Chrome OS firmware storage
-	UCLASS_CROS_NVDATA		Chrome OS non-volatile data device
-	UCLASS_CROS_VBOOT_EC		Chrome OS vboot EC operations
-	UCLASS_CROS_VBOOT_FLAG		Chrome OS verified boot flag
+UCLASS_CROS_AUX_FW
+   Chrome OS auxiliary firmware
+
+UCLASS_CROS_FWSTORE
+   Chrome OS firmware storage
+
+UCLASS_CROS_NVDATA
+   Chrome OS non-volatile data device
+
+UCLASS_CROS_VBOOT_EC
+   Chrome OS vboot EC operations
+
+UCLASS_CROS_VBOOT_FLAG
+   Chrome OS verified boot flag
 
 The existing UCLASS_CROS_EC is also used.
 
@@ -181,7 +169,7 @@ detect problems that affect the flow or particular vboot features.
 U-Boot without Chromium OS verified boot
 ----------------------------------------
 
-The following script can be used to boot a Chrome OS image on coral:
+The following script can be used to boot a Chrome OS image on coral::
 
    # Read the image header and obtain the address of the kernel
    # The offset 4f0 is defined by verified boot and may change for other
@@ -213,6 +201,4 @@ TO DO
 Get the full ACPI tables working with Coral
 
 
-Simon Glass
-sjg@chromium.org
 7 October 2018
diff --git a/doc/index.rst b/doc/index.rst
index f7aada9..02de1d4 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -87,6 +87,14 @@ Android-specific features available in U-Boot.
 
    android/index
 
+Chromium OS-specific doc
+------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   chromium/index
+
 Indices and tables
 ==================