1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================================
4 Chromebook Boot Flow
5 ======================================
6
7 Most recent Chromebooks that use device tree are using the opensource
8 depthcharge_ bootloader. Depthcharge_ expects the OS to be packaged as a `FIT
9 Image`_ which contains an OS image as well as a collection of device trees. It
10 is up to depthcharge_ to pick the right device tree from the `FIT Image`_ and
11 provide it to the OS.
12
13 The scheme that depthcharge_ uses to pick the device tree takes into account
14 three variables:
15
16 - Board name, specified at depthcharge_ compile time. This is $(BOARD) below.
17 - Board revision number, determined at runtime (perhaps by reading GPIO
18 strappings, perhaps via some other method). This is $(REV) below.
19 - SKU number, read from GPIO strappings at boot time. This is $(SKU) below.
20
21 For recent Chromebooks, depthcharge_ creates a match list that looks like this:
22
23 - google,$(BOARD)-rev$(REV)-sku$(SKU)
24 - google,$(BOARD)-rev$(REV)
25 - google,$(BOARD)-sku$(SKU)
26 - google,$(BOARD)
27
28 Note that some older Chromebooks use a slightly different list that may
29 not include SKU matching or may prioritize SKU/rev differently.
30
31 Note that for some boards there may be extra board-specific logic to inject
32 extra compatibles into the list, but this is uncommon.
33
34 Depthcharge_ will look through all device trees in the `FIT Image`_ trying to
35 find one that matches the most specific compatible. It will then look
36 through all device trees in the `FIT Image`_ trying to find the one that
37 matches the *second most* specific compatible, etc.
38
39 When searching for a device tree, depthcharge_ doesn't care where the
40 compatible string falls within a device tree's root compatible string array.
41 As an example, if we're on board "lazor", rev 4, SKU 0 and we have two device
42 trees:
43
44 - "google,lazor-rev5-sku0", "google,lazor-rev4-sku0", "qcom,sc7180"
45 - "google,lazor", "qcom,sc7180"
46
47 Then depthcharge_ will pick the first device tree even though
48 "google,lazor-rev4-sku0" was the second compatible listed in that device tree.
49 This is because it is a more specific compatible than "google,lazor".
50
51 It should be noted that depthcharge_ does not have any smarts to try to
52 match board or SKU revisions that are "close by". That is to say that
53 if depthcharge_ knows it's on "rev4" of a board but there is no "rev4"
54 device tree then depthcharge_ *won't* look for a "rev3" device tree.
55
56 In general when any significant changes are made to a board the board
57 revision number is increased even if none of those changes need to
58 be reflected in the device tree. Thus it's fairly common to see device
59 trees with multiple revisions.
60
61 It should be noted that, taking into account the above system that
62 depthcharge_ has, the most flexibility is achieved if the device tree
63 supporting the newest revision(s) of a board omits the "-rev{REV}"
64 compatible strings. When this is done then if you get a new board
65 revision and try to run old software on it then we'll at pick the
66 newest device tree we know about.
67
68 .. _depthcharge: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/depthcharge/
69 .. _`FIT Image`: https://doc.coreboot.org/lib/payloads/fit.html
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.