doc/README.chromium-chainload

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