doc/README.chromium

   1 Chromium OS Support in U-Boot
   2 =============================
   3
   4 Introduction
   5 ------------
   6
   7 This describes how to use U-Boot with Chromium OS. Several options are
   8 available:
   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
  34 U-Boot with Chromium OS verified boot
  35 -------------------------------------
  36
  37 To 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
  49 To 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
  57 Replace sandbox with another supported target.
  58
  59 This produces $UB/image.bin which contains the firmware binaries in a SPI
  60 flash image.
  61
  62 To 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
  68 To run on other boards:
  69    Install image.bin in the SPI flash of your device
  70    Boot your system
  71
  72
  73 Sandbox
  74 -------
  75
  76 Most Chromium OS development with U-Boot is undertaken using sandbox. There is
  77 a sandbox target available (chromeos_sandbox) which allows running U-Boot on
  78 a Linux machine completion with emulations of the display, TPM, disk, etc.
  79
  80 Running sandbox starts TPL, which contains the first phase of vboot, providing
  81 a 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
  83 phases into state.dtb and will automatically ensure that memory is shared
  84 between all phases. TPL will jump to SPL and then on to U-Boot proper.
  85
  86 It is possible to run with debugging on, e.g.
  87
  88    gdb --args $UB/tpl/u-boot-tpl -d ....
  89
  90 Breakpoints can be set in any U-Boot phase. Overall this is a good debugging
  91 environment for new verified-boot features.
  92
  93
  94 Samus
  95 -----
  96
  97 Basic support is available for samus, using the chromeos_samus target. If you
  98 have an em100, use:
  99
 100    sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r
 101
 102 to write the image and then boot samus (Power-Refresh).
 103
 104
 105 Boot flow
 106 ---------
 107
 108 Verified boot starts in TPL, which selects the A or B SPL, which in turn selects
 109 the A or B U-Boot. Then this jumps to the selected kernel. If anything goes
 110 wrong, the device reboots and the recovery SPL and U-Boot are used instead.
 111
 112 More details are available here:
 113
 114    https://www.chromium.org/chromium-os/chromiumos-design-docs/firmware-boot-and-recovery
 115
 116
 117 New uclasses
 118 ------------
 119
 120 Several 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
 128 The existing UCLASS_CROS_EC is also used.
 129
 130
 131 Commands
 132 --------
 133
 134 A new 'vboot' command is provided to run particular vboot stages. The most
 135 useful command is 'vboot go auto', which continues where the last stage left
 136 off.
 137
 138 Note that TPL and SPL do not supports commands as yet, so the vboot code is
 139 called directly from the SPL boot devices (BOOT_DEVICE_CROS_VBOOT). See
 140 cros_load_image_tpl() and cros_load_image_spl() which both call
 141 vboot_run_auto().
 142
 143
 144 Config options
 145 --------------
 146
 147 The main option is CONFIG_CHROMEOS, which enables a wide array of other options
 148 so that the required features are present.
 149
 150
 151 Device-tree config
 152 ------------------
 153
 154 Various options are available which control the operation of verified boot.
 155 See cros/dts/bindings/config.txt for details. Most config is handled at run-
 156 time, although build-time config (with Kconfig) could also be added fairly
 157 easily.
 158
 159
 160 Porting to other hardware
 161 -------------------------
 162
 163 A basic port to samus (Chromebook Pixel 2015) is in a basic working state,
 164 using the chromeos_samus target. Patches will likely be forthcoming in early
 165 2019. Ports to an ARM board and coreboot (for x86 Chromebooks) are in the
 166 dreaming state.
 167
 168
 169 Tests
 170 -----
 171
 172 Chromium OS firmware has a very limited set of tests. The tests that originally
 173 existed in U-Boot were not brought over to coreboot or depthcharge.
 174
 175 The U-Boot tests ('make check') do operate, but at present there are no
 176 Chromium OS tests available. These will hopefully come together over time. Of
 177 course the above sandbox feature provides a sort of functional test and can
 178 detect problems that affect the flow or particular vboot features.
 179
 180
 181 U-Boot without Chromium OS verified boot
 182 ----------------------------------------
 183
 184 The 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
 210 TO DO
 211 -----
 212
 213 Get the full ACPI tables working with Coral
 214
 215
 216 Simon Glass
 217 sjg@chromium.org
 218 7 October 2018