xref: /openbmc/u-boot/doc/README.chromium (revision c66f5620)
1Running U-Boot from coreboot on Chromebooks
2===========================================
3
4U-Boot can be used as a secondary boot loader in a few situations such as from
5UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on
6ARM platforms to start up the machine.
7
8This document aims to provide a guide to booting U-Boot on a Chromebook. It
9is only a starting point, and there are many guides on the interwebs. But
10placing this information in the U-Boot tree should make it easier to find for
11those who use U-Boot habitually.
12
13Most of these platforms are supported by U-Boot natively, but it is risky to
14replace the ROM unless you have a servo board and cable to restore it with.
15
16
17For all of these the standard U-Boot build instructions apply. For example on
18ARM:
19
20   sudo apt install gcc-arm-linux-gnueabi
21   mkdir b
22   make O=b/nyan_big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all
23
24You can obtain the vbutil_kernel utility here:
25
26   https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U
27
28
29Snow (Samsung ARM Chromebook)
30-----------------------------
31
32See here:
33
34https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook
35
36
37Nyan-big
38--------
39
40Compiled based on information here:
41https://lists.denx.de/pipermail/u-boot/2015-March/209530.html
42https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big
43https://lists.denx.de/pipermail/u-boot/2017-May/289491.html
44https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card
45
461. Patch U-Boot
47
48Open include/configs/tegra124-common.h
49
50Change:
51
52#define CONFIG_SYS_TEXT_BASE	0x80110000
53
54to:
55
56#define CONFIG_SYS_TEXT_BASE	0x81000100
57
58
592. Build U-Boot
60
61   mkdir b
62   make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all
63
64
653. Select a .its file
66
67Select something from doc/chromium which matches your board, or create your
68own.
69
70Note that the device tree node is required, even though it is not actually
71used by U-Boot. This is because the Chromebook expects to pass it to the
72kernel, and crashes if it is not present.
73
74
754. Build and sign an image
76
77   ./b/nyan-big/tools/mkimage -f doc/chromium/nyan-big.its u-boot-chromium.fit
78   echo test >dummy.txt
79   vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
80	--signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
81	--version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
82	--bootloader dummy.txt --pack u-boot.kpart
83
84
855. Prepare an SD card
86
87   DISK=/dev/sdc   # Replace with your actual SD card device
88   sudo cgpt create $DISK
89   sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK
90   sudo cgpt add -b 32802 -s 2000000 -t rootfs $DISK
91   sudo gdisk $DISK   # Enter command 'w' to write a protective MBR to the disk
92
93
946. Write U-Boot to the SD card
95
96   sudo dd if=u-boot.kpart of=/dev/sdc1; sync
97
98
997. Start it up
100
101Reboot the device in dev mode. Make sure that you have USB booting enabled. To
102do this, login as root (via Ctrl-Alt-forward_arrow) and type
103'enable_dev_usb_boot'. You only need to do this once.
104
105Reboot the device with the SD card inserted. Press Clrl-U at the developer
106mode screen. It should show something like the following on the display:
107
108   U-Boot 2017.07-00637-g242eb42-dirty (May 22 2017 - 06:14:21 -0600)
109
110   Model: Acer Chromebook 13 CB5-311
111   Board: Google/NVIDIA Nyan-big, ID: 1
112
113   Net:   No ethernet found.
114   Hit any key to stop autoboot:  0
115   Tegra124 (Nyan-big) #
116
117
1188. Known problems
119
120On the serial console the word MMC is chopped at the start of the line:
121
122C:   sdhci@700b0000: 2, sdhci@700b0400: 1, sdhci@700b0600: 0
123
124This is likely due to some problem with change-over of the serial driver
125during relocation (or perhaps updating the clock setup in board_init()).
126
127
1289. Notes
129
130To check that you copied the u-boot.its file correctly, use these commands.
131You should see that the data at 0x100 in u-boot-chromium.fit is the first few
132bytes of U-Boot:
133
134   hd u-boot-chromium.fit |head -20
135   ...
136   00000100  b8 00 00 ea 14 f0 9f e5  14 f0 9f e5 14 f0 9f e5  |................|
137
138   hd b/nyan-big/u-boot.bin |head
139   00000000  b8 00 00 ea 14 f0 9f e5  14 f0 9f e5 14 f0 9f e5  |................|
140
141
142The 'data' property of the FIT is set up to start at offset 0x100 bytes into
143the file. The change to CONFIG_SYS_TEXT_BASE is also an offset of 0x100 bytes
144from the load address. If this changes, you either need to modify U-Boot to be
145fully relocatable, or expect it to hang.
146
147
148chromebook_jerry
149----------------
150
151The instruction are similar to those for Nyan with changes as noted below:
152
1531. Patch U-Boot
154
155Open include/configs/rk3288_common.h
156
157Change:
158
159#define CONFIG_SYS_TEXT_BASE		0x00100000
160
161to:
162
163#define CONFIG_SYS_TEXT_BASE		0x02000100
164
165
166
1672. Build U-Boot
168
169   mkdir b
170   make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \
171	chromebook_jerry_defconfig all
172
173
1743. See above
175
1764. Build and sign an image
177
178   ./b/chromebook_jerry/tools/mkimage -f doc/chromium/chromebook_jerry.its \
179	u-boot-chromium.fit
180   echo test >dummy.txt
181   vbutil_kernel --arch arm --keyblock doc/chromium/devkeys/kernel.keyblock \
182	--signprivate doc/chromium/devkeys/kernel_data_key.vbprivk \
183	--version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \
184	--bootloader dummy.txt --pack u-boot.kpart
185
186
1875. See above
188
1896. See above
190
1917. Start it up
192
193Reboot the device in dev mode. Make sure that you have USB booting enabled. To
194do this, login as root (via Ctrl-Alt-forward_arrow) and type
195'enable_dev_usb_boot'. You only need to do this once.
196
197Reboot the device with the SD card inserted. Press Clrl-U at the developer
198mode screen. It should show something like the following on the display:
199
200   U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600)
201
202   Model: Google Jerry
203   Net:   Net Initialization Skipped
204   No ethernet found.
205   Hit any key to stop autoboot:  0
206
207
2088. Known problems
209
210None as yet.
211
212
2139. Notes
214
215None as yet.
216
217
218Other notes
219===========
220
221flashrom
222--------
223
224   Used to make a backup of your firmware, or to replace it.
225
226   See: https://www.chromium.org/chromium-os/packages/cros-flashrom
227
228
229coreboot
230--------
231
232Coreboot itself is not designed to actually boot an OS. Instead, a program
233called Depthcharge is used. This originally came out of U-Boot and was then
234heavily hacked and modified such that is is almost unrecognisable. It does
235include a very small part of the U-Boot command-line interface but is not
236usable as a general-purpose boot loader.
237
238In addition, it has a very unusual design in that it does not do device init
239itself, but instead relies on coreboot. This is similar to (in U-Boot) having
240a SPI driver with an empty probe() method, relying on whatever was set up
241beforehand. It can be quite hard to figure out between these two code bases
242what settings are actually used. When chain-loading into U-Boot we must be
243careful to reinit anything that U-Boot expects. If not, some peripherals (or
244the whole machine) may not work. This makes the process of chainloading more
245complicated than it could be on some platforms.
246
247Finally, it supports only a subset of the U-Boot's FIT format. In particular
248it uses a fixed address to load the FIT and does not support load/exec
249addresses. This means that U-Boot must be able to boot from whatever
250address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting
251in Depthcharge). In practice this means that the data in the kernel@1 FIT node
252(see above) must start at the same address as U-Boot's CONFIG_SYS_TEXT_BASE.
253