[PATCH v5 02/26] doc: Add documentation about devicetree usage

[Simon Glass]

Hi François,

On Tue, 26 Oct 2021 at 09:57, François Ozog <francois.ozog at linaro.org> wrote:
>
>
>
> On Tue, 26 Oct 2021 at 17:27, Simon Glass <sjg at chromium.org> wrote:
>>
>> Hi François,
>>
>> On Tue, 26 Oct 2021 at 08:31, François Ozog <francois.ozog at linaro.org> wrote:
>> >
>> > Hi Simon,
>> >
>> > On Tue, 26 Oct 2021 at 02:25, 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.
>> >>

[..]

>> >> +Why not have two devicetrees?
>> >> +-----------------------------
>> >> +
>> >> +Setting aside the argument for restricting U-Boot from having its own nodes and
>> >> +properties, another idea proposed is to have two devicetrees, one for the
>> >> +U-Boot-specific bits (here called `special`) and one for everything else (here
>> >> +called `linux`).
>> >> +
>> >> +On the positive side, it might quieten the discussion alluded to in the section
>> >> +above. But there are many negatives to consider and many open questions to
>> >> +resolve.
>> >> +
>> >> +- **Bindings** - Presumably the special devicetree would have its own bindings.
>> >> +  It would not be necessary to put a `u-boot,` prefix on anything. People coming
>> >> +  across the devicetree source would wonder how it fits in with the Linux
>> >> +  devicetree.
>> >> +
>> >> +- **Access** - U-Boot has a nice `ofnode` API for accessing the devicetree. This
>> >> +  would need to be expanded to support two trees. Features which need to access
>> >> +  both (such as a device driver which reads the special devicetree to get some
>> >> +  configuration info) could become quite confusing to read and write.
>> >> +
>> >> +- **Merging** - Can the two devicetree be merged if a platform desires it? If
>> >> +  so, how is this managed in tooling? Does it happen during the build, in which
>> >> +  case they are not really separate at all. Or does U-Boot merge them at
>> >> +  runtime, in which case this adds time and memory?
>> >> +
>> >> +- **Efficiency** - A second device tree adds more code and more code paths. It
>> >> +  requires that both be made available to the code in U-Boot, e.g. via a
>> >> +  separate pointer or argument or API. Overall the separation would certainly
>> >> +  not speed up U-Boot, nor decrease its size.
>> >> +
>> >> +- **Source code** - At present `u-boot.dtsi` files provide the pieces needed for
>> >> +  U-Boot for a particular board. Would we use these same files for the special
>> >> +  devicetree?
>> >> +
>> >> +- **Complexity** - Two devicetrees complicates the build system since it must
>> >> +  build and package them both. Errors must be reported in such a way that it
>> >> +  is obvious which one is failing.
>> >> +
>> >> +- **Referencing each other** - The `u-boot,dm-xxx` tags used by driver model
>> >> +  are currently placed in the nodes they relate to. How would these tags
>> >> +  reference a node that is in a separate devicetree? What extra validation would
>> >> +  be needed?
>> >> +
>> >> +- **Storage** - How would the two devicetrees be stored in the image? At present
>> >> +  we simply concatenate the U-Boot binary and the devicetree. We could add the
>> >> +  special devicetree before the Linux one, so two are concatenated, but it is
>> >> +  not pretty. We could use binman to support more complex arrangements, but only
>> >> +  some boards use this at present, so it would be a big change.
>> >> +
>> >> +- **API** - How would another project provide two devicetree files to U-Boot at
>> >> +  runtime? Presumably this would just be too painful. But if it doesn't, it
>> >> +  would be unable to configure run-time features of U-Boot during the boot.
>> >> +
>> >> +- **Confusion** - No other project has two devicetrees. U-Boot would be in the
>> >> +  unfortunate position of having to describe this fact to new users, along with
>> >> +  the (arguably contrived) reason for the arrangement.
>> >> +
>> >
>> > False:
>> > 1) projects in trustedfirmware.org are built to have multiple FDT objects, some for "dynamic" configuration purposes.
>>
>> Can you provided a link and I can update this.
>
> https://trustedfirmware-a.readthedocs.io/en/latest/components/fconf/index.html
> Bindings:
> for FCONF: https://trustedfirmware-a.readthedocs.io/en/latest/components/fconf/fconf_properties.html
> for FF-A: https://trustedfirmware-a.readthedocs.io/en/latest/components/ffa-manifest-binding.html
> For chain-of-trust: https://trustedfirmware-a.readthedocs.io/en/latest/components/cot-binding.html
>
> For some code:
> https://github.com/ARM-software/arm-trusted-firmware/blob/master/tools/fiptool/tbbr_config.c
> From there you can wander and see how dynamic config sections of the FIP can contain component specific DTs.
> U-Boot "private" DT could be securely stored in NT_FW_CONFIG section.

OK I can mention that TF-A supports multiple devicetrees if you like,
but I'm not sure we are talking about the same thing.

U-Boot also supports multiple devicetrees in the build - e.g. SPL and
U-Boot proper. With binman you can create several copies of them for
use with A/B boot, for example. But only one is used as a control DTB
by a particular U-Boot phase at a time. Do you see what I mean?

>>
>> > 2) STM32MP1 can have dedicated DTBs for TF-A, OP-TEE and U-Boot in addition to operating system
>> > As Ilias said, this is not about documentation about the current use of DT in U-Boot, but justification of your views on DT.
>> > If taken by the letter, I feel (may be wrong though) that your views prevent establish the DT lifecycle and usage as per the desire of vendors, partners and customers that supports Arm SystemReady standards.
>>
>> I have gone to great efforts to document things here, as they work in
>> U-Boot today. As you know, U-Boot supports separate control and active
>> devicetrees.
>
> I don't know what is an active device tree. Is it the device tree to be passed to OS?

Yes that's right.

>>
>> But if you are wanting to change to multiple control
>> trees within U-Boot, I'd say the answer is "no, thank you".
>
> I see only one control DT.

OK good.

> There is a possibility to store it securely in NT_FW_CONFIG section of a FIP. it also has associated signature plus hash mechanisms to attest authenticity of  it (do not need signature in DT to allow verification: this is the associated content certificate section that contains the valid hashes).

What does NT mean? I suppose FW means firmware.

It doesn't really matter where it is stored, so long as U-Boot can access it.

> You can certain have a similar mechanism for binman.

Note that binman is a packaging tool. Perhaps you should add FIP
support to it if FIP is going to be required too now?

What I would like, to package up the firmware for ANY board, after all
the building is done in various projects:

binman -b <board>

>>
>> If there
>> is a use case for that, please can you be specific about what we
>> cannot do with a combined devicetree?

Regards,
SImon