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

Wed Oct 13 15:12:02 CEST 2021

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.
> > >
> > > --
> > > Tom
> >
> >
> > 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,
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 ? Do you expect to have bootloader specific behavior in distros ?
TF-A makes the binding official and standardized in its own documentation.
U-Boot can and should do the same.

>
>
> > We agreed you would defer the device tree documentation patch you
> proposed
> > because we did not agree on the painted overall picture. So I was
> surprised
> > by your post.
> > I agree standardization of U-Boot bindings is a good thing.
> > Trustedfirnware.org does it internally and U-Boot can get inspiration
> from
> > this.
> >
> https://trustedfirmware-a.readthedocs.io/en/latest/components/cot-binding.html
>
> Note that your example there should also be reviewed and sent upstream
> as the problem is less "U-Boot's config binding isn't documented" but
> more "U-Boot's config binding isn't official".
>
> --
> Tom
>
-- 
François-Frédéric Ozog | *Director Business Development*
T: +33.67221.6485
francois.ozog at linaro.org | Skype: ffozog