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

[Rob Herring]

On Thu, Dec 28, 2023 at 4: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.
>
>
>  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.

Typo.

> +
> +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::

I would suggest dropping "-rebasing" in the u-boot tree. (I wish we
had in the original repo). I don't think it's relevant.

We're not likely to regenerate the tree, but any clue what 'git
subtree pull' would do in this case? It could happen if we switched to
git-filter-repo.

> +
> +    git subtree pull --prefix devicetree-rebasing \
> +        git://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git \
> +        <release-tag> --squash

I'd put this in a script to run. Documentation tends to be not quite
correct. A script could also be smarter and figure out <release-tag>.

> +
> +You may find that the `devicetee-rebasing/` sub-directory has a suitable
> +devicetree file for your board. Look in `devicetree-rebasing/src/<arch>/`.