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

[Simon Glass]

Hi Sumit,

On Thu, 14 Dec 2023 at 06:52, 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>
> ---
>  doc/develop/devicetree/control.rst | 108 +++++++++++++++++++++++------
>  1 file changed, 86 insertions(+), 22 deletions(-)
>
> diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst
> index cbb65c9b177..12ef55ed368 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,12 +23,11 @@ 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.
>
> @@ -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
> +
> +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,18 +94,21 @@ 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::
>
> -   #define CONFIG_DEFAULT_DEVICE_TREE  "<name>"
> +    #define CONFIG_DEFAULT_DEVICE_TREE "<name>"
>
> -to set the filename of the devicetree source. Then put your devicetree
> -file into::
> +However, it has become combersome over time for each SoC/board maintainer to
> +keep devicetree files in sync with Linux kernel. Thereby, SoC/board maintainers
> +are encouraged to migrate to use mirrored copies from `devicetree-rebasing/`
> +into `dts/arch/<arch>/<vendor>` via::
>
> -   arch/<arch>/dts/<name>.dts
> +    #define CONFIG_OF_UPSTREAM=y
> +    #define CONFIG_DEFAULT_DEVICE_TREE "<vendor>/<name>"
>
> -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.
> +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.
>
>  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
> @@ -156,8 +172,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 +187,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
> @@ -200,6 +217,52 @@ 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
> +
> +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).
> +
> +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 +324,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
>

OK, ignore my comment about docs.

Regards,
Simon