1.. SPDX-License-Identifier: GPL-2.0+ 2.. Copyright 2020 Google LLC 3 4Running U-Boot from coreboot on Chromebooks 5=========================================== 6 7U-Boot can be used as a secondary boot loader in a few situations such as from 8UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on 9ARM platforms to start up the machine. 10 11This document aims to provide a guide to booting U-Boot on a Chromebook. It 12is only a starting point, and there are many guides on the interwebs. But 13placing this information in the U-Boot tree should make it easier to find for 14those who use U-Boot habitually. 15 16Most of these platforms are supported by U-Boot natively, but it is risky to 17replace the ROM unless you have a servo board and cable to restore it with. 18 19 20For all of these the standard U-Boot build instructions apply. For example on 21ARM:: 22 23 sudo apt install gcc-arm-linux-gnueabi 24 mkdir b 25 make O=b/nyan_big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all 26 27You can obtain the vbutil_kernel utility here: 28 29 https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U 30 31 32Snow (Samsung ARM Chromebook) 33----------------------------- 34 35See here: 36 37https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook 38 39 40Nyan-big 41-------- 42 43Compiled based on information here:: 44 45 https://lists.denx.de/pipermail/u-boot/2015-March/209530.html 46 https://git.collabora.com/cgit/user/tomeu/u-boot.git/commit/?h=nyan-big 47 https://lists.denx.de/pipermail/u-boot/2017-May/289491.html 48 https://github.com/chromeos-nvidia-androidtv/gnu-linux-on-acer-chromebook-13#copy-data-to-the-sd-card 49 501. Build U-Boot 51 52Steps:: 53 54 mkdir b 55 make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all 56 57 582. Select a .its file 59 60Select something from doc/chromium which matches your board, or create your 61own. 62 63Note that the device tree node is required, even though it is not actually 64used by U-Boot. This is because the Chromebook expects to pass it to the 65kernel, and crashes if it is not present. 66 67 683. Build and sign an image 69 70Steps:: 71 72 ./b/nyan-big/tools/mkimage -f doc/chromium/files/nyan-big.its u-boot-chromium.fit 73 echo test >dummy.txt 74 vbutil_kernel --arch arm \ 75 --keyblock doc/chromium/files/devkeys/kernel.keyblock \ 76 --signprivate doc/chromium/files/devkeys/kernel_data_key.vbprivk \ 77 --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \ 78 --bootloader dummy.txt --pack u-boot.kpart 79 80 814. Prepare an SD card 82 83Steps:: 84 85 DISK=/dev/sdc # Replace with your actual SD card device 86 sudo cgpt create $DISK 87 sudo cgpt add -b 34 -s 32768 -P 1 -S 1 -t kernel $DISK 88 sudo cgpt add -b 32802 -s 2000000 -t rootfs $DISK 89 sudo gdisk $DISK # Enter command 'w' to write a protective MBR to the disk 90 91 925. Write U-Boot to the SD card 93 94Steps:: 95 96 sudo dd if=u-boot.kpart of=/dev/sdc1; sync 97 98 996. 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 1187. Known problems 119 120On the serial console the word MMC is chopped at the start of the line:: 121 122 C: 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 169Steps:: 170 171 mkdir b 172 make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \ 173 chromebook_jerry_defconfig all 174 175 1763. See above 177 1784. Build and sign an image 179 180Steps:: 181 182 ./b/chromebook_jerry/tools/mkimage -f doc/chromium/chromebook_jerry.its \ 183 u-boot-chromium.fit 184 echo test >dummy.txt 185 vbutil_kernel --arch arm \ 186 --keyblock doc/chromium/files/devkeys/kernel.keyblock \ 187 --signprivate doc/chromium/files/devkeys/kernel_data_key.vbprivk \ 188 --version 1 --config dummy.txt --vmlinuz u-boot-chromium.fit \ 189 --bootloader dummy.txt --pack u-boot.kpart 190 191 1925. See above 193 1946. See above 195 1967. Start it up 197 198Reboot the device in dev mode. Make sure that you have USB booting enabled. To 199do this, login as root (via Ctrl-Alt-forward_arrow) and type 200'enable_dev_usb_boot'. You only need to do this once. 201 202Reboot the device with the SD card inserted. Press Clrl-U at the developer 203mode screen. It should show something like the following on the display:: 204 205 U-Boot 2017.05-00649-g72acdbf-dirty (May 29 2017 - 14:57:05 -0600) 206 207 Model: Google Jerry 208 Net: Net Initialization Skipped 209 No ethernet found. 210 Hit any key to stop autoboot: 0 211 212 2138. Known problems 214 215None as yet. 216 217 2189. Notes 219 220None as yet. 221 222 223Other notes 224----------- 225 226flashrom 227~~~~~~~~ 228 229Used to make a backup of your firmware, or to replace it. 230 231See: https://www.chromium.org/chromium-os/packages/cros-flashrom 232 233 234coreboot 235~~~~~~~~ 236 237Coreboot itself is not designed to actually boot an OS. Instead, a program 238called Depthcharge is used. This originally came out of U-Boot and was then 239heavily hacked and modified such that is is almost unrecognisable. It does 240include a very small part of the U-Boot command-line interface but is not 241usable as a general-purpose boot loader. 242 243In addition, it has a very unusual design in that it does not do device init 244itself, but instead relies on coreboot. This is similar to (in U-Boot) having 245a SPI driver with an empty probe() method, relying on whatever was set up 246beforehand. It can be quite hard to figure out between these two code bases 247what settings are actually used. When chain-loading into U-Boot we must be 248careful to reinit anything that U-Boot expects. If not, some peripherals (or 249the whole machine) may not work. This makes the process of chainloading more 250complicated than it could be on some platforms. 251 252Finally, it supports only a subset of the U-Boot's FIT format. In particular 253it uses a fixed address to load the FIT and does not support load/exec 254addresses. This means that U-Boot must be able to boot from whatever 255address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting 256in Depthcharge). In practice this means that the data in the kernel@1 FIT node 257(see above) must start at the same address as U-Boot's CONFIG_SYS_TEXT_BASE. 258