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

Tom Rini trini at konsulko.com
Wed Oct 13 17:39:05 CEST 2021 

[ Splitting my replies up ]
On Wed, Oct 13, 2021 at 04:45:50PM +0200, François Ozog wrote:
> Le mer. 13 oct. 2021 à 15:30, Tom Rini <trini at konsulko.com> a écrit :
> 
> > On Wed, Oct 13, 2021 at 03:12:02PM +0200, François Ozog wrote:
> > > Le mer. 13 oct. 2021 à 14:55, Tom Rini <trini at konsulko.com> a écrit :
> > >
> > > > On Wed, Oct 13, 2021 at 10:15:02AM +0200, François Ozog wrote:
> > > > > Le sam. 18 sept. 2021 à 15:18, Tom Rini <trini at konsulko.com> a
> > écrit :
> > > > >
> > > > > > On Sat, Sep 18, 2021 at 03:38:45AM -0600, Simon Glass wrote:
> > > > > > > Hi,
> > > > > > >
> > > > > > > On Fri, 10 Sept 2021 at 16:44, Tom Rini <trini at konsulko.com>
> > wrote:
> > > > > > > >
> > > > > > > > On Sat, Sep 11, 2021 at 12:09:40AM +0200, Mark Kettenis wrote:
> > > > > > > > > > Date: Fri, 10 Sep 2021 17:17:37 -0400
> > > > > > > > > > From: Tom Rini <trini at konsulko.com>
> > > > > > > > > >
> > > > > > > > > > On Fri, Sep 10, 2021 at 11:12:20PM +0200, Mark Kettenis
> > wrote:
> > > > > > > > > > > > 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.
> > > > > > > > > >
> > > > > > > > > > Thanks for explaining.  Couldn't CONFIG_OF_PRIOR_STAGE be
> > > > > > rewritten as
> > > > > > > > > > an implementation of CONFIG_OF_BOARD, possibly at the same
> > or
> > > > less
> > > > > > > > > > overall code size?  That I think is the potential bug.
> > > > > > > > >
> > > > > > > > > Probably a little bit more code:
> > > > > > > > >
> > > > > > > > > void *
> > > > > > > > > board_fdt_blob_setup(void)
> > > > > > > > > {
> > > > > > > > >     return (void *)(uintptr_t)prior_stage_fdt_address;
> > > > > > > > > }
> > > > > > > >
> > > > > > > > Tiny bit more.  Probably worth doing to make the choices
> > clearer on
> > > > > > > > which to select when?  Bin, Rick, thoughts on this since riscv
> > is
> > > > the
> > > > > > > > main user of CONFIG_OF_PRIOR_STAGE at this point?
> > > > > > >
> > > > > > > Bin, Rick?
> > > > > > >
> > > > > > > What is the prior stage in the RISC-V stage? Could we get it to
> > set
> > > > up
> > > > > > > a bloblist? Then we can add a devicetree in there, with the
> > option to
> > > > > > > add more things in future.
> > > > > >
> > > > > > I'm suggesting we don't need to do anything upstream of us, just
> > rework
> > > > > > things to use the other hook for "provided a DTB by caller, use
> > it", so
> > > > > > that we have a single hook for that.
> > > > >
> > > > > What was the rationale in posting in kernel.org (
> > > > >
> > > >
> > https://lore.kernel.org/all/20211003125134.2.I7733f5a849476e908cc51f0c71b8a594337fbbdf@changeid/
> > > > > ) and not in U-Boot knowing there is still no consensus on the big
> > > > picture ?
> > > >
> > > > Well, because we need to get our bindings reviewed and made official,
> > > > and that looked like a reasonable place and choice to start with? v2
> > > > cc'd a different set of lists, at Rob's suggestion.
> > >
> > > making it “ Official” does not necessarily mean in the Linux DT. What
> > would
> > > you think with a hardware description file that comes with U-Boot,
> >
> > No?  A project-specific binding is only valid within the project.  So
> > unless it's a linux,foo binding it's not "Linux DT", it's generic.  Part
> > of the point in pushing this up for real review is that IF we want to be
> > passed this information then it needs to be a real official and reviewed
> > binding.  And that process in turn meanings convincing other (generally
> > skeptical) people it's a good idea.  And maybe that it should take a
> > more generic approach.
> >
> > > LinuxBoot and EDK2 config options ? No need for Linux to know about those
> > > U-Boot internal config? Why would those U-Boot elements be passed down to
> > > any OS ?
> >
> > I don't see the harm?
> 
> U-Boot per say does not define a standardized contract handover to OS.
> Multiboot, AVB, Linux and UEFi do.

I disagree.  Linux, in general / looking forward, is trying to not have
N ad-hoc per-architecture entry points.  Even as I understand it (and I
might have some of the exact terminology wrong, sorry) on x86_64,
grub/systemd-boot/etc on UEFI systems (the modern, and even not so
modern these days, norm) can set things up such that the kernel is
launched by UEFI.  Just like it would do for Free/Open/NetBSD or
Windows.  That standard defined in parts by UEFI and ACPI where who
shall provide what.  And sometimes that means "here's the standard way
to add some info to the ACPI tables".

I'll admit I don't know how exactly on the x86_64 world information gets
passed around between the secure/non-secure world and all of those other
fun challenge that we're talking about here.

Looking at
https://www.gnu.org/software/grub/manual/multiboot2/multiboot.html it's
certainly written as a specification, but I don't know off-hand how
widely it's used right now.

Assuming AVB in this context means Android Verified Boot, well, I guess
at this point I'm now going to fail to not make this joke:
https://xkcd.com/927/

> It makes sense to expose some stuff
> related to the contract in the DT, added by the relevant “contract manager”
> in U-Boot. Should one want to define further VBE for instance with
> information that is useful to OS, then it make sense to have VBE
> information exposes.
> Exposing information by U-Boot for its own consumption is like an
> information leak: something that is part of a non existing ABI that can
> create bad legacy.

I think Rob's feedback on Simon's thread is helpful here, and the
information in question possibly more belongs strictly under the /chosen
node where this kind of information is already present.  I would
encourage you to chime in on the thread there.

-- 
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/20211013/1ec0cec6/attachment.sig>

More information about the U-Boot mailing list