[PATCH v3 5/8] doc: devicetree: Updates for devicetree-rebasing subtree

Thu Dec 28 14:37:09 CET 2023

Hi Sumit,

On Thu, Dec 28, 2023 at 11:59 AM Sumit Garg <sumit.garg at linaro.org> wrote:
>
> Encourage SoC/board maintainers to migrate to using devicetree-rebasing
> subtree and maintain a regular sync with Linux kernel devicetree files
> and bindings.
>
> Along with that add documentation regarding how to run DT bindings
> schema checks.
>
> Signed-off-by: Sumit Garg <sumit.garg at linaro.org>
> ---
>
> Changes in v3:
> --------------
> - Replace CONFIG_* with Kconfig options
>
> Changes in v2:
> --------------
> - s/U-boot/U-Boot/
>
>  doc/develop/devicetree/control.rst | 131 +++++++++++++++++++++--------
>  1 file changed, 96 insertions(+), 35 deletions(-)
>
> diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst
> index cbb65c9b177..65180d33e8d 100644
> --- a/doc/develop/devicetree/control.rst
> +++ b/doc/develop/devicetree/control.rst
> @@ -1,5 +1,6 @@
>  .. SPDX-License-Identifier: GPL-2.0+
>  .. sectionauthor:: Copyright 2011 The Chromium OS Authors
> +.. Copyright 2023 Linaro Ltd.
>
>  Devicetree Control in U-Boot
>  ============================
> @@ -22,14 +23,13 @@ for three reasons:
>    hierarchical format
>  - It is fairly efficient to read incrementally
>
> -The arch/<arch>/dts directories contains a Makefile for building the devicetree
> -blob and embedding it in the U-Boot image. This is useful since it allows
> -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 devicetree file, and have a single
> -generic source base.
> +The U-Boot Makefile infrastructure allows for building the devicetree blob
> +and embedding it in the U-Boot image. This is useful since it allows 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 devicetree file, and have a single generic source base.
>
> -To enable this feature, add CONFIG_OF_CONTROL to your board config file.
> +To enable this feature, select `OF_CONTROL` via Kconfig.

These changes to remove CONFIG_ are good, but I think they should be
in a separate, prior patch.
>
>
>  What is a Flattened Devicetree?
> @@ -68,8 +68,21 @@ a binary file. U-Boot adds its own `fdtgrep` for creating subsets of the file.
>  Where do I get a devicetree 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.
> +Linux kernel Git repository has been the place where devicetree files along
> +with devicetree bindings are stored and maintained. There is devicetee-rebasing
> +(dtrepo_) which maintains a forked copy of devicetree files along with bindings
> +at every Linux kernel major release or intermideate release candidates.
> +
> +In order to maintain devicetree files sync, U-Boot maintains a Git subtree for
> +devicetee-rebasing repo as `devicetee-rebasing/` sub-directory. It is regularly
> +kept updated with every new kernel major release via subtree pull as follows::
> +
> +    git subtree pull --prefix devicetree-rebasing \
> +        git://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git \
> +        <release-tag> --squash
> +

This is an internal detail and I believe it will confuse people. Can
you put this in a section like 'Resyncing with devicetree-rebasing'
and explain when this might be needed?...almost enver, right?

> +You may find that the `devicetee-rebasing/` sub-directory has a suitable
> +devicetree file for your board. Look in `devicetree-rebasing/src/<arch>/`.
>
>  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
> @@ -81,34 +94,34 @@ Failing that, you could write one from scratch yourself!
>  Configuration
>  -------------
>
> -Use::
> +Traditionally, U-Boot placed copies of devicetree source files from Linux
> +kernel into `arch/<arch>/dts/<name>.dts` which can be selected via setting
> +"<name>" when prompted for `DEFAULT_DEVICE_TREE` by Kconfig.
>
> -   #define CONFIG_DEFAULT_DEVICE_TREE  "<name>"
> +However, it has become combersome over time for each SoC/board maintainer to

spelling

> +keep devicetree files in sync with Linux kernel. Thereby, SoC/board maintainers

s/Thereby/Therefore/

> +are encouraged to migrate to use mirrored copies from `devicetree-rebasing/`
> +into `dts/arch/<arch>/<vendor>`. To do that enable `OF_UPSTREAM` via Kconfig

for the SoC being used

> and
> +set up "<vendor>/<name>" when prompted for `DEFAULT_DEVICE_TREE` by Kconfig.
>
> -to set the filename of the devicetree source. Then put your devicetree
> -file into::
> +This should include your CPU or SOC's devicetree file. On top of that any U-Boot
> +specific tweaks (see: dttweaks_) can be made for your board.
>
> -   arch/<arch>/dts/<name>.dts
> -
> -This should include your CPU or SOC's devicetree file, placed in
> -`arch/<arch>/dts`, and then make any adjustments required using a u-boot-dtsi
> -file for your board.
> -
> -If CONFIG_OF_EMBED is defined, then it will be picked up and built into
> +If `OF_EMBED` is selected by Kconfig, 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
> +If `OF_SEPARATE` is selected by Kconfig, then it will be built and placed in
>  a u-boot.dtb file alongside u-boot-nodtb.bin with the combined result placed
> -in u-boot.bin so you can still just flash u-boot.bin onto your board. If you are
> -using CONFIG_SPL_FRAMEWORK, then u-boot.img will be built to include the device
> -tree binary.
> +in u-boot.bin so you can still just flash u-boot.bin onto your board. If Kconfig
> +option `SPL_FRAMEWORK` is enabled, 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
> +If `OF_BOARD` is selected by Kconfig, a board-specific routine will provide the
>  devicetree at runtime, for example if an earlier bootloader stage creates
>  it and passes it to U-Boot.
>
> -If CONFIG_SANDBOX is defined, then it will be read from a file on
> +If `SANDBOX` is selected by Kconfig, then it will be read from a file on
>  startup. Use the -d flag to U-Boot to specify the file to read, -D for the
>  default and -T for the test devicetree, used to run sandbox unit tests.

