diff mbox series

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

Message ID 20231222061208.3009970-6-sumit.garg@linaro.org
State New
Headers show
Series An effort to bring DT bindings compliance within U-Boot | expand

Commit Message

Sumit Garg Dec. 22, 2023, 6:12 a.m. UTC 
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@linaro.org>
---
 doc/develop/devicetree/control.rst | 108 +++++++++++++++++++++++------
 1 file changed, 86 insertions(+), 22 deletions(-)

Comments

Tom Rini Dec. 22, 2023, 12:35 p.m. UTC | #1 
On Fri, Dec 22, 2023 at 11:42:05AM +0530, Sumit Garg 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@linaro.org>
> ---
>  doc/develop/devicetree/control.rst | 108 +++++++++++++++++++++++------
>  1 file changed, 86 insertions(+), 22 deletions(-)
[snip]
> @@ -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>"

Oh, oof. This never got updated for Kconfig rather than config.h. Can
you please include re-wording this to be setting <name> when prompted
for DEFAULT_DEVICE_TREE by Kconfig? And the rest of the text you're
updating as well to match, thanks.
Sumit Garg Dec. 22, 2023, 1:48 p.m. UTC | #2 
On Fri, 22 Dec 2023 at 18:05, Tom Rini <trini@konsulko.com> wrote:
>
> On Fri, Dec 22, 2023 at 11:42:05AM +0530, Sumit Garg 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@linaro.org>
> > ---
> >  doc/develop/devicetree/control.rst | 108 +++++++++++++++++++++++------
> >  1 file changed, 86 insertions(+), 22 deletions(-)
> [snip]
> > @@ -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>"
>
> Oh, oof. This never got updated for Kconfig rather than config.h. Can
> you please include re-wording this to be setting <name> when prompted
> for DEFAULT_DEVICE_TREE by Kconfig? And the rest of the text you're
> updating as well to match, thanks.
>

Sure but how about changing it to say via board defconfig as
CONFIG_DEFAULT_DEVICE_TREE="<name>", since AFAIK most people use
defconfig to configure U-Boot.

-Sumit

> --
> Tom
Tom Rini Dec. 22, 2023, 1:56 p.m. UTC | #3 
On Fri, Dec 22, 2023 at 07:18:05PM +0530, Sumit Garg wrote:
> On Fri, 22 Dec 2023 at 18:05, Tom Rini <trini@konsulko.com> wrote:
> >
> > On Fri, Dec 22, 2023 at 11:42:05AM +0530, Sumit Garg 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@linaro.org>
> > > ---
> > >  doc/develop/devicetree/control.rst | 108 +++++++++++++++++++++++------
> > >  1 file changed, 86 insertions(+), 22 deletions(-)
> > [snip]
> > > @@ -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>"
> >
> > Oh, oof. This never got updated for Kconfig rather than config.h. Can
> > you please include re-wording this to be setting <name> when prompted
> > for DEFAULT_DEVICE_TREE by Kconfig? And the rest of the text you're
> > updating as well to match, thanks.
> >
> 
> Sure but how about changing it to say via board defconfig as
> CONFIG_DEFAULT_DEVICE_TREE="<name>", since AFAIK most people use
> defconfig to configure U-Boot.

Well, do kernel docs tell people to modify defconfigs, or to use the
config menu/etc?
Sumit Garg Dec. 22, 2023, 2:08 p.m. UTC | #4 
On Fri, 22 Dec 2023 at 19:26, Tom Rini <trini@konsulko.com> wrote:
>
> On Fri, Dec 22, 2023 at 07:18:05PM +0530, Sumit Garg wrote:
> > On Fri, 22 Dec 2023 at 18:05, Tom Rini <trini@konsulko.com> wrote:
> > >
> > > On Fri, Dec 22, 2023 at 11:42:05AM +0530, Sumit Garg 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@linaro.org>
> > > > ---
> > > >  doc/develop/devicetree/control.rst | 108 +++++++++++++++++++++++------
> > > >  1 file changed, 86 insertions(+), 22 deletions(-)
> > > [snip]
> > > > @@ -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>"
> > >
> > > Oh, oof. This never got updated for Kconfig rather than config.h. Can
> > > you please include re-wording this to be setting <name> when prompted
> > > for DEFAULT_DEVICE_TREE by Kconfig? And the rest of the text you're
> > > updating as well to match, thanks.
> > >
> >
> > Sure but how about changing it to say via board defconfig as
> > CONFIG_DEFAULT_DEVICE_TREE="<name>", since AFAIK most people use
> > defconfig to configure U-Boot.
>
> Well, do kernel docs tell people to modify defconfigs, or to use the
> config menu/etc?
>

Okay I see your point, I will use wording to select
DEFAULT_DEVICE_TREE by Kconfig instead.

-Sumit

> --
> Tom
diff mbox series

Patch

diff --git a/doc/develop/devicetree/control.rst b/doc/develop/devicetree/control.rst
index cbb65c9b177..7c15f6d8c19 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