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 ---
.../chainload.rst} | 80 ++++++++++------ doc/chromium/{ => files}/chromebook_jerry.its | 0 .../{ => files}/devkeys/kernel.keyblock | Bin .../devkeys/kernel_data_key.vbprivk | Bin doc/chromium/{ => files}/nyan-big.its | 0 doc/chromium/index.rst | 14 +++ doc/chromium/overview.rst | 74 ++++++++++++++ .../run_vboot.rst} | 90 ++++++++---------- doc/index.rst | 8 ++ 9 files changed, 183 insertions(+), 83 deletions(-) rename doc/{README.chromium-chainload => chromium/chainload.rst} (79%) rename doc/chromium/{ => files}/chromebook_jerry.its (100%) rename doc/chromium/{ => files}/devkeys/kernel.keyblock (100%) rename doc/chromium/{ => files}/devkeys/kernel_data_key.vbprivk (100%) rename doc/chromium/{ => files}/nyan-big.its (100%) create mode 100644 doc/chromium/index.rst create mode 100644 doc/chromium/overview.rst rename doc/{README.chromium => chromium/run_vboot.rst} (68%)
diff --git a/doc/README.chromium-chainload b/doc/chromium/chainload.rst similarity index 79% rename from doc/README.chromium-chainload rename to doc/chromium/chainload.rst index 45eaeced2da..7b6bb10d36d 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-... 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... +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...
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 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 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 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 00000000000..0722c250033 --- /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 00000000000..5498ed9c16c --- /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 68% rename from doc/README.chromium rename to doc/chromium/run_vboot.rst index 75f2f24042c..41b4f631835 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-c... - - - 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 4c44955d67f..ce91a2a41ef 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -110,6 +110,14 @@ Android-specific features available in U-Boot.
android/index
+Chromium OS-specific doc +------------------------ + +.. toctree:: + :maxdepth: 2 + + chromium/index + Indices and tables ==================