On 9/10/21 2:34 PM, Tom Rini wrote:
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 <s...@chromium.org>
Reviewed-by: Marcel Ziswiler <marcel.ziswi...@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 ?
+(at runtime) the devicetree supplied 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`. To be clear, the devicetree in the
+U-Boot tree may be largely for documentation and build-testing purposes, if at
+runtime the devicetree if provided by another project. But the in-tree
+devicetree is packaged with U-Boot as a fallback if it does not get one from a
+prior stage at runtime. This does not create two devicetrees that need to be
+merged, or anything like that. If the prior stage provides one, it is used as
+is, with the one provided by U-Boot being ignored.
+
+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.
The incoming devicetree may not contain any U-Boot specific stuff. So
don't you need the buildtime devicetree for all of this information at
runtime? E.g. you were requesting to move certificate blobs into the
build-time devicetree.
This is wrong because (a) no, there's no functional reason the prior
stage cannot populate / be pre-populated with what we need and (b) we're
documenting what we have today.
The problem is not functional but organizational. The prior boot stage
may be burnt into PROM while U-Boot is on an SD-card.
Don't expect that on a board where you could install EDK II or U-Boot or
anything else the prior boot stage cares about U-Boot.
How could a prior boot stage possibly know years ahead what is not even
yet supported in U-Boot when the prior boot stage is created?
Best regards
Heinrich
