[PATCH 3/3] doc: Add a note about why devicetree is used

[Heinrich Schuchardt]

On 7/25/21 6:44 PM, Simon Glass wrote:
> This question comes up every now and then with people coming from Linux.
> Add some notes about it so we can point to it in the mailing list.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
>   doc/develop/devicetree/control.rst |  2 ++
>   doc/develop/devicetree/intro.rst   | 39 ++++++++++++++++++++++++++++++
>   2 files changed, 41 insertions(+)
>
> diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst
> index ac5f7989cc6..f98faee20d1 100644
> --- a/doc/develop/devicetree/control.rst
> +++ b/doc/develop/devicetree/control.rst
> @@ -174,6 +174,8 @@ ways:
>       $ make DEVICE_TREE=<dts-file-name>
>
>
> +.. _dttweaks:
> +
>   Adding tweaks for U-Boot
>   ------------------------
>
> diff --git a/doc/develop/devicetree/intro.rst b/doc/develop/devicetree/intro.rst
> index 344851327c7..e03d8e1ae66 100644
> --- a/doc/develop/devicetree/intro.rst
> +++ b/doc/develop/devicetree/intro.rst
> @@ -2,3 +2,42 @@
>
>   Devicetree Introduction
>   =======================
> +
> +U-Boot uses devicetree for configuration. This includes the devices used by

%s/devicetree/devicetrees/ or 'uses a'

> +the board, the format of the image created with binman, which UART to use for
> +the console, public keys used for secure boot and many other things.
> +
> +See :doc:`control` for more information.
> +
> +Why does U-Boot put <thing> in the devicetree?
> +----------------------------------------------
> +
> +This question comes up a lot with people new to U-Boot, particular those coming
> +from Linux who are used to quite strict rules about what can go in the

%s/in/into/ ?

> +devicetree.
> +
> +U-Boot uses the same devicetree as Linux but adds more things necessary for the
> +bootloader environment (see :ref:`dttweaks`).
> +
> +U-Boot does not have a user space to provide policy and configuration. It cannot
> +do what Linux does and run programs and look up filesystems to figure out how to
> +boot. So configuration / runtime info go in the devicetree in U-Boot.

Do you mean 'configuration and runtime' or 'runtime configuration'?

%s/info go in/information goes into/

> +
> +Of course it is possible to:
> +
> +- add tables into the rodata

%s/rodata/rodata section of the U-Boot binary/

> +- append some info to the end of U-Boot in a different format
> +- modify the link script to bring in a file with some info in it

%s/link/linker/

> +- put things in ACPI tables

%s/in/into/ ?

> +- compile in a UEFI hand-off block structure and put things in there

%s/compile/link/ ?

> +
> +but *please don't*. In general, devicetree is the sane place to hold U-Boot's
> +configuration.
> +
> +So please...do NOT ask why U-Boot puts <thing> in the devicetree. It is the only

%s/So please.../So, please, /

Best regards

Heinrich

> +place it can go. It is a highly suitable data structure for just about anything
> +that U-Boot needs to know at runtime.
> +
> +Note, it is possible to use platdata directly so drivers avoid devicetreee in
> +SPL. But of-platdata is the modern way of avoiding devicetree overhead, so
> +please use that instead.
>