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

[Heinrich Schuchardt]

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,*" )?
Even if we upstream the binding to some global list of binding I think
U-Boot still should provide an overlay with this content.

Best regards

Heinrich

>
>>> +- U-Boot only has one devicetree. See `Why not have two devicetrees?`_.
>>> +- For a consistent firmware build, decisions made in early stages should be
>>> +  communicated to later ones at runtime. For example, if the serial console is
>>> +  enabled in an early stage, it should be enabled in U-Boot too.
>>> +- U-Boot is quite capable of managing its own copy of the devicetree. If
>>> +  another project wants to bypass this (often for good reason), it is reasonable
>>> +  that it should take on the (fairly small) requirements that U-Boot features
>>> +  that rely on devicetree are still available
>>> +- The point here is not that *U-Boot needs this extra node*, or *U-Boot needs
>>> +  to have this public key*. These features are present in U-Boot in service of
>>> +  the entire firmware system. If the U-Boot features are used, but cannot be
>>> +  supported in the normal way, then there is pressure to implement these
>>> +  features in other ways. In the end, we would have a different mechanism for
>>> +  every other project that uses U-Boot. This introduces duplicate ways of doing
>>> +  the same thing, needlessly increases the complexity of the U-Boot source code,
>>> +  forces authors to consider parallel implementations when writing new features,
>>> +  makes U-Boot harder to test, complicates documentation and confuses the
>>> +  runtime flow of U-Boot. If every board did things its own way rather than
>>> +  contributing to the common code, U-Boot would lose a lot of its cross-platform
>>> +  value.
>>
>> This paragraph is incomprehensible for me.
>>
>> If both the prior boot stage and U-Boot comply to the standards set by
>> Linux we are fine. Any U-Boot quirks should be kept out of other projects.
>
> It's not the "Linux" device tree.  It's the device tree for the system.
>