[PATCH] doc: Add documentation about devicetree usage

Sun Aug 29 16:44:45 CEST 2021

On Sun, Aug 29, 2021 at 10:19:53AM +0200, Mark Kettenis wrote:
> > From: Simon Glass <sjg at chromium.org>
> > Date: Sat, 28 Aug 2021 20:07:27 -0600
> > 
> > Hi Bin,
> > 
> > On Sat, 28 Aug 2021 at 19:29, Bin Meng <bmeng.cn at gmail.com> wrote:
> > >
> > > Hi Simon,
> > >
> > > On Sun, Aug 29, 2021 at 12:45 AM Simon Glass <sjg at chromium.org> wrote:
> > > >
> > > > Hi Bin,
> > > >
> > > > On Sat, 28 Aug 2021 at 07:15, Bin Meng <bmeng.cn at gmail.com> wrote:
> > > > >
> > > > > Hi Simon,
> > > > >
> > > > > On Sat, Aug 28, 2021 at 11:23 AM Simon Glass <sjg at chromium.org> 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>
> > > > > > ---
> > > > > >
> > > > > >  doc/develop/index.rst              |   1 +
> > > > > >  doc/develop/package/devicetree.rst | 315 +++++++++++++++++++++++++++++
> > > > > >  doc/develop/package/index.rst      |   1 +
> > > > > >  3 files changed, 317 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..fccbb182f3e
> > > > > > --- /dev/null
> > > > > > +++ b/doc/develop/package/devicetree.rst
> > > > > > @@ -0,0 +1,315 @@
> > > > > > +.. 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. Specifically:
> > > > > > +
> > > > > > +- `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`
> > > > > > +
> > > > > > +Offending boards are:
> > > > > > +
> > > > > > +- bcm7260
> > > > > > +- bcm7445
> > > > > > +- qemu_arm64
> > > > > > +- qemu_arm
> > > > > > +- qemu-ppce500
> > > > > > +- qemu-riscv32
> > > > > > +- qemu-riscv32_smode
> > > > > > +- qemu-riscv64
> > > > > > +- qemu-riscv64_smode
> > > > > > +
> > > > > > +All of these need to have a devicetree added in-tree. This is targeted to be
> > > > > > +fixed in the 2022.01 release.
> > > > >
> > > > > Do you have some idea of how to support the QEMU case, if not using
> > > > > CONFIG_OF_PRIOR_STAGE?
> > > >
> > > > To be clear, I am not planning to remove this option. It will still work.
> > > >
> > > > But I do want to have an in-tree devicetree for all boards, and
> > > > someone will need to update qemu to support adding U-Boot
> > > > nodes/properties. It always has an array of options controlling what
> > > > it presents to BIOS/UEFI, for example, so this should not be too
> > > > controversial.
> > >
> > > I think there is some misunderstanding.
> > >
> > > Adding U-Boot nodes/properties is not a problem for QEMU, but the
> > > thing is that these QEMU targets don't require U-Boot specific
> > > nodes/properties. It's just that QEMU will generate the DTB on the fly
> > > based on different command-line options, so the DTB is dynamic and we
> > > can't hardcode one in the U-Boot tree.
> > 
> > That's fine, but I do want some sort of sample in the tree, like we
> > have for qemu-x86 and others. For some reason ARM and RISC-V don't
> > have one.
> > 
> > Also, QEMU needs a way to add properties and nodes that are specific
> > to U-Boot, since at present there is no way at all to pass these
> > through (/config node, u-boot,dm-xxx tags, etc.).
> 
> I suppose some of the /config stuff could be nice and that the device
> tree is indeed the most appropriate way to pass runtime options from
> QEMU to U-Boot.  But I'd say U-Boot should still work (with reasonable
> defaults) if no U-Boot specific options are present in the device
> tree.
> 
> My understanding is that the u-boot,dm-xxx tags are for SPL.  It seems
> that for most scenarios having where there is some prior firmware that
> passes a device tree, SPL isn't used.  That certainly is the case for
> QEMU, Raspberry Pi and my Apple M1 work.

This is key, for moving forward.  We need to be able to function wholly
and correctly with a device tree we are given by whatever stars "us"
off.  When we talk about QEMU, we need to keep in mind what QEMU is
being used for, as the use cases.   I feel like QEMU-as-QEMU really is
to enable CI and perhaps enable debug/development workflows.
QEMU-as-hardware (SiFive from Bin's recent patch, sabrelite that QEMU
6.1.0 supports, integrator, malta like we do today, and so on) should be
"let us act like it's the real hardware".  So if we're expecting a
device tree to have X in it, we need to work with whatever the relevant
upstreams are to have it.

-- 
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/20210829/3202baff/attachment.sig>