Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

1 files changed, 442 insertions, 0 deletions

diff --git a/roms/u-boot/doc/board/google/chromebook_coral.rst b/roms/u-boot/doc/board/google/chromebook_coral.rst
new file mode 100644
index 000000000..4b585678d
--- /dev/null
+++ b/roms/u-boot/doc/board/google/chromebook_coral.rst
@@ -0,0 +1,442 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Simon Glass <sjg@chromium.org>
+
+Chromebook Coral
+================
+
+Coral is a Chromebook (or really about 20 different Chromebooks) which use the
+Intel Apollo Lake platform (APL). The 'reef' Chromebooks use the same APL SoC so
+should also work. Some later ones based on Glacier Lake (GLK) need various
+changes in GPIOs, etc. but are very similar.
+
+It is hoped that this port can enable ports to embedded APL boards which are
+starting to appear.
+
+Note that booting U-Boot on APL is already supported by coreboot and
+Slim Bootloader. This documentation refers to a 'bare metal' port.
+
+
+Building
+--------
+
+First, you need the following binary blobs:
+
+   * descriptor.bin - Intel flash descriptor
+   * fitimage.bin - Base flash image structure
+   * fsp_m.bin - FSP-M, for setting up SDRAM
+   * fsp_s.bin - FSP-S, for setting up Silicon
+   * vbt.bin - for setting up display
+
+These binaries do not seem to be available publicly. If you have a ROM image,
+such as santa.bin then you can do this::
+
+  cbfstool santa.bin extract -n fspm.bin -f fsp-m.bin
+  cbfstool santa.bin extract -n fsps.bin -f fsp-s.bin
+  cbfstool santa.bin extract -n vbt-santa.bin -f vbt.bin
+  mkdir tmp
+  cd tmp
+  dump_fmap -x ../santa.bin
+  mv SI_DESC ../descriptor.bin
+  mv IFWI ../fitimage.bin
+
+Put all of these files in `board/google/chromebook_coral` so they can be found
+by the build.
+
+To build::
+
+  make O=/tmp/b/chromebook_coral chromebook_coral_defconfig
+  make O=/tmp/b/chromebook_coral -s -j30 all
+
+That should produce `/tmp/b/chrombook_coral/u-boot.rom` which you can use with
+a Dediprog em100::
+
+  em100 -s -c w25q128fw -d /tmp/b/chromebook_coral/u-boot.rom -r
+
+or you can use flashrom to write it to the board. If you do that, make sure you
+have a way to restore the old ROM without booting the board. Otherwise you may
+brick it. Having said that, you may find these instructions useful if you want
+to unbrick your device:
+
+  https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging.md
+
+You can buy Suzy-Q from Sparkfun:
+
+  https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/main/docs/ccd.md#suzyq-suzyqable
+
+Note that it will hang at the SPL prompt for 21 seconds. When booting into
+Chrome OS it will always select developer mode, so will wipe anything you have
+on the device if you let it proceed. You have two seconds in U-Boot to stop the
+auto-boot prompt and several seconds at the 'developer wipe' screen to stop it
+wiping the disk.
+
+Here is the console output::
+
+  U-Boot TPL 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700)
+  Trying to boot from Mapped SPI
+
+  U-Boot SPL 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700)
+  Trying to boot from Mapped SPI
+
+
+  U-Boot 2021.04-rc1-00128-g344eefcdfec-dirty (Feb 11 2021 - 20:13:08 -0700)
+
+  CPU:   Intel(R) Celeron(R) CPU N3450 @ 1.10GHz
+  DRAM:  3.9 GiB
+  MMC:   sdmmc@1b,0: 1, emmc@1c,0: 2
+  Video: 1024x768x32 @ b0000000
+  Model: Google Coral
+  Net:   No ethernet found.
+  SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB
+  Hit any key to stop autoboot:  0
+  cmdline=console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=${uuid}/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=${uuid} add_efi_memmap boot=local noresume noswap i915.modeset=1 Kernel command line: "console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off  "
+  Setup located at 00090000:
+
+  ACPI RSDP addr      : 7991f000
+  E820: 14 entries
+                Addr              Size  Type
+      d0000000     1000000  <NULL>
+             0       a0000  RAM
+         a0000       60000  Reserved
+      7b000000      800000  Reserved
+      7b800000     4800000  Reserved
+      7ac00000      400000  Reserved
+        100000     ff00000  RAM
+      10000000     2151000  Reserved
+      12151000    68aaf000  RAM
+     100000000    80000000  RAM
+      e0000000    10000000  Reserved
+      7991bfd0     12e4030  Reserved
+      d0000000    10000000  Reserved
+      fed10000        8000  Reserved
+  Setup sectors       : 1e
+  Root flags          : 1
+  Sys size            : 63420
+  RAM size            : 0
+  Video mode          : ffff
+  Root dev            : 0
+  Boot flag           : 0
+  Jump                : 66eb
+  Header              : 53726448
+                        Kernel V2
+  Version             : 20d
+  Real mode switch    : 0
+  Start sys           : 1000
+  Kernel version      : 38cc
+     @00003acc:
+  Type of loader      : 80
+                        U-Boot, version 0
+  Load flags          : 81
+                      : loaded-high can-use-heap
+  Setup move size     : 8000
+  Code32 start        : 100000
+  Ramdisk image       : 0
+  Ramdisk size        : 0
+  Bootsect kludge     : 0
+  Heap end ptr        : 8e00
+  Ext loader ver      : 0
+  Ext loader type     : 0
+  Command line ptr    : 99000
+     console= loglevel=7 init=/sbin/init cros_secure oops=panic panic=-1 root=PARTUUID=35c775e7-3735-d745-93e5-d9e0238f7ed0/PARTNROFF=1 rootwait rw dm_verity.error_behavior=3 dm_verity.max_bios=-1 dm_verity.dev_wait=0 dm="1 vroot none rw 1,0 3788800 verity payload=ROOT_DEV hashtree=HASH_DEV hashstart=3788800 alg=sha1 root_hexdigest=55052b629d3ac889f25a9583ea12cdcd3ea15ff8 salt=a2d4d9e574069f4fed5e3961b99054b7a4905414b60a25d89974a7334021165c" noinitrd vt.global_cursor_default=0 kern_guid=35c775e7-3735-d745-93e5-d9e0238f7ed0 add_efi_memmap boot=local noresume noswap i915.modeset=1 tpm_tis.force=1 tpm_tis.interrupts=0 nmi_watchdog=panic,lapic disablevmx=off
+  Initrd addr max     : 7fffffff
+  Kernel alignment    : 200000
+  Relocatable kernel  : 1
+  Min alignment       : 15
+                      : 200000
+  Xload flags         : 3
+                      : 64-bit-entry can-load-above-4gb
+  Cmdline size        : 7ff
+  Hardware subarch    : 0
+  HW subarch data     : 0
+  Payload offset      : 26e
+  Payload length      : 612045
+  Setup data          : 0
+  Pref address        : 1000000
+  Init size           : 1383000
+  Handover offset     : 0
+
+  Starting kernel ...
+
+  Timer summary in microseconds (17 records):
+         Mark    Elapsed  Stage
+            0          0  reset
+      155,279    155,279  TPL
+      237,088     81,809  end phase
+      237,533        445  SPL
+      816,456    578,923  end phase
+      817,357        901  board_init_f
+    1,061,751    244,394  board_init_r
+    1,402,435    340,684  id=64
+    1,430,071     27,636  main_loop
+    5,532,057  4,101,986  start_kernel
+
+  Accumulated time:
+                     685  dm_r
+                   2,817  fast_spi
+                  33,095  dm_spl
+                  52,468  dm_f
+                 208,242  fsp-m
+                 242,221  fsp-s
+                 332,710  mmap_spi
+
+
+Boot flow - TPL
+---------------
+
+Apollo Lake boots via an IFWI (Integrated Firmware Image). TPL is placed in
+this, in the IBBL entry.
+
+On boot, an on-chip microcontroller called the CSE (Converged Security Engine)
+sets up some SDRAM at ffff8000 and loads the TPL image to that address. The
+SRAM extends up to the top of 32-bit address space, but the last 2KB is the
+start16 region, so the TPL image must be 30KB at most, and CONFIG_TPL_TEXT_BASE
+must be ffff8000. Actually the start16 region is small and it could probably
+move from f800 to fe00, providing another 1.5KB, but TPL is only about 19KB so
+there is no need to change it at present. The size limit is enforced by
+CONFIG_TPL_SIZE_LIMIT to avoid producing images that won't boot.
+
+TPL (running from start.S) first sets up CAR (Cache-as-RAM) which provides
+larger area of RAM for use while booting. CAR is mapped at CONFIG_SYS_CAR_ADDR
+(fef00000) and is 768KB in size. It then sets up the stack in the botttom 64KB
+of this space (i.e. below fef10000). This means that the stack and early
+malloc() region in TPL can be 64KB at most.
+
+TPL operates without CONFIG_TPL_PCI enabled so PCI config access must use the
+x86-specific functions pci_x86_write_config(), etc. SPL creates a simple-bus
+device so that PCI devices are bound by driver model. Then arch_cpu_init_tpl()
+is called to early init on various devices. This includes placing PCI devices
+at hard-coded addresses in the memory map. PCI auto-config is not used.
+
+Most of the 16KB ROM is mapped into the very top of memory, except for the
+Intel descriptor (first 4KB) and the space for SRAM as above.
+
+TPL does not set up a bloblist since at present it does not have anything to
+pass to SPL.
+
+Once TPL is done it loads SPL from ROM using either the memory-mapped SPI or by
+using the Intel fast SPI driver. SPL is loaded into CAR, at the address given
+by CONFIG_SPL_TEXT_BASE, which is normally fef10000.
+
+Note that booting using the SPI driver results in an TPL image that is about
+26KB in size instead of 19KB. Also boot speed is worse by about 340ms. If you
+really want to use the driver, enable CONFIG_APL_SPI_FLASH_BOOT and set
+BOOT_FROM_FAST_SPI_FLASH to true[2].
+
+
+Boot flow - SPL
+---------------
+
+SPL (running from start_from_tpl.S) continues to use the same stack as TPL.
+It calls arch_cpu_init_spl() to set up a few devices, then init_dram() loads
+the FSP-M binary into CAR and runs to, to set up SDRAM. The address of the
+output 'HOB' list (Hand-off-block) is stored into gd->arch.hob_list for parsing.
+There is a 2GB chunk of SDRAM starting at 0 and the rest is at 4GB.
+
+PCI auto-config is not used in SPL either, but CONFIG_SPL_PCI is defined, so
+proper PCI access is available and normal dm_pci_read_config() calls can be
+used. However PCI auto-config is not used so the same static memory mapping set
+up by TPL is still active.
+
+SPL on x86 always runs with CONFIG_SPL_SEPARATE_BSS=y and BSS is at 120000
+(see u-boot-spl.lds). This works because SPL doesn't access BSS until after
+board_init_r(), as per the rules, and DRAM is available then.
+
+SPL sets up a bloblist and passes the SPL hand-off information to U-Boot proper.
+This includes a pointer to the HOB list as well as DRAM information. See
+struct arch_spl_handoff. The bloblist address is set by CONFIG_BLOBLIST_ADDR,
+normally 100000.
+
+SPL uses SPI flash to update the MRC caches in ROM. This speeds up subsequent
+boots. Be warned that SPL can take 30 seconds without this cache! This is a
+known issue with Intel SoCs with modern DRAM and apparently cannot be improved.
+The MRC caches are used to work around this.
+
+Once SPL is finished it loads U-Boot into SDRAM at CONFIG_SYS_TEXT_BASE, which
+is normally 1110000. Note that CAR is still active.
+
+
+Boot flow - U-Boot pre-relocation
+---------------------------------
+
+U-Boot (running from start_from_spl.S) starts running in RAM and uses the same
+stack as SPL. It does various init activities before relocation. Notably
+arch_cpu_init_dm() sets up the pin muxing for the chip using a very large table
+in the device tree.
+
+PCI auto-config is not used before relocation, but CONFIG_PCI of course is
+defined, so proper PCI access is available. The same static memory mapping set
+up by TPL is still active until relocation.
+
+As per usual, U-Boot allocates memory at the top of available RAM (a bit below
+2GB in this case) and copies things there ready to relocate itself. Notably
+reserve_arch() does not reserve space for the HOB list returned by FSP-M since
+this is already located in RAM.
+
+U-Boot then shuts down CAR and jumps to its relocated version.
+
+
+Boot flow - U-Boot post-relocation
+----------------------------------
+
+U-Boot starts up normally, running near the top of RAM. After driver model is
+running, arch_fsp_init_r() is called which loads and runs the FSP-S binary.
+This updates the HOB list to include graphics information, used by the fsp_video
+driver.
+
+PCI autoconfig is done and a few devices are probed to complete init. Most
+others are started only when they are used.
+
+Note that FSP-S is supposed to run after CAR has been shut down, which happens
+immediately before U-Boot starts up in its relocated position. Therefore we
+cannot run FSP-S before relocation. On the other hand we must run it before
+PCI auto-config is done, since FSP-S may show or hide devices. The first device
+that probes PCI after relocation is the serial port, in initr_serial(), so FSP-S
+must run before that. A corollary is that loading FSP-S must be done without
+using the SPI driver, to avoid probing PCI and causing an autoconfig, so
+memory-mapped reading is always used for FSP-S.
+
+It would be possible to tear down CAR in SPL instead of U-Boot. The SPL handoff
+information could make sure it does not include any pointers into CAR (in fact
+it doesn't). But tearing down CAR in U-Boot allows the initial state used by TPL
+and SPL to be read by U-Boot, which seems useful. It also matches how older
+platforms start up (those that don't use SPL).
+
+
+Performance
+-----------
+
+Bootstage is used through all phases of U-Boot to keep accurate timimgs for
+boot. Use 'bootstage report' in U-Boot to see the report, e.g.::
+
+    Timer summary in microseconds (16 records):
+           Mark    Elapsed  Stage
+              0          0  reset
+        155,325    155,325  TPL
+        204,014     48,689  end TPL
+        204,385        371  SPL
+        738,633    534,248  end SPL
+        739,161        528  board_init_f
+        842,764    103,603  board_init_r
+      1,166,233    323,469  main_loop
+      1,166,283         50  id=175
+
+    Accumulated time:
+                        62  fast_spi
+                       202  dm_r
+                     7,779  dm_spl
+                    15,555  dm_f
+                   208,357  fsp-m
+                   239,847  fsp-s
+                   292,143  mmap_spi
+
+CPU performance is about 3500 DMIPS::
+
+    => dhry
+    1000000 iterations in 161 ms: 6211180/s, 3535 DMIPS
+
+
+Partial memory map
+------------------
+
+::
+
+    ffffffff       Top of ROM (and last byte of 32-bit address space)
+    ffff8000       TPL loaded here (from IFWI)
+    ff000000       Bottom of ROM
+    fefc0000       Top of CAR region
+    fef96000       Stack for FSP-M
+    fef40000 59000 FSP-M (also VPL loads here)
+    fef11000       SPL loaded here
+    fef10000       CONFIG_BLOBLIST_ADDR
+    fef10000       Stack top in TPL, SPL and U-Boot before relocation
+    fef00000  1000 CONFIG_BOOTSTAGE_STASH_ADDR
+    fef00000       Base of CAR region
+
+       30000       AP_DEFAULT_BASE (used to start up additional CPUs)
+       f0000       CONFIG_ROM_TABLE_ADDR
+      120000       BSS (defined in u-boot-spl.lds)
+      200000       FSP-S (which is run after U-Boot is relocated)
+     1110000       CONFIG_SYS_TEXT_BASE
+
+
+Speeding up SPL for development
+-------------------------------
+
+The 21-second wait for memory training is annoying during development, since
+every new image incurs this cost when booting. There is no cache to fall back on
+since that area of the image is empty on start-up.
+
+You can add suitable cache contents to the image to fix this, for development
+purposes only, like this::
+
+   # Read the image back after booting through SPL
+   em100 -s -c w25q128fw -u image.bin
+
+   # Extract the two cache regions
+   binman extract -i image.bin extra *cache
+
+   # Move them into the source directory
+   mv *cache board/google/chromebook_coral
+
+Then add something like this to the devicetree::
+
+  #if IS_ENABLED(CONFIG_HAVE_MRC) || IS_ENABLED(CONFIG_FSP_VERSION2)
+     /* Provide initial contents of the MRC data for faster development */
+     rw-mrc-cache {
+        type = "blob";
+        /* Mirror the offset in spi-flash@0 */
+        offset = <0xff8e0000>;
+        size = <0x10000>;
+        filename = "board/google/chromebook_coral/rw-mrc-cache";
+     };
+     rw-var-mrc-cache {
+        type = "blob";
+        size = <0x1000>;
+        filename = "board/google/chromebook_coral/rw-var-mrc-cache";
+     };
+  #endif
+
+This tells binman to put the cache contents in the same place as the
+`rw-mrc-cache` and `rw-var-mrc-cache` regions defined by the SPI-flash driver.
+
+
+Supported peripherals
+---------------------
+
+The following have U-Boot drivers:
+
+   - UART
+   - SPI flash
+   - Video
+   - MMC (dev 0) and micro-SD (dev 1)
+   - Chrome OS EC
+   - Cr50 (security chip)
+   - Keyboard
+   - USB
+
+
+To do
+-----
+
+- Finish peripherals
+   - Sound (Intel I2S support exists, but need da7219 driver)
+- Use FSP-T binary instead of our own CAR implementation
+- Use the official FSP package instead of the coreboot one
+- Suspend / resume
+- Fix MMC which seems to try to read even though the card is empty
+- Fix USB3 crash "WARN halted endpoint, queueing URB anyway."
+
+
+Credits
+-------
+
+This is a spare-time project conducted slowly over a long period of time.
+
+Much of the code for this port came from Coreboot, an open-source firmware
+project similar to U-Boot's SPL in terms of features.
+
+Also see [2] for information about the boot flow used by coreboot. It is
+similar, but has an extra postcar stage. U-Boot doesn't need this since it
+supports relocating itself in memory.
+
+
+[2] Intel PDF https://www.coreboot.org/images/2/23/Apollolake_SoC.pdf