chromebook_coral.rst 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. .. sectionauthor:: Simon Glass <sjg@chromium.org>
  3. Chromebook Coral
  4. ================
  5. Coral is a Chromebook (or really about 20 different Chromebooks) which use the
  6. Intel Apollo Lake platform (APL). The 'reef' Chromebooks use the same APL SoC so
  7. should also work. Some later ones based on Glacier Lake (GLK) need various
  8. changes in GPIOs, etc. but are very similar.
  9. It is hoped that this port can enable ports to embedded APL boards which are
  10. starting to appear.
  11. Note that booting U-Boot on APL is already supported by coreboot and
  12. Slim Bootloader. This documentation refers to a 'bare metal' port.
  13. Boot flow - TPL
  14. ---------------
  15. Apollo Lake boots via an IFWI (Integrated Firmware Image). TPL is placed in
  16. this, in the IBBL entry.
  17. On boot, an on-chip microcontroller called the CSE (Converged Security Engine)
  18. sets up some SDRAM at ffff8000 and loads the TPL image to that address. The
  19. SRAM extends up to the top of 32-bit address space, but the last 2KB is the
  20. start16 region, so the TPL image must be 30KB at most, and CONFIG_TPL_TEXT_BASE
  21. must be ffff8000. Actually the start16 region is small and it could probably
  22. move from f800 to fe00, providing another 1.5KB, but TPL is only about 19KB so
  23. there is no need to change it at present. The size limit is enforced by
  24. CONFIG_TPL_SIZE_LIMIT to avoid producing images that won't boot.
  25. TPL (running from start.S) first sets up CAR (Cache-as-RAM) which provides
  26. larger area of RAM for use while booting. CAR is mapped at CONFIG_SYS_CAR_ADDR
  27. (fef00000) and is 768KB in size. It then sets up the stack in the botttom 64KB
  28. of this space (i.e. below fef10000). This means that the stack and early
  29. malloc() region in TPL can be 64KB at most.
  30. TPL operates without CONFIG_TPL_PCI enabled so PCI config access must use the
  31. x86-specific functions pci_x86_write_config(), etc. SPL creates a simple-bus
  32. device so that PCI devices are bound by driver model. Then arch_cpu_init_tpl()
  33. is called to early init on various devices. This includes placing PCI devices
  34. at hard-coded addresses in the memory map. PCI auto-config is not used.
  35. Most of the 16KB ROM is mapped into the very top of memory, except for the
  36. Intel descriptor (first 4KB) and the space for SRAM as above.
  37. TPL does not set up a bloblist since at present it does not have anything to
  38. pass to SPL.
  39. Once TPL is done it loads SPL from ROM using either the memory-mapped SPI or by
  40. using the Intel fast SPI driver. SPL is loaded into CAR, at the address given
  41. by CONFIG_SPL_TEXT_BASE, which is normally fef10000.
  42. Note that booting using the SPI driver results in an TPL image that is about
  43. 26KB in size instead of 19KB. Also boot speed is worse by about 340ms. If you
  44. really want to use the driver, enable CONFIG_APL_SPI_FLASH_BOOT and set
  45. BOOT_FROM_FAST_SPI_FLASH to true[2].
  46. Boot flow - SPL
  47. ---------------
  48. SPL (running from start_from_tpl.S) continues to use the same stack as TPL.
  49. It calls arch_cpu_init_spl() to set up a few devices, then init_dram() loads
  50. the FSP-M binary into CAR and runs to, to set up SDRAM. The address of the
  51. output 'HOB' list (Hand-off-block) is stored into gd->arch.hob_list for parsing.
  52. There is a 2GB chunk of SDRAM starting at 0 and the rest is at 4GB.
  53. PCI auto-config is not used in SPL either, but CONFIG_SPL_PCI is defined, so
  54. proper PCI access is available and normal dm_pci_read_config() calls can be
  55. used. However PCI auto-config is not used so the same static memory mapping set
  56. up by TPL is still active.
  57. SPL on x86 always runs with CONFIG_SPL_SEPARATE_BSS=y and BSS is at 120000
  58. (see u-boot-spl.lds). This works because SPL doesn't access BSS until after
  59. board_init_r(), as per the rules, and DRAM is available then.
  60. SPL sets up a bloblist and passes the SPL hand-off information to U-Boot proper.
  61. This includes a pointer to the HOB list as well as DRAM information. See
  62. struct arch_spl_handoff. The bloblist address is set by CONFIG_BLOBLIST_ADDR,
  63. normally 100000.
  64. SPL uses SPI flash to update the MRC caches in ROM. This speeds up subsequent
  65. boots. Be warned that SPL can take 30 seconds without this cache! This is a
  66. known issue with Intel SoCs with modern DRAM and apparently cannot be improved.
  67. The MRC caches are used to work around this.
  68. Once SPL is finished it loads U-Boot into SDRAM at CONFIG_SYS_TEXT_BASE, which
  69. is normally 1110000. Note that CAR is still active.
  70. Boot flow - U-Boot pre-relocation
  71. ---------------------------------
  72. U-Boot (running from start_from_spl.S) starts running in RAM and uses the same
  73. stack as SPL. It does various init activities before relocation. Notably
  74. arch_cpu_init_dm() sets up the pin muxing for the chip using a very large table
  75. in the device tree.
  76. PCI auto-config is not used before relocation, but CONFIG_PCI of course is
  77. defined, so proper PCI access is available. The same static memory mapping set
  78. up by TPL is still active until relocation.
  79. As per usual, U-Boot allocates memory at the top of available RAM (a bit below
  80. 2GB in this case) and copies things there ready to relocate itself. Notably
  81. reserve_arch() does not reserve space for the HOB list returned by FSP-M since
  82. this is already located in RAM.
  83. U-Boot then shuts down CAR and jumps to its relocated version.
  84. Boot flow - U-Boot post-relocation
  85. ---------------------------------
  86. U-Boot starts up normally, running near the top of RAM. After driver model is
  87. running, arch_fsp_init_r() is called which loads and runs the FSP-S binary.
  88. This updates the HOB list to include graphics information, used by the fsp_video
  89. driver.
  90. PCI autoconfig is done and a few devices are probed to complete init. Most
  91. others are started only when they are used.
  92. Note that FSP-S is supposed to run after CAR has been shut down, which happens
  93. immediately before U-Boot starts up in its relocated position. Therefore we
  94. cannot run FSP-S before relocation. On the other hand we must run it before
  95. PCI auto-config is done, since FSP-S may show or hide devices. The first device
  96. that probes PCI after relocation is the serial port, in initr_serial(), so FSP-S
  97. must run before that. A corollary is that loading FSP-S must be done without
  98. using the SPI driver, to avoid probing PCI and causing an autoconfig, so
  99. memory-mapped reading is always used for FSP-S.
  100. It would be possible to tear down CAR in SPL instead of U-Boot. The SPL handoff
  101. information could make sure it does not include any pointers into CAR (in fact
  102. it doesn't). But tearing down CAR in U-Boot allows the initial state used by TPL
  103. and SPL to be read by U-Boot, which seems useful. It also matches how older
  104. platforms start up (those that don't use SPL).
  105. Performance
  106. -----------
  107. Bootstage is used through all phases of U-Boot to keep accurate timimgs for
  108. boot. Use 'bootstage report' in U-Boot to see the report, e.g.:
  109. Timer summary in microseconds (16 records):
  110. Mark Elapsed Stage
  111. 0 0 reset
  112. 155,325 155,325 TPL
  113. 204,014 48,689 end TPL
  114. 204,385 371 SPL
  115. 738,633 534,248 end SPL
  116. 739,161 528 board_init_f
  117. 842,764 103,603 board_init_r
  118. 1,166,233 323,469 main_loop
  119. 1,166,283 50 id=175
  120. Accumulated time:
  121. 62 fast_spi
  122. 202 dm_r
  123. 7,779 dm_spl
  124. 15,555 dm_f
  125. 208,357 fsp-m
  126. 239,847 fsp-s
  127. 292,143 mmap_spi
  128. CPU performance is about 3500 DMIPS:
  129. => dhry
  130. 1000000 iterations in 161 ms: 6211180/s, 3535 DMIPS
  131. Partial memory map
  132. ------------------
  133. ffffffff Top of ROM (and last byte of 32-bit address space)
  134. ffff8000 TPL loaded here (from IFWI)
  135. ff000000 Bottom of ROM
  136. fefc000 Top of CAR region
  137. fef96000 Stack for FSP-M
  138. fef40000 59000 FSP-M
  139. fef11000 SPL loaded here
  140. fef10000 CONFIG_BLOBLIST_ADDR
  141. fef10000 Stack top in TPL, SPL and U-Boot before relocation
  142. fef00000 1000 CONFIG_BOOTSTAGE_STASH_ADDR
  143. fef00000 Base of CAR region
  144. f0000 CONFIG_ROM_TABLE_ADDR
  145. 120000 BSS (defined in u-boot-spl.lds)
  146. 200000 FSP-S (which is run after U-Boot is relocated)
  147. 1110000 CONFIG_SYS_TEXT_BASE
  148. Supported peripherals
  149. ---------------------
  150. - UART
  151. - SPI flash
  152. - Video
  153. - MMC (dev 0) and micro-SD (dev 1)
  154. - Chrome OS EC
  155. - Keyboard
  156. - USB
  157. To do
  158. -----
  159. - Finish peripherals
  160. - left-side USB
  161. - USB-C
  162. - Cr50 (security chip: a basic driver is running but not included here)
  163. - I2C (driver exists but not enabled in device tree)
  164. - Sound (Intel I2S support exists, but need da7219 driver)
  165. - RTC (driver exists but not enabled in device tree)
  166. - Various minor features supported by LPC, etc.
  167. - Booting Chrome OS, e.g. with verified boot
  168. - Integrate with Chrome OS vboot
  169. - Improvements to booting from coreboot (i.e. as a coreboot target)
  170. - Use FSP-T binary instead of our own CAR implementation
  171. - Use the official FSP package instead of the coreboot one
  172. - Enable all CPU cores
  173. - Suspend / resume
  174. - ACPI
  175. Credits
  176. -------
  177. This is a spare-time project conducted slowly over a long period of time.
  178. Much of the code for this port came from Coreboot, an open-source firmware
  179. project similar to U-Boot's SPL in terms of features.
  180. Also see [2] for information about the boot flow used by coreboot. It is
  181. similar, but has an extra postcar stage. U-Boot doesn't need this since it
  182. supports relocating itself in memory.
  183. [2] Intel PDF https://www.coreboot.org/images/2/23/Apollolake_SoC.pdf