[PATCH v2 3/3] RFC: doc: Add documentation about devicetree usage

Fri Sep 3 10:53:43 CEST 2021

Hi,

On Mon, 30 Aug 2021 at 10:15, Tom Rini <trini at konsulko.com> wrote:
>
> On Mon, Aug 30, 2021 at 05:14:53PM +0200, Heinrich Schuchardt wrote:
> >
> >
> > On 8/30/21 4:48 PM, Tom Rini wrote:
> > > On Mon, Aug 30, 2021 at 04:30:55PM +0200, Heinrich Schuchardt wrote:
> > > >
> > > >
> > > > On 8/28/21 6:46 PM, Simon Glass wrote:
> > > > > At present some of the ideas and techniques behind devicetree in U-Boot
> > > > > are assumed, implied or unsaid. Add some documentation to cover how
> > > > > devicetree is build, how it can be modified and the rules about using
> > > > > the various CONFIG_OF_... options.
> > >
> > > I feel like I should emphasize that this is "document what we have
> > > today" at least as much, if not more-so, than "document what we want to
> > > move to tomorrow".
> > >
> > > In that this highlights some design disagreements that need to be
> > > settled, good.  But lets perhaps start separate threads on those areas?
> > >
> > > > > Signed-off-by: Simon Glass <sjg at chromium.org>
> > > > > ---
> > > > >
> > > > > Changes in v2:
> > > > > - Fix typos per Sean (thank you!) and a few others
> > > > > - Add a 'Use of U-Boot /config node' section
> > > > > - Drop mention of dm-verity since that actually uses the kernel cmdline
> > > > > - Explain that OF_BOARD will still work after these changes (in
> > > > >     'Once this bug is fixed...' paragraph)
> > > > > - Expand a bit on the reason why the 'Current situation' is bad
> > > > > - Clarify in a second place that Linux and U-Boot use the same devicetree
> > > > >     in 'To be clear, while U-Boot...'
> > > > > - Expand on why we should have rules for other projects in
> > > > >     'Devicetree in another project'
> > > > > - Add a comment as to why devicetree in U-Boot is not 'bad design'
> > > > > - Reword 'in-tree U-Boot devicetree' to 'devicetree source in U-Boot'
> > > > > - Rewrite 'Devicetree generated on-the-fly in another project' to cover
> > > > >     points raised on v1
> > > > > - Add 'Why does U-Boot have its nodes and properties?'
> > > > > - Add 'Why not have two devicetrees?'
> > > > >
> > > > >    doc/develop/index.rst              |   1 +
> > > > >    doc/develop/package/devicetree.rst | 563 +++++++++++++++++++++++++++++
> > > > >    doc/develop/package/index.rst      |   1 +
> > > > >    3 files changed, 565 insertions(+)
> > > > >    create mode 100644 doc/develop/package/devicetree.rst
> > > > >
> > > > > diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> > > > > index 83c929babda..d5ad8f9fe53 100644
> > > > > --- a/doc/develop/index.rst
> > > > > +++ b/doc/develop/index.rst
> > > > > @@ -36,6 +36,7 @@ Packaging
> > > > >       :maxdepth: 1
> > > > >
> > > > >       package/index
> > > > > +   package/devicetree
> > > > >
> > > > >    Testing
> > > > >    -------
> > > > > diff --git a/doc/develop/package/devicetree.rst b/doc/develop/package/devicetree.rst
> > > > > new file mode 100644
> > > > > index 00000000000..d922d3f87ae
> > > > > --- /dev/null
> > > > > +++ b/doc/develop/package/devicetree.rst
> > > > > @@ -0,0 +1,563 @@
> > > > > +.. SPDX-License-Identifier: GPL-2.0+
> > > > > +
> > > > > +Updating the devicetree
> > > > > +=======================
> > > > > +
> > > > > +U-Boot uses devicetree for runtime configuration and storing required blobs or
> > > > > +any other information it needs to operate. It is possible to update the
> > > > > +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.
> > > > > +
> > > > > +
> > > > > +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.
> > > > > +
> > > > > +
> > > > > +Current situation (August 2021)
> > > > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > > > +
> > > > > +As an aside, at present U-Boot allows `CONFIG_DEFAULT_DEVICE_TREE` to be empty,
> > > > > +e.g. if `CONFIG_OF_BOARD` or `CONFIG_OF_PRIOR_STAGE` are used. This has
> > > > > +unfortunately created an enormous amount of confusion and some wasted effort.
> > > > > +This was not intended and this bug will be fixed soon.
> > > > > +
> > > > > +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
> > > > > +
> > > > > +- 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 linst, this
> > > > > +  was only discovered after weeks of discussion and confusion
> > > > > +
> > > > > +- 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.
> > > > > +
> > > > > +Specifically on the changes in U-Boot:
> > > > > +
> > > > > +- `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
> > > > > +- `CONFIG_OF_PRIOR_STAGE` was added in bcm_patch_ as part of a larger Broadcom
> > > > > +  change with a tag indicating it only affected one board, so the change in
> > > > > +  behaviour was not noticed at the time. It has since been used by RISC-V qemu
> > > > > +  boards.
> > > > > +
> > > > > +Once this bug is fixed, CONFIG_OF_BOARD and CONFIG_OF_PRIOR_STAGE will override
> > > > > +(at runtime) the devicetree 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
> > > > > +accept its devicetree from another source.
> > > > > +
> > > > > +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.
> > > >
> > > > For many boards we lag far behind Linux' device-tree.
> > >
> > > Which is a huge problem that needs to be fixed.  The intention has never
> > > been to "commit and forget".
> > >
> > > [snip]
> > > > > +it. For example ARM's Trusted Firmware A (`TF-A`_) may have a devicetree that it
> > > > > +passes to U-Boot. This overrides any devicetree build by U-Boot. When packaging
> > > > > +the firmware, the U-Boot devicetree may in fact be left out if it can be
> > > > > +guaranteed that it will receive one from another project.
> > > > > +
> > > > > +In this case, the devicetree in the other project must track U-Boot's use of
> > > > > +device tree, for the following reasons:
> > > >
> > > > Currently it is Linux that sets the standards not U-Boot.
> > >
> > > Well no, Linux isn't supposed to set "the standard" here either.  It's
> > > OS-agnostic.
> > >
> > > > U-Boot can apply an overlay to the devicetree provided by the prior boot
> > > > stage. We should not try to force any U-Boot specific stuff onto other
> > > > projects.
> > >
> > > We should, when applicable, submit our bindings upstream just like any
> > > other project.  We also want to make sure that when we do so, we hold
> > > ourselves to a high standard.
> >
> > What would you consider upstream for compatible( "u-boot,*" )?
>
> As I believe Simon is the main author of most of them, I'll let him
> chime in here as well.  But I suspect things like "u-boot,bootcount*"
> are a good example of something to polish and push upstream.

I was the author of some of them but I haven't counted. I tried to
document all of the things I could find. I actually wonder if we
should have a 'u-boot,config' node and then have properties without
the 'u-boot,' prefix, to reduce the size.

>
> In the same vein as to how mtd partitions are valid in device trees, our
> binding for where environment is stored on MMC is likely another
> candidate.
>
> > Even if we upstream the binding to some global list of binding I think
> > U-Boot still should provide an overlay with this content.

What is an overlay? Do you mean the u-boot.dtsi files we already have,
or a separate repo, or a subdir in the linux dts dirs, or a devicetree
.dto file, or something else? Once I understand what you are asking
for I might have an opinion, but I went through most of it in the
patch.

>
> Depending if we have stuff that both we need and can't reasonably
> suggest moving upstream, sure.

Regards,
Simon