summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/arch/sandbox.rst2
-rw-r--r--doc/board/google/chromebook_coral.rst234
-rw-r--r--doc/chromium/chainload.rst (renamed from doc/README.chromium-chainload)80
-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)bin1208 -> 1208 bytes
-rw-r--r--doc/chromium/files/devkeys/kernel_data_key.vbprivk (renamed from doc/chromium/devkeys/kernel_data_key.vbprivk)bin1199 -> 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.rst14
-rw-r--r--doc/chromium/overview.rst74
-rw-r--r--doc/chromium/run_vboot.rst (renamed from doc/README.chromium)90
-rw-r--r--doc/device-tree-bindings/sysinfo/google,coral.txt37
-rw-r--r--doc/index.rst8
-rw-r--r--doc/usage/index.rst1
-rw-r--r--doc/usage/x86/cbsysinfo.rst25
14 files changed, 465 insertions, 100 deletions
diff --git a/doc/arch/sandbox.rst b/doc/arch/sandbox.rst
index 8b18a22117..e052b6bdb0 100644
--- a/doc/arch/sandbox.rst
+++ b/doc/arch/sandbox.rst
@@ -389,6 +389,8 @@ the contents of the root directory on the second partion of the image
=>host bind 0 ./disk.raw
=>ls host 0:2
+The device can be marked removeable with 'host bind -r'.
+
A disk image can be created using the following commands::
$> truncate -s 1200M ./disk.raw
diff --git a/doc/board/google/chromebook_coral.rst b/doc/board/google/chromebook_coral.rst
index c39f1e310c..4b585678dc 100644
--- a/doc/board/google/chromebook_coral.rst
+++ b/doc/board/google/chromebook_coral.rst
@@ -16,6 +16,169 @@ Note that booting U-Boot on APL is already supported by coreboot and
Slim Bootloader. This documentation refers to a 'bare metal' port.
+Building
+--------
+
+First, you need the following binary blobs:
+
+ * descriptor.bin - Intel flash descriptor
+ * fitimage.bin - Base flash image structure
+ * fsp_m.bin - FSP-M, for setting up SDRAM
+ * fsp_s.bin - FSP-S, for setting up Silicon
+ * vbt.bin - for setting up display
+
+These binaries do not seem to be available publicly. If you have a ROM image,
+such as santa.bin then you can do this::
+
+ cbfstool santa.bin extract -n fspm.bin -f fsp-m.bin
+ cbfstool santa.bin extract -n fsps.bin -f fsp-s.bin
+ cbfstool santa.bin extract -n vbt-santa.bin -f vbt.bin
+ mkdir tmp
+ cd tmp
+ dump_fmap -x ../santa.bin
+ mv SI_DESC ../descriptor.bin
+ mv IFWI ../fitimage.bin
+
+Put all of these files in `board/google/chromebook_coral` so they can be found
+by the build.
+
+To build::
+
+ make O=/tmp/b/chromebook_coral chromebook_coral_defconfig
+ make O=/tmp/b/chromebook_coral -s -j30 all
+
+That should produce `/tmp/b/chrombook_coral/u-boot.rom` which you can use with
+a Dediprog em100::
+
+ em100 -s -c w25q128fw -d /tmp/b/chromebook_coral/u-boot.rom -r
+
+or you can use flashrom to write it to the board. If you do that, make sure you
+have a way to restore the old ROM without booting the board. Otherwise you may
+brick it. Having said that, you may find these instructions useful if you want
+to unbrick your device:
+
+ https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging.md
+
+You can buy Suzy-Q from Sparkfun:
+
+ https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/main/docs/ccd.md#suzyq-suzyqable
+
+Note that it will hang at the SPL prompt for 21 seconds. When booting into
+Chrome OS it will always select developer mode, so will wipe anything you have
+on the device if you let it proceed. You have two seconds in U-Boot to stop the
+auto-boot prompt and several seconds at the 'developer wipe' screen to stop it
+wiping the disk.
+
+Here is the console output::
+
+ U-Boot TPL 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700)
+ Trying to boot from Mapped SPI
+
+ U-Boot SPL 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700)
+ Trying to boot from Mapped SPI
+
+
+ U-Boot 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700)
+
+ CPU: Intel(R) Celeron(R) CPU N3450 @ 1.10GHz
+ DRAM: 3.9 GiB
+ MMC: sdmmc@1b,0: 1, emmc@1c,0: 2
+ Video: 1024x768x32 @ b0000000
+ Model: Google Coral
+ Net: No ethernet found.
+ SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB
+ Hit any key to stop autoboot: 0
+ cmdline=console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=${uuid}/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=${uuid} add_efi_memmap boot=local noresume noswap i915.modeset=1 Kernel command line: "console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off "
+ Setup located at 00090000:
+
+ ACPI RSDP addr : 7991f000
+ E820: 14 entries
+ Addr Size Type
+ d0000000 1000000 <NULL>
+ 0 a0000 RAM
+ a0000 60000 Reserved
+ 7b000000 800000 Reserved
+ 7b800000 4800000 Reserved
+ 7ac00000 400000 Reserved
+ 100000 ff00000 RAM
+ 10000000 2151000 Reserved
+ 12151000 68aaf000 RAM
+ 100000000 80000000 RAM
+ e0000000 10000000 Reserved
+ 7991bfd0 12e4030 Reserved
+ d0000000 10000000 Reserved
+ fed10000 8000 Reserved
+ Setup sectors : 1e
+ Root flags : 1
+ Sys size : 63420
+ RAM size : 0
+ Video mode : ffff
+ Root dev : 0
+ Boot flag : 0
+ Jump : 66eb
+ Header : 53726448
+ Kernel V2
+ Version : 20d
+ Real mode switch : 0
+ Start sys : 1000
+ Kernel version : 38cc
+ @00003acc:
+ Type of loader : 80
+ U-Boot, version 0
+ Load flags : 81
+ : loaded-high can-use-heap
+ Setup move size : 8000
+ Code32 start : 100000
+ Ramdisk image : 0
+ Ramdisk size : 0
+ Bootsect kludge : 0
+ Heap end ptr : 8e00
+ Ext loader ver : 0
+ Ext loader type : 0
+ Command line ptr : 99000
+ console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off
+ Initrd addr max : 7fffffff
+ Kernel alignment : 200000
+ Relocatable kernel : 1
+ Min alignment : 15
+ : 200000
+ Xload flags : 3
+ : 64-bit-entry can-load-above-4gb
+ Cmdline size : 7ff
+ Hardware subarch : 0
+ HW subarch data : 0
+ Payload offset : 26e
+ Payload length : 612045
+ Setup data : 0
+ Pref address : 1000000
+ Init size : 1383000
+ Handover offset : 0
+
+ Starting kernel ...
+
+ Timer summary in microseconds (17 records):
+ Mark Elapsed Stage
+ 0 0 reset
+ 155,279 155,279 TPL
+ 237,088 81,809 end phase
+ 237,533 445 SPL
+ 816,456 578,923 end phase
+ 817,357 901 board_init_f
+ 1,061,751 244,394 board_init_r
+ 1,402,435 340,684 id=64
+ 1,430,071 27,636 main_loop
+ 5,532,057 4,101,986 start_kernel
+
+ Accumulated time:
+ 685 dm_r
+ 2,817 fast_spi
+ 33,095 dm_spl
+ 52,468 dm_f
+ 208,242 fsp-m
+ 242,221 fsp-s
+ 332,710 mmap_spi
+
+
Boot flow - TPL
---------------
@@ -181,7 +344,7 @@ Partial memory map
ff000000 Bottom of ROM
fefc0000 Top of CAR region
fef96000 Stack for FSP-M
- fef40000 59000 FSP-M
+ fef40000 59000 FSP-M (also VPL loads here)
fef11000 SPL loaded here
fef10000 CONFIG_BLOBLIST_ADDR
fef10000 Stack top in TPL, SPL and U-Boot before relocation
@@ -195,35 +358,72 @@ Partial memory map
1110000 CONFIG_SYS_TEXT_BASE
+Speeding up SPL for development
+-------------------------------
+
+The 21-second wait for memory training is annoying during development, since
+every new image incurs this cost when booting. There is no cache to fall back on
+since that area of the image is empty on start-up.
+
+You can add suitable cache contents to the image to fix this, for development
+purposes only, like this::
+
+ # Read the image back after booting through SPL
+ em100 -s -c w25q128fw -u image.bin
+
+ # Extract the two cache regions
+ binman extract -i image.bin extra *cache
+
+ # Move them into the source directory
+ mv *cache board/google/chromebook_coral
+
+Then add something like this to the devicetree::
+
+ #if IS_ENABLED(CONFIG_HAVE_MRC) || IS_ENABLED(CONFIG_FSP_VERSION2)
+ /* Provide initial contents of the MRC data for faster development */
+ rw-mrc-cache {
+ type = "blob";
+ /* Mirror the offset in spi-flash@0 */
+ offset = <0xff8e0000>;
+ size = <0x10000>;
+ filename = "board/google/chromebook_coral/rw-mrc-cache";
+ };
+ rw-var-mrc-cache {
+ type = "blob";
+ size = <0x1000>;
+ filename = "board/google/chromebook_coral/rw-var-mrc-cache";
+ };
+ #endif
+
+This tells binman to put the cache contents in the same place as the
+`rw-mrc-cache` and `rw-var-mrc-cache` regions defined by the SPI-flash driver.
+
+
Supported peripherals
---------------------
-- UART
-- SPI flash
-- Video
-- MMC (dev 0) and micro-SD (dev 1)
-- Chrome OS EC
-- Keyboard
-- USB
+The following have U-Boot drivers:
+
+ - UART
+ - SPI flash
+ - Video
+ - MMC (dev 0) and micro-SD (dev 1)
+ - Chrome OS EC
+ - Cr50 (security chip)
+ - Keyboard
+ - USB
To do
-----
- Finish peripherals
- - left-side USB
- - USB-C
- - Cr50 (security chip: a basic driver is running but not included here)
- Sound (Intel I2S support exists, but need da7219 driver)
- - Various minor features supported by LPC, etc.
-- Booting Chrome OS, e.g. with verified boot
-- Integrate with Chrome OS vboot
-- Improvements to booting from coreboot (i.e. as a coreboot target)
- Use FSP-T binary instead of our own CAR implementation
- Use the official FSP package instead of the coreboot one
-- Enable all CPU cores
- Suspend / resume
-- ACPI
+- Fix MMC which seems to try to read even though the card is empty
+- Fix USB3 crash "WARN halted endpoint, queueing URB anyway."
Credits
diff --git a/doc/README.chromium-chainload b/doc/chromium/chainload.rst
index 45eaeced2d..7b6bb10d36 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 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
index 9740be4e60..9740be4e60 100644
--- a/doc/chromium/devkeys/kernel.keyblock
+++ b/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
index 8d392fb294..8d392fb294 100644
--- a/doc/chromium/devkeys/kernel_data_key.vbprivk
+++ b/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
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/README.chromium b/doc/chromium/run_vboot.rst
index 75f2f24042..41b4f63183 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/device-tree-bindings/sysinfo/google,coral.txt b/doc/device-tree-bindings/sysinfo/google,coral.txt
new file mode 100644
index 0000000000..d8a1a79687
--- /dev/null
+++ b/doc/device-tree-bindings/sysinfo/google,coral.txt
@@ -0,0 +1,37 @@
+Google Coral sysinfo information
+================================
+
+This binding allows information about the board to be described. It includes
+the SMBIOS binding as well.
+
+Required properties:
+
+ - compatible: "google,coral"
+ - recovery-gpios: GPIO to use for recovery button (-1 if none)
+ - wite-protect-gpios: GPIO to use for write-protect screw
+ - phase-enforce-gpios: GPIO to indicate the board is in final ship mode
+ - memconfig-gpios: 4 GPIOs to use to read memory config (as base2 int)
+
+Optional properties:
+ - skuconfig-gpios: 2 GPIOs to use to read SKU ID. If not present, the
+ Chromium OS EC SKU_ID is used instead
+
+Example:
+
+board: board {
+ compatible = "google,coral";
+ recovery-gpios = <&gpio_nw (-1) GPIO_ACTIVE_LOW>;
+ write-protect-gpios = <&gpio_nw GPIO_75 GPIO_ACTIVE_HIGH>;
+ phase-enforce-gpios = <&gpio_n GPIO_10 GPIO_ACTIVE_HIGH>;
+ memconfig-gpios = <&gpio_nw GPIO_101 GPIO_ACTIVE_HIGH
+ &gpio_nw GPIO_102 GPIO_ACTIVE_HIGH
+ &gpio_n GPIO_38 GPIO_ACTIVE_HIGH
+ &gpio_n GPIO_45 GPIO_ACTIVE_HIGH>;
+
+ /*
+ * This is used for reef only:
+ *
+ * skuconfig-gpios = <&gpio_nw GPIO_16 GPIO_ACTIVE_HIGH
+ * &gpio_nw GPIO_17 GPIO_ACTIVE_HIGH>;
+ */
+ };
diff --git a/doc/index.rst b/doc/index.rst
index f7aada966b..02de1d4684 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
==================
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 35c515f8b5..fb834349ca 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -21,6 +21,7 @@ Shell commands
booti
bootmenu
button
+ x86/cbsysinfo
conitrace
echo
exception
diff --git a/doc/usage/x86/cbsysinfo.rst b/doc/usage/x86/cbsysinfo.rst
new file mode 100644
index 0000000000..8c03a85169
--- /dev/null
+++ b/doc/usage/x86/cbsysinfo.rst
@@ -0,0 +1,25 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+cbsysinfo
+=========
+
+Synopis
+-------
+
+::
+
+ cbsysinfo
+
+
+Description
+-----------
+
+This displays information obtained from the coreboot sysinfo table. It is only
+useful when booting U-Boot from coreboot.
+
+Example
+-------
+
+::
+
+ => cbsysinfo
View Lorry Controller Status