lkml.org 
[lkml]   [2022]   [May]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [PATCH v2 1/4] dt-bindings: Document how Chromebooks with depthcharge boot
    On Fri, May 13, 2022 at 09:59:17AM -0700, Douglas Anderson wrote:
    > 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>

    Thanks!

    a few nits below

    > ---
    >
    > Changes in v2:
    > - ("Document how Chromebooks with depthcharge boot") new for v2.
    >
    > .../devicetree/chromebook-boot-flow.rst | 63 +++++++++++++++++++
    > 1 file changed, 63 insertions(+)
    > create mode 100644 Documentation/devicetree/chromebook-boot-flow.rst
    >
    > diff --git a/Documentation/devicetree/chromebook-boot-flow.rst b/Documentation/devicetree/chromebook-boot-flow.rst
    > new file mode 100644
    > index 000000000000..84aeb0a17ee4
    > --- /dev/null
    > +++ b/Documentation/devicetree/chromebook-boot-flow.rst
    > @@ -0,0 +1,63 @@
    > +.. SPDX-License-Identifier: GPL-2.0
    > +
    > +======================================
    > +Chromebook Boot Flow
    > +======================================
    > +
    > +Most recent Chromebooks that use device tree boot using the opensource

    s/using/are using/

    > +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 may use a slightly different list that may

    nit: first 'may' isn't really needed, since this is about 'some' Chromebooks
    whose list 'may' differ in certain ways.

    > +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 that depthcharge _won't_ look for a "rev3" device tree.

    s/that/then/

    > +
    > +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 the
    > +depthcharge has, the most flexibility is achieved if the device tree

    s/the depthcharge/depthcharge/

    > +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.
    > \ No newline at end of file
    > --
    > 2.36.0.550.gb090851708-goog
    >

    \
     
     \ /
      Last update: 2022-05-13 20:43    [W:4.333 / U:0.600 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site