doc/chromium/chainload.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. Copyright 2020 Google LLC
   3
   4 Running U-Boot from coreboot on Chromebooks
   5 ===========================================
   6
   7 U-Boot can be used as a secondary boot loader in a few situations such as from
   8 UEFI and coreboot (see README.x86). Recent Chromebooks use coreboot even on
   9 ARM platforms to start up the machine.
  10
  11 This document aims to provide a guide to booting U-Boot on a Chromebook. It
  12 is only a starting point, and there are many guides on the interwebs. But
  13 placing this information in the U-Boot tree should make it easier to find for
  14 those who use U-Boot habitually.
  15
  16 Most of these platforms are supported by U-Boot natively, but it is risky to
  17 replace the ROM unless you have a servo board and cable to restore it with.
  18
  19
  20 For all of these the standard U-Boot build instructions apply. For example on
  21 ARM::
  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
  27 You can obtain the vbutil_kernel utility here:
  28
  29    https://drive.google.com/open?id=0B7WYZbZ9zd-3dHlVVXo4VXE2T0U
  30
  31
  32 Snow (Samsung ARM Chromebook)
  33 -----------------------------
  34
  35 See here:
  36
  37 https://www.chromium.org/chromium-os/firmware-porting-guide/using-nv-u-boot-on-the-samsung-arm-chromebook
  38
  39
  40 Nyan-big
  41 --------
  42
  43 Compiled 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
  50 1. Build U-Boot
  51
  52 Steps::
  53
  54    mkdir b
  55    make -j8 O=b/nyan-big CROSS_COMPILE=arm-linux-gnueabi- nyan-big_defconfig all
  56
  57
  58 2. Select a .its file
  59
  60 Select something from doc/chromium which matches your board, or create your
  61 own.
  62
  63 Note that the device tree node is required, even though it is not actually
  64 used by U-Boot. This is because the Chromebook expects to pass it to the
  65 kernel, and crashes if it is not present.
  66
  67
  68 3. Build and sign an image
  69
  70 Steps::
  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
  81 4. Prepare an SD card
  82
  83 Steps::
  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
  92 5. Write U-Boot to the SD card
  93
  94 Steps::
  95
  96    sudo dd if=u-boot.kpart of=/dev/sdc1; sync
  97
  98
  99 6. Start it up
 100
 101 Reboot the device in dev mode. Make sure that you have USB booting enabled. To
 102 do this, login as root (via Ctrl-Alt-forward_arrow) and type
 103 'enable_dev_usb_boot'. You only need to do this once.
 104
 105 Reboot the device with the SD card inserted. Press Clrl-U at the developer
 106 mode 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
 118 7. Known problems
 119
 120 On 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
 124 This is likely due to some problem with change-over of the serial driver
 125 during relocation (or perhaps updating the clock setup in board_init()).
 126
 127
 128 9. Notes
 129
 130 To check that you copied the u-boot.its file correctly, use these commands.
 131 You should see that the data at 0x100 in u-boot-chromium.fit is the first few
 132 bytes 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
 142 The 'data' property of the FIT is set up to start at offset 0x100 bytes into
 143 the file. The change to CONFIG_SYS_TEXT_BASE is also an offset of 0x100 bytes
 144 from the load address. If this changes, you either need to modify U-Boot to be
 145 fully relocatable, or expect it to hang.
 146
 147
 148 chromebook_jerry
 149 ----------------
 150
 151 The instruction are similar to those for Nyan with changes as noted below:
 152
 153 1. Patch U-Boot
 154
 155 Open include/configs/rk3288_common.h
 156
 157 Change::
 158
 159    #define CONFIG_SYS_TEXT_BASE         0x00100000
 160
 161 to::
 162
 163    #define CONFIG_SYS_TEXT_BASE         0x02000100
 164
 165
 166
 167 2. Build U-Boot
 168
 169 Steps::
 170
 171    mkdir b
 172    make -j8 O=b/chromebook_jerry CROSS_COMPILE=arm-linux-gnueabi- \
 173       chromebook_jerry_defconfig all
 174
 175
 176 3. See above
 177
 178 4. Build and sign an image
 179
 180 Steps::
 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
 192 5. See above
 193
 194 6. See above
 195
 196 7. Start it up
 197
 198 Reboot the device in dev mode. Make sure that you have USB booting enabled. To
 199 do this, login as root (via Ctrl-Alt-forward_arrow) and type
 200 'enable_dev_usb_boot'. You only need to do this once.
 201
 202 Reboot the device with the SD card inserted. Press Clrl-U at the developer
 203 mode 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
 213 8. Known problems
 214
 215 None as yet.
 216
 217
 218 9. Notes
 219
 220 None as yet.
 221
 222
 223 Other notes
 224 -----------
 225
 226 flashrom
 227 ~~~~~~~~
 228
 229 Used to make a backup of your firmware, or to replace it.
 230
 231 See: https://www.chromium.org/chromium-os/packages/cros-flashrom
 232
 233
 234 coreboot
 235 ~~~~~~~~
 236
 237 Coreboot itself is not designed to actually boot an OS. Instead, a program
 238 called Depthcharge is used. This originally came out of U-Boot and was then
 239 heavily hacked and modified such that is is almost unrecognisable. It does
 240 include a very small part of the U-Boot command-line interface but is not
 241 usable as a general-purpose boot loader.
 242
 243 In addition, it has a very unusual design in that it does not do device init
 244 itself, but instead relies on coreboot. This is similar to (in U-Boot) having
 245 a SPI driver with an empty probe() method, relying on whatever was set up
 246 beforehand. It can be quite hard to figure out between these two code bases
 247 what settings are actually used. When chain-loading into U-Boot we must be
 248 careful to reinit anything that U-Boot expects. If not, some peripherals (or
 249 the whole machine) may not work. This makes the process of chainloading more
 250 complicated than it could be on some platforms.
 251
 252 Finally, it supports only a subset of the U-Boot's FIT format. In particular
 253 it uses a fixed address to load the FIT and does not support load/exec
 254 addresses. This means that U-Boot must be able to boot from whatever
 255 address Depthcharge happens to use (it is the CONFIG_KERNEL_START setting
 256 in 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.