Hi, On Mon, 30 Aug 2021 at 10:15, Tom Rini <tr...@konsulko.com> wrote: > > On Mon, Aug 30, 2021 at 05:14:53PM +0200, Heinrich Schuchardt wrote: > > > > > > 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 <s...@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,*" )? > > As I believe Simon is the main author of most of them, I'll let him > chime in here as well. But I suspect things like "u-boot,bootcount*" > are a good example of something to polish and push upstream.
I was the author of some of them but I haven't counted. I tried to document all of the things I could find. I actually wonder if we should have a 'u-boot,config' node and then have properties without the 'u-boot,' prefix, to reduce the size. > > In the same vein as to how mtd partitions are valid in device trees, our > binding for where environment is stored on MMC is likely another > candidate. > > > Even if we upstream the binding to some global list of binding I think > > U-Boot still should provide an overlay with this content. What is an overlay? Do you mean the u-boot.dtsi files we already have, or a separate repo, or a subdir in the linux dts dirs, or a devicetree .dto file, or something else? Once I understand what you are asking for I might have an opinion, but I went through most of it in the patch. > > Depending if we have stuff that both we need and can't reasonably > suggest moving upstream, sure. Regards, Simon
