[PATCH 1/3] doc: Move devicetree control doc to rST

[Heinrich Schuchardt]

On 7/25/21 6:43 PM, Simon Glass wrote:
> Move this to rST format, largely unchanged to start with. Add an index
> for this topic, as well as an empty intro.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
>   .../devicetree/control.rst}                   | 50 +++++++++----------
>   doc/develop/devicetree/index.rst              | 13 +++++
>   doc/develop/devicetree/intro.rst              |  4 ++
>   doc/develop/index.rst                         |  1 +
>   4 files changed, 43 insertions(+), 25 deletions(-)
>   rename doc/{README.fdt-control => develop/devicetree/control.rst} (89%)
>   create mode 100644 doc/develop/devicetree/index.rst
>   create mode 100644 doc/develop/devicetree/intro.rst
>
> diff --git a/doc/README.fdt-control b/doc/develop/devicetree/control.rst
> similarity index 89%
> rename from doc/README.fdt-control
> rename to doc/develop/devicetree/control.rst
> index 424d13fc5b1..1289b6156fe 100644


 > diff --git a/doc/develop/devicetree/control.rst
b/doc/develop/devicetree/control.rst
 > new file mode 100644
 > index 0000000000..1289b6156f
 > --- /dev/null
 > +++ b/doc/develop/devicetree/control.rst
 > @@ -0,0 +1,230 @@
 > +.. SPDX-License-Identifier: GPL-2.0+
 > +.. sectionauthor:: Copyright 2011 The Chromium OS Authors
 > +
 > +Device Tree Control in U-Boot
 > +=============================
 > +
 > +This feature provides for run-time configuration of U-Boot via a flat

%s/flat/flattened/

Please, use the terminology of the Devicetree Specification.

 > +device tree (fdt). U-Boot configuration has traditionally been done
 > +using CONFIG options in the board config file. This feature aims to

%s/config/configuration/

Please, avoid slang.

 > +make it possible for a single U-Boot binary to support multiple boards,
 > +with the exact configuration of each board controlled by a flat device

%s/flag/flattened/

 > +tree (fdt). This is the approach recently taken by the ARM Linux kernel

RISC-V too.

 > +and has been used by PowerPC for some time.
 > +
 > +The fdt is a convenient vehicle for implementing run-time configuration
 > +for three reasons. Firstly it is easy to use, being a simple text file.

No. The flattened devicetree is not a text file format. It is a binary
format.

Assume that a reader does not know that these different formats exist.
You need to explain at the beginning of the chapter what a devicetree is
and that it can be converted to a binary format, the flattened divice tree.

 > +It is extensible since it consists of nodes and properties in a nice
 > +hierarchical format.
 > +
 > +Finally, there is already excellent infrastructure for the fdt: a
 > +compiler checks the text file and converts it to a compact binary
 > +format, and a library is already available in U-Boot (libfdt) for
 > +handling this format.
 > +
 > +The dts directory contains a Makefile for building the device tree blob

The arch/<arch>/dts directories contain Makefiles ...

 > +and embedding it in your U-Boot image. This is useful since it allows
%s/your/the/

 > +U-Boot to configure itself according to what it finds there. If you have
 > +a number of similar boards with different peripherals, you can describe
 > +the features of each board in the device tree file, and have a single
 > +generic source base.
 > +
 > +To enable this feature, add CONFIG_OF_CONTROL to your board config file.
 > +
 > +
 > +What is a Flat Device Tree?

%s/Flat/Flattened/

 > +---------------------------
 > +
 > +An fdt can be specified in source format as a text file. To read about
 > +the fdt syntax, take a look at the specification (dtspec_).

Please, provide a URL link to the Devicetree Specification, Release v0.3.

 > +
 > +You also might find this section of the Linux kernel documentation
 > +useful: (access this in the Linux kernel source code)
 > +
 > +	Documentation/devicetree/booting-without-of.txt
 > +
 > +There is also a mailing list:
 > +
 > +	http://lists.ozlabs.org/listinfo/devicetree-discuss
 > +
 > +In case you are wondering, OF stands for Open Firmware.
 > +
 > +
 > +Tools
 > +-----
 > +
 > +To use this feature you will need to get the device tree compiler.

This is
"this feature" does not relate to anything. Better:

To create flattened device trees the device tree compiler is used.

 > +provided by U-Boot automatically. If you have a system version of dtc

What automatism? Better:

U-Boot comes with a copy of the device tree compiler code in /scripts/dtc/.

 > +(typically in the 'device-tree-compiler' package), it is currently
not used.

What is not used? /scripts/dtc/ or the system instance?

 > +
 > +If you want to build your own dtc, it is kept here::
 > +
 > +	git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 > +
 > +For example::
 > +
 > +	$ git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 > +	$ cd dtc
 > +	$ make
 > +	$ sudo make install

