patches.lists.linux.dev archive mirror
 help / color / mirror / Atom feed
* [PATCH v3 1/5] dt-bindings: Document how Chromebooks with depthcharge boot
@ 2022-05-19 23:51 Douglas Anderson
  2022-05-19 23:51 ` [PATCH v3 2/5] dt-bindings: arm: qcom: Mention that Chromebooks use a different scheme Douglas Anderson
                   ` (4 more replies)
  0 siblings, 5 replies; 7+ messages in thread
From: Douglas Anderson @ 2022-05-19 23:51 UTC (permalink / raw)
  To: Rob Herring, Bjorn Andersson
  Cc: Stephen Boyd, linux-arm-msm, Matthias Kaehlcke, Andy Gross,
	Alexandru M Stan, Joseph S . Barrera III, patches, devicetree,
	Rajendra Nayak, Krzysztof Kozlowski, Julius Werner,
	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 <dianders@chromium.org>
---
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
objections?

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       | 63 +++++++++++++++++++
 1 file changed, 63 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..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
+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 compile time.
+- Board revision number, read from GPIO strappings at boot time.
+- 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.
+
+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
+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
+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
+reasonable device tree, we'll pick the exact right one.
-- 
2.36.1.124.g0e6072fb45-goog


^ permalink raw reply related	[flat|nested] 7+ messages in thread
end of thread, other threads:[~2022-05-20  0:17 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-05-19 23:51 [PATCH v3 1/5] dt-bindings: Document how Chromebooks with depthcharge boot Douglas Anderson
2022-05-19 23:51 ` [PATCH v3 2/5] dt-bindings: arm: qcom: Mention that Chromebooks use a different scheme Douglas Anderson
2022-05-20  0:01   ` Stephen Boyd
2022-05-19 23:51 ` [PATCH v3 3/5] dt-bindings: arm: qcom: Add sc7180 Chromebook board bindings Douglas Anderson
2022-05-19 23:51 ` [PATCH v3 4/5] dt-bindings: arm: qcom: Add / fix sc7280 " Douglas Anderson
2022-05-19 23:51 ` [PATCH v3 5/5] dt-bindings: arm: qcom: Add more sc7180 Chromebook " Douglas Anderson
2022-05-20  0:17 ` [PATCH v3 1/5] dt-bindings: Document how Chromebooks with depthcharge boot Stephen Boyd

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).