[PATCH v7 01/31] doc: Add documentation about devicetree usage

[Tom Rini]

On Mon, Dec 06, 2021 at 05:11:39PM -0700, Simon Glass wrote:

[snip]
> +Updating the devicetree
> +=======================

The first thing here is that the subject says dt usage, but the file is
dt_update and starts out talking about updates, not usage.  So there's
not a great place for my next comment, in reply to this patch.  The
second thing is I've already gotten one novel written so far, and I've
got more comments on the rest of the document, so I'm splitting this
reply up.

What this seems to miss it that the intention of device tree usage in
U-Boot is similar to the usage of device trees in an OS.  That is to
allow for the run-time binary to be data-driven and determine what
peripherals or even SoC is present at run-time rather than build time.
A sufficiently abstracted build can support not just rev A vs rev B of a
given hardware platform but platform A and platform B using the same SoC
but different designs and peripherals or platform A and platform C where
there are different SoCs present entirely.

> +U-Boot uses devicetree for runtime configuration and storing required blobs or
> +any other information it needs to operate. This is called the 'control'
> +devicetree since it controls U-Boot. It is possible to update the control
> +devicetree separately from actually building U-Boot. This provides a good degree
> +of control and flexibility for firmware that uses U-Boot in conjunction with
> +other project.
> +
> +There are many reasons why it is useful to modify the devicetree after building
> +it:
> +
> +- Configuration can be changed, e.g. which UART to use
> +- A serial number can be added
> +- Public keys can be added to allow image verification
> +- Console output can be changed (e.g. to select serial or vidconsole)
> +
> +This section describes how to work with devicetree to accomplish your goals.
> +
> +See also :doc:`../devicetree/control` for a basic summary of the available
> +features.

This implies that the control device tree is separate from the OS device
tree.  You certainly can't put "blobs" in to the device tree that will
be in the upstream dts repository.  So this needs to be clarified /
expanded more to be clear we aren't talking about the OS device tree but
rather we're using the device tree format to define what we're making as
an output, with binman, and spell out binman, and probably link to those
docs too.

> +Devicetree source
> +-----------------
> +
> +Every board in U-Boot must include a devicetree sufficient to build and boot
> +that board on suitable hardware (or emulation). This is specified using the
> +`CONFIG DEFAULT_DEVICE_TREE` option.

No, this is wrong.  As has been explained over and over, a device tree
that can _boot_ the hardware is not always statically possible.  I'll go
further and note that in the cases where you cannot do this, you _need_
to do what the platform specific method of modifying the device tree is,
in order to do that, in order to test things.  But this really feels
like making the doorway to later on say "Now we can have U-Boot override
the device tree for everyone" rather than just developer developing
and testing things locally.

> +Current situation (October 2021)
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +As an aside, at present U-Boot allows `CONFIG_DEFAULT_DEVICE_TREE` to be empty,
> +e.g. if `CONFIG_OF_BOARD` is used. This has unfortunately created an enormous
> +amount of confusion and some wasted effort. This was not intended. Support for
> +an empty `CONFIG_DEFAULT_DEVICE_TREE` will be dropped soon.

It's intentional and required.  When you support more than one distinct
SoC and a prior stage that takes care of enough low level configuration
that, just like an OS, U-Boot can be data-driven rather than hard-coded,
it is NOT possible to include a default that will work for everyone.  So
it doesn't make sense to include a default that will fail for some.

> +Some of the problems created are:
> +
> +- It is not obvious that the devicetree is coming from another project
> +
> +- There is no way to see even a sample devicetree for these platform in U-Boot,
> +  so it is hard to know what is going on, e.g. which devices are typically
> +  present


Board documentation has been sporadic at best historically but thanks to
Heinrich and others, we've seen huge improvements more recently.
Getting information such as this included would make life easier.

> +- The other project may not provide a way to support U-Boot's requirements for
> +  devicetree, such as the /config node. Note: On the U-Boot mailing list, this
> +  was only discovered after weeks of discussion and confusion

In that there is a problem there it's because we need to document the
binding (which yes, you're doing and it's time to push again on Rob
about) and then it's on the board to update their device tree.  Not on
U-Boot to provide this information.

> +- For QEMU specifically, consulting two QEMU source files is required, for which
> +  there are no references in U-Boot documentation. The code is generating a
> +  devicetree, but it is not clear what controls affect this generation.

QEMU generates a device tree, we consume the device tree.  Device trees
are generated against the bindings.  If a property needs to be present,
it needs to be in the bindings.  If a board won't populate the binding,
it won't get the feature supported.

> +Specifically on the changes in U-Bootm `CONFIG_OF_BOARD` was added in
> +rpi_patch_ for Raspberry Pi, which does have an in-tree devicetree, but this
> +feature has since been used for boards that don't

Yes, historically there's been some funny stuff with Pi and
unfortunately we've not handled things as best as could be.  We really
should just have rpi_arm64 and see if we can do an rpi_arm32, both of
which rely on the provided device tree.

> +Once this bug is fixed, CONFIG_OF_BOARD will override (at runtime) the
> +evicetree suppled with U-Boot, but will otherwise use CONFIG_OF_SEPARATE for the
> +in-tree build. So these two will become options, moving out of the 'choice' in
> +`dts/Kconfig`.
> +
> +This means that there is a basic devicetree build in the U-Boot tree, for
> +build-testing, consistency and documentation purposes, but at runtime U-Boot can

No.  We already accept that for build-testing binaries won't be
functional.  There's huge swaths of the codebase today that print some
form of "this builds but will not run".  Device trees aren't an
exception to that.  For documentation purposes, boards should have more
extensive documentation than they do today and can / should point to
where their device trees come from as part of that.  Or at least point
to their documentation that covers such topics.

> +accept its devicetree from another source. The in-tree devicetree may contain
> +U-Boot-specific features (in u-boot*.dtsi files) and this may prove useful for
> +the other project, so it can ensure that U-Boot functions correctly and supports
> +all its expected features.

Frankly, I think I made a mistake with -u-boot.dtsi as it let us go for
too long without getting our bindings upstream, so we got very far down
the road of requiring properties that would only be present in our
generated device tree.  This was really only noticeable as a problem on
Pi where we kept having to do things to deal with "provided device tree
got updated, we need to something-something to keep working / not break
the OS now".

> +To be clear, while U-Boot has its own copy of the devicetree source for each
> +board, this must match the Linux source, perhaps with some u-boot.dtsi
> +additions. The intent here is not to create a separate binding, just to provide
> +a representative devicetree in U-Boot.

In that it can be helpful to not have to swap to another project to look
at files, and that I'm sure "git submodules" is out of the question for
us, we would first need to re-organize our device tree structure so that
it's a clear import of Linux's arch/${ARCH}/boot/dts ->
something/${ARCH}/dts in U-Boot, and deal with ARMv8+ here being under
ARCH=arm but ARCH=arm64 in Linux.  That would not be where any
-u-boot.dtsi files live.

But I don't see it as our role to try and be where all the device trees
that want to live somewhere public live.  There's another projects and
people trying to sort that out, for quite some time.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20211207/3f9f9dd6/attachment.sig>