As above, please move the CONFIG changes into a prior patch.

>
> @@ -142,7 +155,7 @@ Build:
>  After the board configuration is done, fdt supported u-boot can be built in two
>  ways:
>
> -#  build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE::
> +#  build the default dts which is selected by DEFAULT_DEVICE_TREE Kconfig::
>
>      $ make
>
> @@ -156,8 +169,9 @@ ways:
>  Adding tweaks for U-Boot
>  ------------------------
>
> -It is strongly recommended that devicetree files in U-Boot are an exact copy of
> -those in Linux, so that it is easy to sync them up from time to time.
> +With devicetee-rebasing Git subtree, it is ensured that devicetree files in
> +U-Boot are an exact copy of those in Linux kernel via mirroring into
> +`dts/arch/<arch>/<vendor>`.
>
>  U-Boot is of course a very different project from Linux, e.g. it operates under
>  much more restrictive memory and code-size constraints. Where Linux may use a
> @@ -170,8 +184,8 @@ constraints are even more extreme and the devicetree is shrunk to remove
>  unwanted nodes, or even turned into C code to avoid access overhead.
>
>  U-Boot automatically looks for and includes a file with updates to the standard
> -devicetree for your board, searching for them in the same directory as the
> -main file, in this order::
> +devicetree for your board, searching for them in `arch/<arch>/dts/` in this
> +order::
>
>     <orig_filename>-u-boot.dtsi
>     <CONFIG_SYS_SOC>-u-boot.dtsi
> @@ -195,11 +209,57 @@ As mentioned above, the U-Boot build system automatically includes a
>  `*-u-boot.dtsi` file, if found, containing U-Boot specific
>  quirks. However, some data, such as the mentioned public keys, are not
>  appropriate for upstream U-Boot but are better kept and maintained
> -outside the U-Boot repository. You can use CONFIG_DEVICE_TREE_INCLUDES
> -to specify a list of .dtsi files that will also be included when
> +outside the U-Boot repository. You can use `DEVICE_TREE_INCLUDES` Kconfig
> +option to specify a list of .dtsi files that will also be included when
>  building .dtb files.
>
>
> +Devicetree bindings schema checks
> +---------------------------------
> +
> +With devicetee-rebasing Git subtree, the devicetree bindings are also regularly
> +synced with Linux kernel as `devicetree-rebasing/Bindings/` sub-directory. This
> +allows U-Boot to run devicetree bindings schema checks which will bring
> +compliance to U-Boot core/drivers regarding usage of devicetree.
> +
> +Dependencies
> +~~~~~~~~~~~~
> +
> +The DT schema project must be installed in order to validate the DT schema
> +binding documents and validate DTS files using the DT schema. The DT schema
> +project can be installed with pip::
> +
> +    pip3 install dtschema
> +
> +Note that 'dtschema' installation requires 'swig' and Python development files
> +installed first. On Debian/Ubuntu systems::
> +
> +    apt install swig python3-dev

These two are already in doc/build/gcc.rst so please reference that
here, rather than repeating it.

> +
> +Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
> +installed. Ensure they are in your PATH (~/.local/bin by default).
> +
> +Recommended is also to install yamllint (used by dtschema when present).

How?

> +
> +Running checks
> +~~~~~~~~~~~~~~
> +
> +In order to perform validation of DTB files, use the ``dtbs_check`` target::
> +
> +    make dtbs_check
> +
> +It is also possible to run checks with a subset of matching schema files by
> +setting the ``DT_SCHEMA_FILES`` variable to 1 or more specific schema files or
> +patterns (partial match of a fixed string). Each file or pattern should be
> +separated by ':'.
> +
> +::
> +
> +    make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml:rtc.yaml
> +    make dtbs_check DT_SCHEMA_FILES=/gpio/
> +    make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml
> +
> +
>  Relocation, SPL and TPL
>  -----------------------
>
> @@ -261,8 +321,9 @@ used it before Linux (e.g. snow). The two projects developed in parallel
>  and there are still some differences in the bindings for certain boards.
>  While there has been discussion of having a separate repository for devicetree
>  files, in practice the Linux kernel Git repository has become the place where
> -these are stored, with U-Boot taking copies and adding tweaks with u-boot.dtsi
> -files.
> +these are stored, with U-Boot taking copies via devicetree-rebasing repo
> +(see: dtrepo_) and adding tweaks with u-boot.dtsi files.
>
>  .. _dtspec: https://www.devicetree.org/specifications/
>  .. _dtlist: https://www.spinics.net/lists/devicetree-compiler/
> +.. _dtrepo: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git
> --
> 2.34.1
>

Regards,
Simon