Why should we describe this? We have the code in /scripts/dtc/. We
enable CONFIG_DTC as neeeded.

 > +
 > +Then run the compiler (your version will vary)::
 > +
 > +	$ dtc -v
 > +	Version: DTC 1.2.0-g2cb4b51f
 > +	$ make tests
 > +	$ cd tests
 > +	$ ./run_tests.sh
 > +	********** TEST SUMMARY
 > +	*     Total testcases:	1371
 > +	*                PASS:	1371
 > +	*                FAIL:	0
 > +	*   Bad configuration:	0
 > +	* Strange test result:	0
 > +
 > +You will also find a useful fdtdump utility for decoding a binary
file, as

fdtdump is deprecated. Use 'dtc -I dtb -O dts'.

 > +well as fdtget/fdtput for reading and writing properties in a binary
file.
 > +
 > +
 > +Where do I get an fdt file for my board?>
+----------------------------------------
 > +
 > +You may find that the Linux kernel has a suitable file. Look in the
 > +kernel source in arch/<arch>/boot/dts.

There is no fdt file in the kernel source.

 > +
 > +If not you might find other boards with suitable files that you can
 > +modify to your needs. Look in the board directories for files with a
 > +.dts extension.
 > +
 > +Failing that, you could write one from scratch yourself!
 > +
 > +
 > +Configuration
 > +-------------
 > +
 > +Use::
 > +
 > +   #define CONFIG_DEFAULT_DEVICE_TREE	"<name>"
 > +
 > +to set the filename of the device tree source. Then put your device tree
 > +file into::
 > +
 > +   board/<vendor>/dts/<name>.dts
 > +
 > +This should include your CPU or SOC's device tree file, placed in
 > +arch/<arch>/dts, and then make any adjustments required.
 > +
 > +If CONFIG_OF_EMBED is defined, then it will be picked up and built into
 > +the U-Boot image (including u-boot.bin). This is suitable for debugging
 > +and development only and is not recommended for production devices.
 > +
 > +If CONFIG_OF_SEPARATE is defined, then it will be built and placed in
 > +a u-boot.dtb file alongside u-boot-nodtb.bin. A common approach is
then to
 > +join the two::
 > +
 > +   cat u-boot-nodtb.bin u-boot.dtb >image.bin

All these steps will not be taken by a normal user. So this is very
confusing for him.

Please, clearly distinguish between steps a user takes who uses an
existing defconfig file and those taken by a developer.

 > +
 > +and then flash image.bin onto your board. Note that U-Boot creates
 > +u-boot-dtb.bin which does the above step for you also. Resulting
 > +u-boot.bin is a copy of u-boot-dtb.bin in this case. If you are using
 > +CONFIG_SPL_FRAMEWORK, then u-boot.img will be built to include the
device
 > +tree binary.
 > +
 > +If CONFIG_OF_BOARD is defined, a board-specific routine will provide the
 > +device tree at runtime, for example if an earlier bootloader stage
creates
 > +it and passes it to U-Boot.
 > +
 > +If CONFIG_OF_HOSTFILE is defined, then it will be read from a file on
 > +startup. This is only useful for sandbox. Use the -d flag to U-Boot to
 > +specify the file to read.
 > +
 > +You cannot use more than one of these options at the same time.
 > +
 > +To use a device tree file that you have compiled yourself, pass
 > +EXT_DTB=<filename> to 'make', as in::
 > +
 > +   make EXT_DTB=boot/am335x-boneblack-pubkey.dtb
 > +
 > +Then U-Boot will copy that file to u-boot.dtb, put it in the .img file
 > +if used, and u-boot-dtb.bin.
 > +
 > +If you wish to put the fdt at a different address in memory, you can
 > +define the "fdtcontroladdr" environment variable. This is the hex
 > +address of the fdt binary blob, and will override either of the options.
 > +Be aware that this environment variable is checked prior to relocation,
 > +when only the compiled-in environment is available. Therefore it is not
 > +possible to define this variable in the saved SPI/NAND flash
 > +environment, for example (it will be ignored). After relocation, this
 > +variable will be set to the address of the newly relocated fdt blob.
 > +It is read-only and cannot be changed. It can optionally be used to
 > +control the boot process of Linux with bootm/bootz commands.
 > +
 > +To use this, put something like this in your board header file::
 > +
 > +   #define CONFIG_EXTRA_ENV_SETTINGS	"fdtcontroladdr=10000\0"
 > +
 > +Build:
 > +
 > +After board configuration is done, fdt supported u-boot can be build
in two

%s/After/After the/

%s/build/built/

 > +ways:
 > +
 > +#  build the default dts which is defined from
