All of lore.kernel.org
 help / color / mirror / Atom feed
From: Douglas Anderson <dianders@chromium.org>
To: Rob Herring <robh+dt@kernel.org>,
	Bjorn Andersson <bjorn.andersson@linaro.org>
Cc: Matthias Kaehlcke <mka@chromium.org>,
	Alexandru M Stan <amstan@chromium.org>,
	patches@lists.linux.dev, linux-arm-msm@vger.kernel.org,
	Julius Werner <jwerner@chromium.org>,
	Andy Gross <agross@kernel.org>,
	Stephen Boyd <swboyd@chromium.org>,
	Krzysztof Kozlowski <krzk+dt@kernel.org>,
	Rajendra Nayak <quic_rjendra@quicinc.com>,
	"Joseph S . Barrera III" <joebar@chromium.org>,
	devicetree@vger.kernel.org,
	Douglas Anderson <dianders@chromium.org>,
	Jonathan Corbet <corbet@lwn.net>,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH v4 1/5] dt-bindings: Document how Chromebooks with depthcharge boot
Date: Fri, 20 May 2022 14:38:41 -0700	[thread overview]
Message-ID: <20220520143502.v4.1.I71e42c6174f1cec17da3024c9f73ba373263b9b6@changeid> (raw)

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 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
+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
+newest device tree we know about.
+
+.. _depthcharge: https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform/depthcharge/
+.. _`FIT Image`: https://doc.coreboot.org/lib/payloads/fit.html
-- 
2.36.1.124.g0e6072fb45-goog


             reply	other threads:[~2022-05-20 21:38 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-05-20 21:38 Douglas Anderson [this message]
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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220520143502.v4.1.I71e42c6174f1cec17da3024c9f73ba373263b9b6@changeid \
    --to=dianders@chromium.org \
    --cc=agross@kernel.org \
    --cc=amstan@chromium.org \
    --cc=bjorn.andersson@linaro.org \
    --cc=corbet@lwn.net \
    --cc=devicetree@vger.kernel.org \
    --cc=joebar@chromium.org \
    --cc=jwerner@chromium.org \
    --cc=krzk+dt@kernel.org \
    --cc=linux-arm-msm@vger.kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mka@chromium.org \
    --cc=patches@lists.linux.dev \
    --cc=quic_rjendra@quicinc.com \
    --cc=robh+dt@kernel.org \
    --cc=swboyd@chromium.org \
    --subject='Re: [PATCH v4 1/5] dt-bindings: Document how Chromebooks with depthcharge boot' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

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.