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
  27 U-Boot with Chromium OS verified boot
  28 -------------------------------------
  29
  30 To obtain:
  31
  32    git clone https://github.com/sglass68/u-boot.git
  33    cd u-boot
  34    git checkout cros-master
  35
  36    cd ..
  37    git clone https://chromium.googlesource.com/chromiumos/platform/vboot_reference
  38    cd vboot_reference
  39    git checkout 45964294
  40    #  futility: updater: Correct output version for Snow
  41
  42 To build for sandbox:
  43
  44    UB=/tmp/b/chromeos_sandbox    # U-Boot build directory
  45    cd u-boot
  46    make O=$UB chromeos_sandbox_defconfig
  47    make O=$UB -j20 -s VBOOT_SOURCE=/path/to/vboot_reference \
  48         MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1
  49
  50 Replace sandbox with another supported target.
  51
  52 This produces $UB/image.bin which contains the firmware binaries in a SPI
  53 flash image.
  54
  55 To run on sandbox:
  56
  57    $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out \
  58         -L6 -c "host bind 0 $CROS/src/build/images/cheza/latest/chromiumos_image.bin; vboot go auto" \
  59         -l -w -s state.dtb -r
  60
  61 To run on other boards:
  62    Install image.bin in the SPI flash of your device
  63    Boot your system
  64
  65
  66 Sandbox
  67 -------
  68
  69 Most Chromium OS development with U-Boot is undertaken using sandbox. There is
  70 a sandbox target available (chromeos_sandbox) which allows running U-Boot on
  71 a Linux machine completion with emulations of the display, TPM, disk, etc.
  72
  73 Running sandbox starts TPL, which contains the first phase of vboot, providing
  74 a device tree and binding a Chromium OS disk image for use to find kernels
  75 (any Chromium OS image will do). It also saves driver state between U-Boot
  76 phases into state.dtb and will automatically ensure that memory is shared
  77 between all phases. TPL will jump to SPL and then on to U-Boot proper.
  78
  79 It is possible to run with debugging on, e.g.
  80
  81    gdb --args $UB/tpl/u-boot-tpl -d ....
  82
  83 Breakpoints can be set in any U-Boot phase. Overall this is a good debugging
  84 environment for new verified-boot features.
  85
  86
  87 Samus
  88 -----
  89
  90 Basic support is available for samus, using the chromeos_samus target. If you
  91 have an em100, use:
  92
  93    sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r
  94
  95 to write the image and then boot samus (Power-Refresh).
  96
  97
  98 Boot flow
  99 ---------
 100
 101 Verified boot starts in TPL, which selects the A or B SPL, which in turn selects
 102 the A or B U-Boot. Then this jumps to the selected kernel. If anything goes
 103 wrong, the device reboots and the recovery SPL and U-Boot are used instead.
 104
 105 More details are available here:
 106
 107    https://www.chromium.org/chromium-os/chromiumos-design-docs/firmware-boot-and-recovery
 108
 109
 110 New uclasses
 111 ------------
 112
 113 Several uclasses are provided in cros/:
 114
 115         UCLASS_CROS_AUX_FW              Chrome OS auxiliary firmware
 116         UCLASS_CROS_FWSTORE             Chrome OS firmware storage
 117         UCLASS_CROS_NVDATA              Chrome OS non-volatile data device
 118         UCLASS_CROS_VBOOT_EC            Chrome OS vboot EC operations
 119         UCLASS_CROS_VBOOT_FLAG          Chrome OS verified boot flag
 120
 121 The existing UCLASS_CROS_EC is also used.
 122
 123
 124 Commands
 125 --------
 126
 127 A new 'vboot' command is provided to run particular vboot stages. The most
 128 useful command is 'vboot go auto', which continues where the last stage left
 129 off.
 130
 131 Note that TPL and SPL do not supports commands as yet, so the vboot code is
 132 called directly from the SPL boot devices (BOOT_DEVICE_CROS_VBOOT). See
 133 cros_load_image_tpl() and cros_load_image_spl() which both call
 134 vboot_run_auto().
 135
 136
 137 Config options
 138 --------------
 139
 140 The main option is CONFIG_CHROMEOS, which enables a wide array of other options
 141 so that the required features are present.
 142
 143
 144 Device-tree config
 145 ------------------
 146
 147 Various options are available which control the operation of verified boot.
 148 See cros/dts/bindings/config.txt for details. Most config is handled at run-
 149 time, although build-time config (with Kconfig) could also be added fairly
 150 easily.
 151
 152
 153 Porting to other hardware
 154 -------------------------
 155
 156 A basic port to samus (Chromebook Pixel 2015) is in a basic working state,
 157 using the chromeos_samus target. Patches will likely be forthcoming in early
 158 2019. Ports to an ARM board and coreboot (for x86 Chromebooks) are in the
 159 dreaming state.
 160
 161
 162 Tests
 163 -----
 164
 165 Chromium OS firmware has a very limited set of tests. The tests that originally
 166 existed in U-Boot were not brought over to coreboot or depthcharge.
 167
 168 The U-Boot tests ('make check') do operate, but at present there are no
 169 Chromium OS tests available. These will hopefully come together over time. Of
 170 course the above sandbox feature provides a sort of functional test and can
 171 detecte problems that affect the flow or particular vboot features.
 172
 173
 174 TO DO
 175 -----
 176
 177 - Support for booting from coreboot (patches expected March 2019)
 178 - Support for booting from an ARM board, e.g. bob
 179
 180
 181 Simon Glass
 182 sjg@chromium.org
 183 7 October 2018