0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ======================================
0004 Chromebook Boot Flow
0005 ======================================
0006
0007 Most recent Chromebooks that use device tree are using the opensource
0008 depthcharge_ bootloader. Depthcharge_ expects the OS to be packaged as a `FIT
0009 Image`_ which contains an OS image as well as a collection of device trees. It
0010 is up to depthcharge_ to pick the right device tree from the `FIT Image`_ and
0011 provide it to the OS.
0012
0013 The scheme that depthcharge_ uses to pick the device tree takes into account
0014 three variables:
0015
0016 - Board name, specified at depthcharge_ compile time. This is $(BOARD) below.
0017 - Board revision number, determined at runtime (perhaps by reading GPIO
0018 strappings, perhaps via some other method). This is $(REV) below.
0019 - SKU number, read from GPIO strappings at boot time. This is $(SKU) below.
0020
0021 For recent Chromebooks, depthcharge_ creates a match list that looks like this:
0022
0023 - google,$(BOARD)-rev$(REV)-sku$(SKU)
0024 - google,$(BOARD)-rev$(REV)
0025 - google,$(BOARD)-sku$(SKU)
0026 - google,$(BOARD)
0027
0028 Note that some older Chromebooks use a slightly different list that may
0029 not include SKU matching or may prioritize SKU/rev differently.
0030
0031 Note that for some boards there may be extra board-specific logic to inject
0032 extra compatibles into the list, but this is uncommon.
0033
0034 Depthcharge_ will look through all device trees in the `FIT Image`_ trying to
0035 find one that matches the most specific compatible. It will then look
0036 through all device trees in the `FIT Image`_ trying to find the one that
0037 matches the *second most* specific compatible, etc.
0038
0039 When searching for a device tree, depthcharge_ doesn't care where the
0040 compatible string falls within a device tree's root compatible string array.
0041 As an example, if we're on board "lazor", rev 4, SKU 0 and we have two device
0042 trees:
0043
0044 - "google,lazor-rev5-sku0", "google,lazor-rev4-sku0", "qcom,sc7180"
0045 - "google,lazor", "qcom,sc7180"
0046
0047 Then depthcharge_ will pick the first device tree even though
0048 "google,lazor-rev4-sku0" was the second compatible listed in that device tree.
0049 This is because it is a more specific compatible than "google,lazor".
0050
0051 It should be noted that depthcharge_ does not have any smarts to try to
0052 match board or SKU revisions that are "close by". That is to say that
0053 if depthcharge_ knows it's on "rev4" of a board but there is no "rev4"
0054 device tree then depthcharge_ *won't* look for a "rev3" device tree.
0055
0056 In general when any significant changes are made to a board the board
0057 revision number is increased even if none of those changes need to
0058 be reflected in the device tree. Thus it's fairly common to see device
0059 trees with multiple revisions.
0060
0061 It should be noted that, taking into account the above system that
0062 depthcharge_ has, the most flexibility is achieved if the device tree
0063 supporting the newest revision(s) of a board omits the "-rev{REV}"
0064 compatible strings. When this is done then if you get a new board
0065 revision and try to run old software on it then we'll at pick the
0066 newest device tree we know about.
0067
0068 .. _depthcharge: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/depthcharge/
0069 .. _`FIT Image`: https://doc.coreboot.org/lib/payloads/fit.html
