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
next 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.