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>
diff --git a/doc/README.chromium-chainload b/doc/chromium/chainload.rst
similarity index 78%
rename from doc/README.chromium-chainload
rename to 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 @@
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 @@
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 @@
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 @@
5. Write U-Boot to the SD card
+Steps::
+
sudo dd if=u-boot.kpart of=/dev/sdc1; sync
@@ -90,7 +103,7 @@
'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 @@
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 @@
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 @@
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 @@
'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 @@
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
similarity index 100%
rename from doc/chromium/chromebook_jerry.its
rename to doc/chromium/files/chromebook_jerry.its
diff --git a/doc/chromium/devkeys/kernel.keyblock b/doc/chromium/files/devkeys/kernel.keyblock
similarity index 100%
rename from doc/chromium/devkeys/kernel.keyblock
rename to doc/chromium/files/devkeys/kernel.keyblock
Binary files differ
diff --git a/doc/chromium/devkeys/kernel_data_key.vbprivk b/doc/chromium/files/devkeys/kernel_data_key.vbprivk
similarity index 100%
rename from doc/chromium/devkeys/kernel_data_key.vbprivk
rename to doc/chromium/files/devkeys/kernel_data_key.vbprivk
Binary files differ
diff --git a/doc/chromium/nyan-big.its b/doc/chromium/files/nyan-big.its
similarity index 100%
rename from doc/chromium/nyan-big.its
rename to 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
similarity index 67%
rename from doc/README.chromium
rename to 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,29 +18,36 @@
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 @@
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 @@
-----
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 @@
Several uclasses are provided in cros/:
+UCLASS_CROS_AUX_FW
+ Chrome OS auxiliary firmware
+
- 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_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 @@
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 @@
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/index
+Chromium OS-specific doc
+------------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ chromium/index
+
Indices and tables
==================