diff options
author | Simon Glass <sjg@chromium.org> | 2021-03-15 08:11:20 +0300 |
---|---|---|
committer | Simon Glass <sjg@chromium.org> | 2021-03-27 05:04:31 +0300 |
commit | 2d0423aff9fd9adc0933f94df6726e29ee2c89be (patch) | |
tree | 68970ad263f9e6686bcecd62a0613405c28ab225 /doc/chromium | |
parent | c197f6e27923b4cff9d782cd9be7a058d5d65aa2 (diff) | |
download | u-boot-2d0423aff9fd9adc0933f94df6726e29ee2c89be.tar.xz |
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>
Diffstat (limited to 'doc/chromium')
-rw-r--r-- | doc/chromium/chainload.rst | 257 | ||||
-rw-r--r-- | doc/chromium/files/chromebook_jerry.its (renamed from doc/chromium/chromebook_jerry.its) | 0 | ||||
-rw-r--r-- | doc/chromium/files/devkeys/kernel.keyblock (renamed from doc/chromium/devkeys/kernel.keyblock) | bin | 1208 -> 1208 bytes | |||
-rw-r--r-- | doc/chromium/files/devkeys/kernel_data_key.vbprivk (renamed from doc/chromium/devkeys/kernel_data_key.vbprivk) | bin | 1199 -> 1199 bytes | |||
-rw-r--r-- | doc/chromium/files/nyan-big.its (renamed from doc/chromium/nyan-big.its) | 0 | ||||
-rw-r--r-- | doc/chromium/index.rst | 14 | ||||
-rw-r--r-- | doc/chromium/overview.rst | 74 | ||||
-rw-r--r-- | doc/chromium/run_vboot.rst | 204 |
8 files changed, 549 insertions, 0 deletions
diff --git a/doc/chromium/chainload.rst b/doc/chromium/chainload.rst new file mode 100644 index 0000000000..7b6bb10d36 --- /dev/null +++ b/doc/chromium/chainload.rst @@ -0,0 +1,257 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020 Google LLC + +Running U-Boot from coreboot on Chromebooks +=========================================== + +U-Boot can be used as a secondary boot loader in a few situations such as from +UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on +ARM platforms to start up the machine. + +This document aims to provide a guide to booting U-Boot on a Chromebook. It +is only a starting point, and there are many guides on the interwebs. But +placing this information in the U-Boot tree should make it easier to find for +those who use U-Boot habitually. + +Most of these platforms are supported by U-Boot natively, but it is risky to +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:: + + sudo apt install gcc-arm-linux-gnueabi + mkdir b + make O=b/nyan_big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all + +You can obtain the vbutil_kernel utility here: + + https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U + + +Snow (Samsung ARM Chromebook) +----------------------------- + +See here: + +https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook + + +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 + +1. Build U-Boot + +Steps:: + + mkdir b + make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all + + +2. Select a .its file + +Select something from doc/chromium which matches your board, or create your +own. + +Note that the device tree node is required, even though it is not actually +used by U-Boot. This is because the Chromebook expects to pass it to the +kernel, and crashes if it is not present. + + +3. Build and sign an image + +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/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 + sudo cgpt add -b 32802 -s 2000000 -t rootfs $DISK + sudo gdisk $DISK # Enter command 'w' to write a protective MBR to the disk + + +5. Write U-Boot to the SD card + +Steps:: + + sudo dd if=u-boot.kpart of=/dev/sdc1; sync + + +6. Start it up + +Reboot the device in dev mode. Make sure that you have USB booting enabled. To +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:: + + U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600) + + Model: Acer Chromebook 13 CB5-311 + Board: Google/NVIDIA Nyan-big, ID: 1 + + Net: No ethernet found. + Hit any key to stop autoboot: 0 + Tegra124 (Nyan-big) # + + +7. Known problems + +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 + +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()). + + +9. Notes + +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:: + + hd u-boot-chromium.fit |head -20 + ... + 00000100 b8 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| + + hd b/nyan-big/u-boot.bin |head + 00000000 b8 00 00 ea 14 f0 9f e5 14 f0 9f e5 14 f0 9f e5 |................| + + +The 'data' property of the FIT is set up to start at offset 0x100 bytes into +the file. The change to CONFIG_SYS_TEXT_BASE is also an offset of 0x100 bytes +from the load address. If this changes, you either need to modify U-Boot to be +fully relocatable, or expect it to hang. + + +chromebook_jerry +---------------- + +The instruction are similar to those for Nyan with changes as noted below: + +1. Patch U-Boot + +Open include/configs/rk3288_common.h + +Change:: + + #define CONFIG_SYS_TEXT_BASE 0x00100000 + +to:: + + #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 + + +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 + echo test >dummy.txt + 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 + +6. See above + +7. Start it up + +Reboot the device in dev mode. Make sure that you have USB booting enabled. To +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:: + + U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600) + + Model: Google Jerry + Net: Net Initialization Skipped + No ethernet found. + Hit any key to stop autoboot: 0 + + +8. Known problems + +None as yet. + + +9. Notes + +None as yet. + + +Other notes +----------- + +flashrom +~~~~~~~~ + +Used to make a backup of your firmware, or to replace it. + +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 +heavily hacked and modified such that is is almost unrecognisable. It does +include a very small part of the U-Boot command-line interface but is not +usable as a general-purpose boot loader. + +In addition, it has a very unusual design in that it does not do device init +itself, but instead relies on coreboot. This is similar to (in U-Boot) having +a SPI driver with an empty probe() method, relying on whatever was set up +beforehand. It can be quite hard to figure out between these two code bases +what settings are actually used. When chain-loading into U-Boot we must be +careful to reinit anything that U-Boot expects. If not, some peripherals (or +the whole machine) may not work. This makes the process of chainloading more +complicated than it could be on some platforms. + +Finally, it supports only a subset of the U-Boot's FIT format. In particular +it uses a fixed address to load the FIT and does not support load/exec +addresses. This means that U-Boot must be able to boot from whatever +address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting +in Depthcharge). In practice this means that the data in the kernel@1 FIT node +(see above) must start at the same address as U-Boot's CONFIG_SYS_TEXT_BASE. diff --git a/doc/chromium/chromebook_jerry.its b/doc/chromium/files/chromebook_jerry.its index 7505a20535..7505a20535 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 Binary files differindex 9740be4e60..9740be4e60 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 Binary files differindex 8d392fb294..8d392fb294 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 bd412915e9..bd412915e9 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 0000000000..0722c25003 --- /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 0000000000..5498ed9c16 --- /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/chromium/run_vboot.rst b/doc/chromium/run_vboot.rst new file mode 100644 index 0000000000..41b4f63183 --- /dev/null +++ b/doc/chromium/run_vboot.rst @@ -0,0 +1,204 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2020 Google LLC +.. sectionauthor:: Simon Glass <sjg@chromium.org> + + +Running U-Boot with Chromium OS verified boot +============================================= + +To obtain:: + + git clone https://github.com/sjg20/u-boot.git + cd u-boot + git checkout cros-master + + cd .. + git clone https://chromium.googlesource.com/chromiumos/platform/vboot_reference + cd vboot_reference + git checkout 45964294 + # futility: updater: Correct output version for Snow + +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 + +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:: + + 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 $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 + + +Sandbox +------- + +Most Chromium OS development with U-Boot is undertaken using sandbox. There is +a sandbox target available (chromeos_sandbox) which allows running U-Boot on +a Linux machine completion with emulations of the display, TPM, disk, etc. + +Running sandbox starts TPL, which contains the first phase of vboot, providing +a device tree and binding a Chromium OS disk image for use to find kernels +(any Chromium OS image will do). It also saves driver state between U-Boot +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.:: + + gdb --args $UB/tpl/u-boot-tpl -d .... + +Breakpoints can be set in any U-Boot phase. Overall this is a good debugging +environment for new verified-boot features. + + +Samus +----- + +Basic support is available for samus, using the chromeos_samus target. If you +have an em100, use:: + + sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r + +to write the image and then boot samus (Power-Refresh). + + +Boot flow +--------- + +Verified boot starts in TPL, which selects the A or B SPL, which in turn selects +the A or B U-Boot. Then this jumps to the selected kernel. If anything goes +wrong, the device reboots and the recovery SPL and U-Boot are used instead. + +More details are available here: + + https://www.chromium.org/chromium-os/chromiumos-design-docs/firmware-boot-and-recovery + + +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 + +The existing UCLASS_CROS_EC is also used. + + +Commands +-------- + +A new 'vboot' command is provided to run particular vboot stages. The most +useful command is 'vboot go auto', which continues where the last stage left +off. + +Note that TPL and SPL do not supports commands as yet, so the vboot code is +called directly from the SPL boot devices (BOOT_DEVICE_CROS_VBOOT). See +cros_load_image_tpl() and cros_load_image_spl() which both call +vboot_run_auto(). + + +Config options +-------------- + +The main option is CONFIG_CHROMEOS, which enables a wide array of other options +so that the required features are present. + + +Device-tree config +------------------ + +Various options are available which control the operation of verified boot. +See cros/dts/bindings/config.txt for details. Most config is handled at run- +time, although build-time config (with Kconfig) could also be added fairly +easily. + + +Porting to other hardware +------------------------- + +A basic port to samus (Chromebook Pixel 2015) is in a basic working state, +using the chromeos_samus target. Patches will likely be forthcoming in early +2019. Ports to an ARM board and coreboot (for x86 Chromebooks) are in the +dreaming state. + + +Tests +----- + +Chromium OS firmware has a very limited set of tests. The tests that originally +existed in U-Boot were not brought over to coreboot or depthcharge. + +The U-Boot tests ('make check') do operate, but at present there are no +Chromium OS tests available. These will hopefully come together over time. Of +course the above sandbox feature provides a sort of functional test and can +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:: + + # Read the image header and obtain the address of the kernel + # The offset 4f0 is defined by verified boot and may change for other + # Chromebooks + read mmc 2:2 100000 0 80; setexpr loader *001004f0; + + # Get the kernel size and calculate the number of blocks (0x200 bytes each) + setexpr size *00100518; setexpr blocks $size / 200; + + # Read the full kernel and calculate the address of the setup block + read mmc 2:2 100000 80 $blocks; setexpr setup $loader - 1000; + + # Locate the command line + setexpr cmdline $loader - 2000; + + # Start the zboot process with the loaded kernel, setup block and cmdline + zboot start 100000 0 0 0 $setup $cmdline; + + # Load the kernel, fix up the 'setup' block, dump information + zboot load; zboot setup; zboot dump + + # Boot into Chrome OS + zboot go + + +TO DO +----- + +Get the full ACPI tables working with Coral + + +7 October 2018 |