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>
This commit is contained in:
Simon Glass
parent
c197f6e279
commit
2d0423aff9
@ -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
|
||||
14
doc/chromium/index.rst
Normal file
14
doc/chromium/index.rst
Normal file
@ -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
|
||||
74
doc/chromium/overview.rst
Normal file
74
doc/chromium/overview.rst
Normal file
@ -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>`_
|
||||
@ -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
|
||||
@ -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
|
||||
==================
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user