1Chromium OS Support in U-Boot
2=============================
3
4Introduction
5------------
6
7This describes how to use U-Boot with Chromium OS. Several options are
8available:
9
10   - Running U-Boot from the 'altfw' feature, which is available on selected
11        Chromebooks from 2019 onwards (initially Grunt). Press '1' from the
12        developer-mode screen to get into U-Boot. See here for details:
13        https://sites.google.com/a/chromium.org/dev/chromium-os/poking-around-your-chrome-os-device?pli=1
14
15   - Running U-Boot from the disk partition. This involves signing U-Boot and
16        placing it on the disk, for booting as a 'kernel'. See
17        README.chromium-chainload for information on this. This is the only
18        option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat
19        more involved.
20
21   - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be
22        used instead of either or both of depthcharge (a bootloader which forked
23        from U-Boot in 2013) and coreboot. See below for more information on
24        this.
25
26   - Running U-Boot from coreboot. This allows U-Boot to run on more devices
27        since many of them only support coreboot as the bootloader and have
28        no bare-metal support in U-Boot. For this, use the 'coreboot' target.
29
30   - Running U-Boot and booting into a Chrome OS image, but without verified
31        boot. This can be useful for testing.
32
33
34U-Boot with Chromium OS verified boot
35-------------------------------------
36
37To obtain:
38
39   git clone https://github.com/sglass68/u-boot.git
40   cd u-boot
41   git checkout cros-master
42
43   cd ..
44   git clone https://chromium.googlesource.com/chromiumos/platform/vboot_reference
45   cd vboot_reference
46   git checkout 45964294
47   #  futility: updater: Correct output version for Snow
48
49To build for sandbox:
50
51   UB=/tmp/b/chromeos_sandbox    # U-Boot build directory
52   cd u-boot
53   make O=$UB chromeos_sandbox_defconfig
54   make O=$UB -j20 -s VBOOT_SOURCE=/path/to/vboot_reference \
55	MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1
56
57Replace sandbox with another supported target.
58
59This produces $UB/image.bin which contains the firmware binaries in a SPI
60flash image.
61
62To run on sandbox:
63
64   $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out \
65	-L6 -c "host bind 0 $CROS/src/build/images/cheza/latest/chromiumos_image.bin; vboot go auto" \
66	-l -w -s state.dtb -r
67
68To run on other boards:
69   Install image.bin in the SPI flash of your device
70   Boot your system
71
72
73Sandbox
74-------
75
76Most Chromium OS development with U-Boot is undertaken using sandbox. There is
77a sandbox target available (chromeos_sandbox) which allows running U-Boot on
78a Linux machine completion with emulations of the display, TPM, disk, etc.
79
80Running sandbox starts TPL, which contains the first phase of vboot, providing
81a device tree and binding a Chromium OS disk image for use to find kernels
82(any Chromium OS image will do). It also saves driver state between U-Boot
83phases into state.dtb and will automatically ensure that memory is shared
84between all phases. TPL will jump to SPL and then on to U-Boot proper.
85
86It is possible to run with debugging on, e.g.
87
88   gdb --args $UB/tpl/u-boot-tpl -d ....
89
90Breakpoints can be set in any U-Boot phase. Overall this is a good debugging
91environment for new verified-boot features.
92
93
94Samus
95-----
96
97Basic support is available for samus, using the chromeos_samus target. If you
98have an em100, use:
99
100   sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r
101
102to write the image and then boot samus (Power-Refresh).
103
104
105Boot flow
106---------
107
108Verified boot starts in TPL, which selects the A or B SPL, which in turn selects
109the A or B U-Boot. Then this jumps to the selected kernel. If anything goes
110wrong, the device reboots and the recovery SPL and U-Boot are used instead.
111
112More details are available here:
113
114   https://www.chromium.org/chromium-os/chromiumos-design-docs/firmware-boot-and-recovery
115
116
117New uclasses
118------------
119
120Several uclasses are provided in cros/:
121
122	UCLASS_CROS_AUX_FW		Chrome OS auxiliary firmware
123	UCLASS_CROS_FWSTORE		Chrome OS firmware storage
124	UCLASS_CROS_NVDATA		Chrome OS non-volatile data device
125	UCLASS_CROS_VBOOT_EC		Chrome OS vboot EC operations
126	UCLASS_CROS_VBOOT_FLAG		Chrome OS verified boot flag
127
128The existing UCLASS_CROS_EC is also used.
129
130
131Commands
132--------
133
134A new 'vboot' command is provided to run particular vboot stages. The most
135useful command is 'vboot go auto', which continues where the last stage left
136off.
137
138Note that TPL and SPL do not supports commands as yet, so the vboot code is
139called directly from the SPL boot devices (BOOT_DEVICE_CROS_VBOOT). See
140cros_load_image_tpl() and cros_load_image_spl() which both call
141vboot_run_auto().
142
143
144Config options
145--------------
146
147The main option is CONFIG_CHROMEOS, which enables a wide array of other options
148so that the required features are present.
149
150
151Device-tree config
152------------------
153
154Various options are available which control the operation of verified boot.
155See cros/dts/bindings/config.txt for details. Most config is handled at run-
156time, although build-time config (with Kconfig) could also be added fairly
157easily.
158
159
160Porting to other hardware
161-------------------------
162
163A basic port to samus (Chromebook Pixel 2015) is in a basic working state,
164using the chromeos_samus target. Patches will likely be forthcoming in early
1652019. Ports to an ARM board and coreboot (for x86 Chromebooks) are in the
166dreaming state.
167
168
169Tests
170-----
171
172Chromium OS firmware has a very limited set of tests. The tests that originally
173existed in U-Boot were not brought over to coreboot or depthcharge.
174
175The U-Boot tests ('make check') do operate, but at present there are no
176Chromium OS tests available. These will hopefully come together over time. Of
177course the above sandbox feature provides a sort of functional test and can
178detect problems that affect the flow or particular vboot features.
179
180
181U-Boot without Chromium OS verified boot
182----------------------------------------
183
184The following script can be used to boot a Chrome OS image on coral:
185
186   # Read the image header and obtain the address of the kernel
187   # The offset 4f0 is defined by verified boot and may change for other
188   # Chromebooks
189   read mmc 2:2 100000 0 80; setexpr loader *001004f0;
190
191   # Get the kernel size and calculate the number of blocks (0x200 bytes each)
192   setexpr size *00100518; setexpr blocks $size / 200;
193
194   # Read the full kernel and calculate the address of the setup block
195   read mmc 2:2 100000 80 $blocks; setexpr setup $loader - 1000;
196
197   # Locate the command line
198   setexpr cmdline $loader - 2000;
199
200   # Start the zboot process with the loaded kernel, setup block and cmdline
201   zboot start 100000 0 0 0 $setup $cmdline;
202
203   # Load the kernel, fix up the 'setup' block, dump information
204   zboot load; zboot setup; zboot dump
205
206   # Boot into Chrome OS
207   zboot go
208
209
210TO DO
211-----
212
213Get the full ACPI tables working with Coral
214
215
216Simon Glass
217sjg@chromium.org
2187 October 2018
219