Quoting Douglas Anderson (2022-05-19 16:51:05)
> diff --git a/Documentation/arm/google/chromebook-boot-flow.rst b/Documentation/arm/google/chromebook-boot-flow.rst
> new file mode 100644
> index 000000000000..92d8a658ceaa
> --- /dev/null
> +++ b/Documentation/arm/google/chromebook-boot-flow.rst
> @@ -0,0 +1,63 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +======================================
> +Chromebook Boot Flow
> +======================================
> +
> +Most recent Chromebooks that use device tree are using the opensource
> +depthcharge bootloader. Depthcharge expects the OS to be packaged as a "FIT
Is there a reference for depthcharge? I guess there's source browser[2] but
I was hoping for some README or something.
> +Image" which contains an OS image as well as a collection of device trees. It
Reference coreboot docs[1]?
> +is up to depthcharge to pick the right device tree from the FIT Image and
> +provide it to the OS.
> +
> +The scheme that depthcharge uses to pick the device tree takes into account
> +three variables:
> +- Board name, specified at compile time.
Which compile time? depthcharge compile time? Also mention "BOARD"
somehow so it corresponds to the list below.
> +- Board revision number, read from GPIO strappings at boot time.
Maybe just say "determined at runtime" as who knows if it may change
from GPIO to something else. Also mention "REV" somehow so it
corresponds to the list below.
> +- SKU number, read from GPIO strappings at boot time.
> +
> +For recent Chromebooks, depthcharge creates a match list that looks like this:
> +- google,$(BOARD)-rev$(REV)-sku$(SKU)
> +- google,$(BOARD)-rev$(REV)
> +- google,$(BOARD)-sku$(SKU)
> +- google,$(BOARD)
> +
> +Note that some older Chromebooks use a slightly different list that may
> +not include sku matching or may prioritize sku/rev differently.
s/sku/SKU/g
> +
> +Note that for some boards there may be extra board-specific logic to inject
> +extra compatibles into the list, but this is uncommon.
> +
> +Depthcharge will look through all device trees in the FIT image trying to
> +find one that matches the most specific compatible. It will then look
> +through all device trees in the FIT image trying to find the one that
> +matches the _second most_ specific compatible, etc.
> +
> +When searching for a device tree, depthcharge doesn't care where the
> +compatible falls within a given device tree. As an example, if we're on
where the compatible string falls within a device tree's root compatible
string array?
> +board "lazor", rev 4, sku 0 and we have two device trees:
> +- "google,lazor-rev5-sku0", "google,lazor-rev4-sku0", "qcom,sc7180"
> +- "google,lazor", "qcom,sc7180"
> +
> +Then depthcharge will pick the first device tree even though
> +"google,lazor-rev4-sku0" was the second compatible listed in that device tree.
> +This is because it is a more specific compatible than "google,lazor".
> +
> +It should be noted that depthcharge does not have any smarts to try to
> +match board or SKU revisions that are "close by". That is to say that
> +if depthcharge knows it's on "rev4" of a board but there is no "rev4"
> +device tree then depthcharge _won't_ look for a "rev3" device tree.
> +
> +In general when any significant changes are made to a board the board
> +revision number is increased even if none of those changes need to
> +be reflected in the device tree. Thus it's fairly common to see device
> +trees with multiple revisions.
> +
> +It should be noted that, taking into account the above system that
> +depthcharge has, the most flexibility is achieved if the device tree
> +supporting the newest revision(s) of a board omits the "-rev{REV}"
> +compatible strings. When this is done then if you get a new board
> +revision and try to run old software on it then we'll at pick the most
then we'll pick the most? These last two sentences confuse me.
> +reasonable device tree. If it turns out that the new revision actually
> +has no device-tree visible changes then we'll not only pick the most
There's 'device tree' and 'device-tree', please pick one, or use a new
one like 'devicetree'.
> +reasonable device tree, we'll pick the exact right one.
[1] https://doc.coreboot.org/lib/payloads/fit.html
[2] https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/depthcharge/