CONFIG_DEFAULT_DEVICE_TREE::
 > +
 > +    $ make
 > +
 > +#  build the user specified dts file::
 > +
 > +    $ make DEVICE_TREE=<dts-file-name>
 > +
 > +
 > +Relocation, SPL and TPL
 > +-----------------------
 > +
 > +U-Boot can be divided into three phases: TPL, SPL and U-Boot proper.> +
 > +The full device tree is available to U-Boot proper, but normally
only a subset
 > +(or none at all) is available to TPL and SPL. See 'Pre-Relocation
Support' and
 > +'SPL Support' in doc/driver-model/design.rst for more details.
 > +
 > +
 > +Using several DTBs in the SPL (CONFIG_SPL_MULTI_DTB)
 > +----------------------------------------------------
 > +In some rare cases it is desirable to let SPL be able to select one
DTB among
 > +many. This usually not very useful as the DTB for the SPL is small
and usually

Quite the contrary. It is very useful to reduce the number of different
images a Linux distribution has to supply.

 > +fits several platforms. However the DTB sometimes include
information that do
 > +work on several platforms (like IO tuning parameters).
 > +In this case it is possible to use CONFIG_SPL_MULTI_DTB. This option
appends to
How does this compare to CONFIG_MULTI_DTB_FIT and CONFIG_SPL_MULTI_DTB_FIT?

 > +the SPL a FIT image containing several DTBs listed in SPL_OF_LIST.
 > +board_fit_config_name_match() is called to select the right DTB.
 > +
 > +If board_fit_config_name_match() relies on DM (DM driver to access
an EEPROM

CONFIG_SPL_MULTI_DTB seems not to be related to
board_fit_config_name_match(). It is CONFIG_$(SPL_)MULTI_DTB_FIT that
enables compiling common_fit.o.

 > +containing the board ID for example), it possible to start with a
generic DTB
 > +and then switch over to the right DTB after the detection. For this
purpose,
 > +the platform code must call fdtdec_resetup(). Based on the returned
flag, the
 > +platform may have to re-initiliaze the DM subusystem using
dm_uninit() and
 > +dm_init_and_scan().
 > +
 > +
 > +Limitations
 > +-----------
 > +
 > +U-Boot is designed to build with a single architecture type and CPU

%s/with/for/

 > +type. So for example it is not possible to build a single ARM binary
 > +which runs on your AT91 and OMAP boards, relying on an fdt to configure
 > +the various features. This is because you must select one of
 > +the CPU families within arch/arm/cpu/arm926ejs (omap or at91) at build
 > +time. Similarly you cannot build for multiple cpu types or
 > +architectures.

%s/you cannot build/U-Boot cannot be built/

It is not the user's fault.

 > +
 > +That said the complexity reduction by using fdt to support variants of
 > +boards which use the same SOC / CPU can be substantial.

This complexity reduction should be described first. The limitations
(e.g. same CPU architecture) second.

Best regards

Heinrich

 > +
 > +It is important to understand that the fdt only selects options
 > +available in the platform / drivers. It cannot add new drivers (yet). So
 > +you must still have the CONFIG option to enable the driver. For example,
 > +you need to define CONFIG_SYS_NS16550 to bring in the NS16550 driver,
 > +but can use the fdt to specific the UART clock, peripheral address, etc.
 > +In very broad terms, the CONFIG options in general control *what* driver
 > +files are pulled in, and the fdt controls *how* those files work.
 > +
 > +.. _dtspec:
https://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf
 > diff --git a/doc/develop/devicetree/index.rst
b/doc/develop/devicetree/index.rst
 > new file mode 100644
 > index 0000000000..fa5db3eb76
 > --- /dev/null
 > +++ b/doc/develop/devicetree/index.rst
 > @@ -0,0 +1,13 @@
 > +.. SPDX-License-Identifier: GPL-2.0+
 > +
 > +Devicetree in U-Boot
 > +====================
 > +
 > +The following holds information on how U-Boot makes use of
devicetree for
 > +build-time and runtime configuration.
 > +
 > +.. toctree::
 > +   :maxdepth: 2
 > +
 > +   intro
 > +   control
 > diff --git a/doc/develop/devicetree/intro.rst
b/doc/develop/devicetree/intro.rst
 > new file mode 100644
 > index 0000000000..344851327c
 > --- /dev/null
 > +++ b/doc/develop/devicetree/intro.rst
 > @@ -0,0 +1,4 @@
 > +.. SPDX-License-Identifier: GPL-2.0+
 > +
 > +Devicetree Introduction
 > +=======================
 > diff --git a/doc/develop/index.rst b/doc/develop/index.rst
 > index 54e14dd77b..1b90418994 100644
 > --- a/doc/develop/index.rst
 > +++ b/doc/develop/index.rst
 > @@ -10,6 +10,7 @@ Implementation
 >      :maxdepth: 1
 >
 >      commands
 > +   devicetree/index
 >      driver-model/index
 >      global_data
 >      logging
 >