README.chromium 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183
  1. Chromium OS Support in U-Boot
  2. =============================
  3. Introduction
  4. ------------
  5. This describes how to use U-Boot with Chromium OS. Several options are
  6. available:
  7. - Running U-Boot from the 'altfw' feature, which is available on selected
  8. Chromebooks from 2019 onwards (initially Grunt). Press '1' from the
  9. developer-mode screen to get into U-Boot. See here for details:
  10. https://sites.google.com/a/chromium.org/dev/chromium-os/poking-around-your-chrome-os-device?pli=1
  11. - Running U-Boot from the disk partition. This involves signing U-Boot and
  12. placing it on the disk, for booting as a 'kernel'. See
  13. README.chromium-chainload for information on this. This is the only
  14. option on non-U-Boot Chromebooks from 2013 to 2018 and is somewhat
  15. more involved.
  16. - Running U-Boot with Chromium OS verified boot. This allows U-Boot to be
  17. used instead of either or both of depthcharge (a bootloader which forked
  18. from U-Boot in 2013) and coreboot. See below for more information on
  19. this.
  20. U-Boot with Chromium OS verified boot
  21. -------------------------------------
  22. To obtain:
  23. git clone https://github.com/sglass68/u-boot.git
  24. cd u-boot
  25. git checkout cros-master
  26. cd ..
  27. git clone https://chromium.googlesource.com/chromiumos/platform/vboot_reference
  28. cd vboot_reference
  29. git checkout 45964294
  30. # futility: updater: Correct output version for Snow
  31. To build for sandbox:
  32. UB=/tmp/b/chromeos_sandbox # U-Boot build directory
  33. cd u-boot
  34. make O=$UB chromeos_sandbox_defconfig
  35. make O=$UB -j20 -s VBOOT_SOURCE=/path/to/vboot_reference \
  36. MAKEFLAGS_VBOOT=DEBUG=1 QUIET=1
  37. Replace sandbox with another supported target.
  38. This produces $UB/image.bin which contains the firmware binaries in a SPI
  39. flash image.
  40. To run on sandbox:
  41. $UB/tpl/u-boot-tpl -d $UB/u-boot.dtb.out \
  42. -L6 -c "host bind 0 $CROS/src/build/images/cheza/latest/chromiumos_image.bin; vboot go auto" \
  43. -l -w -s state.dtb -r
  44. To run on other boards:
  45. Install image.bin in the SPI flash of your device
  46. Boot your system
  47. Sandbox
  48. -------
  49. Most Chromium OS development with U-Boot is undertaken using sandbox. There is
  50. a sandbox target available (chromeos_sandbox) which allows running U-Boot on
  51. a Linux machine completion with emulations of the display, TPM, disk, etc.
  52. Running sandbox starts TPL, which contains the first phase of vboot, providing
  53. a device tree and binding a Chromium OS disk image for use to find kernels
  54. (any Chromium OS image will do). It also saves driver state between U-Boot
  55. phases into state.dtb and will automatically ensure that memory is shared
  56. between all phases. TPL will jump to SPL and then on to U-Boot proper.
  57. It is possible to run with debugging on, e.g.
  58. gdb --args $UB/tpl/u-boot-tpl -d ....
  59. Breakpoints can be set in any U-Boot phase. Overall this is a good debugging
  60. environment for new verified-boot features.
  61. Samus
  62. -----
  63. Basic support is available for samus, using the chromeos_samus target. If you
  64. have an em100, use:
  65. sudo em100 -s -c W25Q128FW -d $UB/image.bin -t -r
  66. to write the image and then boot samus (Power-Refresh).
  67. Boot flow
  68. ---------
  69. Verified boot starts in TPL, which selects the A or B SPL, which in turn selects
  70. the A or B U-Boot. Then this jumps to the selected kernel. If anything goes
  71. wrong, the device reboots and the recovery SPL and U-Boot are used instead.
  72. More details are available here:
  73. https://www.chromium.org/chromium-os/chromiumos-design-docs/firmware-boot-and-recovery
  74. New uclasses
  75. ------------
  76. Several uclasses are provided in cros/:
  77. UCLASS_CROS_AUX_FW Chrome OS auxiliary firmware
  78. UCLASS_CROS_FWSTORE Chrome OS firmware storage
  79. UCLASS_CROS_NVDATA Chrome OS non-volatile data device
  80. UCLASS_CROS_VBOOT_EC Chrome OS vboot EC operations
  81. UCLASS_CROS_VBOOT_FLAG Chrome OS verified boot flag
  82. The existing UCLASS_CROS_EC is also used.
  83. Commands
  84. --------
  85. A new 'vboot' command is provided to run particular vboot stages. The most
  86. useful command is 'vboot go auto', which continues where the last stage left
  87. off.
  88. Note that TPL and SPL do not supports commands as yet, so the vboot code is
  89. called directly from the SPL boot devices (BOOT_DEVICE_CROS_VBOOT). See
  90. cros_load_image_tpl() and cros_load_image_spl() which both call
  91. vboot_run_auto().
  92. Config options
  93. --------------
  94. The main option is CONFIG_CHROMEOS, which enables a wide array of other options
  95. so that the required features are present.
  96. Device-tree config
  97. ------------------
  98. Various options are available which control the operation of verified boot.
  99. See cros/dts/bindings/config.txt for details. Most config is handled at run-
  100. time, although build-time config (with Kconfig) could also be added fairly
  101. easily.
  102. Porting to other hardware
  103. -------------------------
  104. A basic port to samus (Chromebook Pixel 2015) is in a basic working state,
  105. using the chromeos_samus target. Patches will likely be forthcoming in early
  106. 2019. Ports to an ARM board and coreboot (for x86 Chromebooks) are in the
  107. dreaming state.
  108. Tests
  109. -----
  110. Chromium OS firmware has a very limited set of tests. The tests that originally
  111. existed in U-Boot were not brought over to coreboot or depthcharge.
  112. The U-Boot tests ('make check') do operate, but at present there are no
  113. Chromium OS tests available. These will hopefully come together over time. Of
  114. course the above sandbox feature provides a sort of functional test and can
  115. detecte problems that affect the flow or particular vboot features.
  116. TO DO
  117. -----
  118. - Support for booting from coreboot (patches expected March 2019)
  119. - Support for booting from an ARM board, e.g. bob
  120. Simon Glass
  121. sjg@chromium.org
  122. 7 October 2018