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. -- Tom
signature.asc
Description: PGP signature
