70 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3======================================4Chromebook Boot Flow5======================================6 7Most recent Chromebooks that use device tree are using the opensource8depthcharge_ bootloader. Depthcharge_ expects the OS to be packaged as a `FIT9Image`_ which contains an OS image as well as a collection of device trees. It10is up to depthcharge_ to pick the right device tree from the `FIT Image`_ and11provide it to the OS.12 13The scheme that depthcharge_ uses to pick the device tree takes into account14three variables:15 16- Board name, specified at depthcharge_ compile time. This is $(BOARD) below.17- Board revision number, determined at runtime (perhaps by reading GPIO18 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 21For 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 28Note that some older Chromebooks use a slightly different list that may29not include SKU matching or may prioritize SKU/rev differently.30 31Note that for some boards there may be extra board-specific logic to inject32extra compatibles into the list, but this is uncommon.33 34Depthcharge_ will look through all device trees in the `FIT Image`_ trying to35find one that matches the most specific compatible. It will then look36through all device trees in the `FIT Image`_ trying to find the one that37matches the *second most* specific compatible, etc.38 39When searching for a device tree, depthcharge_ doesn't care where the40compatible string falls within a device tree's root compatible string array.41As an example, if we're on board "lazor", rev 4, SKU 0 and we have two device42trees:43 44- "google,lazor-rev5-sku0", "google,lazor-rev4-sku0", "qcom,sc7180"45- "google,lazor", "qcom,sc7180"46 47Then depthcharge_ will pick the first device tree even though48"google,lazor-rev4-sku0" was the second compatible listed in that device tree.49This is because it is a more specific compatible than "google,lazor".50 51It should be noted that depthcharge_ does not have any smarts to try to52match board or SKU revisions that are "close by". That is to say that53if depthcharge_ knows it's on "rev4" of a board but there is no "rev4"54device tree then depthcharge_ *won't* look for a "rev3" device tree.55 56In general when any significant changes are made to a board the board57revision number is increased even if none of those changes need to58be reflected in the device tree. Thus it's fairly common to see device59trees with multiple revisions.60 61It should be noted that, taking into account the above system that62depthcharge_ has, the most flexibility is achieved if the device tree63supporting the newest revision(s) of a board omits the "-rev{REV}"64compatible strings. When this is done then if you get a new board65revision and try to run old software on it then we'll at pick the66newest 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.html70