All of
 help / color / mirror / Atom feed
* [PATCH v4 1/5] dt-bindings: Document how Chromebooks with depthcharge boot
@ 2022-05-20 21:38 Douglas Anderson
  2022-05-20 21:38 ` [PATCH v4 2/5] dt-bindings: arm: qcom: Mention that Chromebooks use a different scheme Douglas Anderson
                   ` (4 more replies)
  0 siblings, 5 replies; 16+ messages in thread
From: Douglas Anderson @ 2022-05-20 21:38 UTC (permalink / raw)
  To: Rob Herring, Bjorn Andersson
  Cc: Matthias Kaehlcke, Alexandru M Stan, patches, linux-arm-msm,
	Julius Werner, Andy Gross, Stephen Boyd, Krzysztof Kozlowski,
	Rajendra Nayak, Joseph S . Barrera III, devicetree,
	Douglas Anderson, Jonathan Corbet, linux-doc, linux-kernel

This documents how many Chromebooks pick the device tree that will be
passed to the OS and can help understand the revisions / SKUs listed
as the top-level "compatible" in many Chromebooks.

Signed-off-by: Douglas Anderson <>
In my opinion this could land through the Qualcomm dts64 tree, mostly
because I want to land bindings patches in that tree that refer to
it. Since it's a new file it seems like there ought to be few

Changes in v4:
- Add reference to depthcharge and FIT Image.
- A few rst syntax fixups found by using a different rst preview.
- Updated wording as per Stephen.

Changes in v3:
- Fix up typos as per Matthias.
- Move under Documentation/arm/google/ as per Krzysztof.
- Add missing newline at end of file.

Changes in v2:
- ("Document how Chromebooks with depthcharge boot") new for v2.

 .../arm/google/chromebook-boot-flow.rst       | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 Documentation/arm/google/chromebook-boot-flow.rst

diff --git a/Documentation/arm/google/chromebook-boot-flow.rst b/Documentation/arm/google/chromebook-boot-flow.rst
new file mode 100644
index 000000000000..36da77684bba
--- /dev/null
+++ b/Documentation/arm/google/chromebook-boot-flow.rst
@@ -0,0 +1,69 @@
+.. 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
+Image`_ which contains an OS image as well as a collection of device trees. It
+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 depthcharge_ compile time. This is $(BOARD) below.
+- Board revision number, determined at runtime (perhaps by reading GPIO
+  strappings, perhaps via some other method). This is $(REV) below.
+- SKU number, read from GPIO strappings at boot time. This is $(SKU) below.
+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.
+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 string falls within a device tree's root compatible string array.
+As an example, if we're on board "lazor", rev 4, SKU 0 and we have two device
+- "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
+newest device tree we know about.
+.. _depthcharge:
+.. _`FIT Image`:

^ permalink raw reply related	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2022-06-27 20:03 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-05-20 21:38 [PATCH v4 1/5] dt-bindings: Document how Chromebooks with depthcharge boot Douglas Anderson
2022-05-20 21:38 ` [PATCH v4 2/5] dt-bindings: arm: qcom: Mention that Chromebooks use a different scheme Douglas Anderson
2022-05-22  7:54   ` Krzysztof Kozlowski
2022-05-20 21:38 ` [PATCH v4 3/5] dt-bindings: arm: qcom: Add sc7180 Chromebook board bindings Douglas Anderson
2022-05-22  7:57   ` Krzysztof Kozlowski
2022-05-23 16:16     ` Doug Anderson
2022-05-24  9:34       ` Krzysztof Kozlowski
2022-05-24 23:00         ` Doug Anderson
2022-05-20 21:38 ` [PATCH v4 4/5] dt-bindings: arm: qcom: Add / fix sc7280 " Douglas Anderson
2022-06-22  8:27   ` Krzysztof Kozlowski
2022-06-22 13:51     ` Doug Anderson
2022-05-20 21:38 ` [PATCH v4 5/5] dt-bindings: arm: qcom: Add more sc7180 Chromebook " Douglas Anderson
2022-05-22  8:01   ` Krzysztof Kozlowski
2022-05-23 16:19     ` Doug Anderson
2022-06-01 23:26       ` Rob Herring
2022-06-27 20:02 ` [PATCH v4 1/5] dt-bindings: Document how Chromebooks with depthcharge boot Bjorn Andersson

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.