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

Mark Kettenis mark.kettenis at xs4all.nl
Fri Sep 10 23:12:20 CEST 2021


> Date: Fri, 10 Sep 2021 08:34:20 -0400
> From: Tom Rini <trini at konsulko.com>
> 
> On Fri, Sep 10, 2021 at 10:38:17AM +0200, Heinrich Schuchardt wrote:
> > 
> > 
> > On 9/9/21 10:10 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.
> > > 
> > > Signed-off-by: Simon Glass <sjg at chromium.org>
> > > Reviewed-by: Marcel Ziswiler <marcel.ziswiler at toradex.com>
> > > ---
> > > 
> > > Changes in v3:
> > > - Fix typos linst suppled receive EFL
> > > - Drop 'and' before 'self-defeating'
> > > - Reword mention of control of QEMU's devicetree generation
> > > - Add mention of dropping CONFIG_OF_BOARD
> > > - Clarify the 'Once this bug is fixed' paragraph a bit
> > > - Expand ways that CONFIG_OF_PRIOR_STAGE can support the U-Boot devicetree
> > > - Add a note at the top explaining that his patch covers 'now', not 'future'
> > > - Add note 'Note: Some boards use a devicetree in U-Boot which does not match'
> > > 
> > > 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 | 583 +++++++++++++++++++++++++++++
> > >   doc/develop/package/index.rst      |   1 +
> > >   3 files changed, 585 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..b1bd310d906
> > > --- /dev/null
> > > +++ b/doc/develop/package/devicetree.rst
> > > @@ -0,0 +1,583 @@
> > > +.. SPDX-License-Identifier: GPL-2.0+
> > > +
> > > +Updating the devicetree
> > > +=======================
> > > +
> > > +Note: This documentation describes how things are today, mostly, with some
> > > +mention of things that need to be fixed. It is not intended to point the way to
> > > +what might be done in the future. That should be the subject of discussions on
> > > +the mailing list.
> > > +
> > > +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 list, 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, with some control from command-line args, but it is not clear
> > > +  how to add properties required by U-Boot.
> > > +
> > > +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.
> > > +
> > > +Note: It is not clear that we actually need both of these. Possibly
> > > +`CONFIG_OF_BOARD` can be dropped.
> > > +
> > > +Once this bug is fixed, CONFIG_OF_BOARD and CONFIG_OF_PRIOR_STAGE will override
> > 
> > What does "bug" refer to? Above you describe the current design not a bug.
> 
> The bug is that we have two options to provide seemingly the same
> functionality.  Is there a functional difference between CONFIG_OF_BOARD
> and CONFIG_OF_PRIOR_STAGE ?

With CONFIG_OF_BOARD there is a function that returns the pointer to
the DTB, so you can do all sort of things with it.

With CONFIG_OF_PRIOR_STAGE there is a variable that you need to set in
low-level code to point at the DTB and there is a pre-defined function
that returns that pointer.

CONFIG_OF_BOARD is more flexible than CONFIG_OF_PRIOR_STAGE, but if
the only thing you want to do is to pass on a DTB that is passed in a
CPU register to U-Boot then CONFIG_OF_PRIOR_STAGE is probably easier
to use.

I'm not convinced there is a bug here.


More information about the U-Boot mailing list