[PATCH v6 08/11] doc: devicetree: Updates for devicetree-rebasing subtree

Wed Feb 28 10:20:32 CET 2024

Hi Paul,

On Wed, 28 Feb 2024 at 03:08, Paul Barker <paul.barker.ct at bp.renesas.com> wrote:
>
> Hi Sumit,
>
> On 22/02/2024 09:36, 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 at linaro.org>
> > ---
> >
> > Changes in v6:
> > - Incorporate documentation review comments from Paul.
> >
>
> I have just a couple of tidy up suggestions for the links in this
> document - these let us avoid short reference names like `dtrepo` or
> `dttweaks` appearing in the document itself where they interrupt the
> flow of the text.

Although these are following the same pattern as `dtspec` and `dtlist`
, your suggestion sounds reasonable. However, I would just like to
avoid sending a newer version just for these since this patch-set is
already a dependency for others [1] [2].

If you agree then I can send a follow up patch to get rid of all the
short reference names in this document.

[1] https://patchwork.ozlabs.org/project/uboot/list/?series=396399
[2] https://patchwork.ozlabs.org/project/uboot/list/?series=396742

-Sumit

> For each one I've just wrote out what I think the line
> above should be, I hope that makes sense.
>
> [...]
>
> > +Resyncing with devicetree-rebasing
> > +----------------------------------
> > +
> > +The devicetee-rebasing repository (dtrepo_) maintains a fork cum mirror copy of
>
> The `devicetree-rebasing repository`_ maintains a fork cum mirror copy of
>
> > +devicetree files along with the bindings synced at every Linux kernel major
> > +release or intermediate release candidates. The U-Boot maintainers regularly
> > +sync the `dts/upstream/` subtree from the devicetree-rebasing repo whenever
> > +the next branch opens (refer: :doc:`../release_cycle`) with the latest mainline
> > +Linux kernel release. To sync the `dts/upstream/` subtree, run::
> > +
> > +    ./dts/update-dts-subtree.sh pull <devicetree-rebasing-release-tag>
> > +
> > +If required it is also possible to cherry-pick fixes from the
> > +devicetree-rebasing repository prior to next sync, usage::
> > +
> > +    ./dts/update-dts-subtree.sh pick <devicetree-rebasing-commit-id>
> > +
> > +
> >  Configuration
> >  -------------
> >
> > -Set up "<name>" when prompted for `DEFAULT_DEVICE_TREE` by Kconfig. Then put
> > -your devicetree file into::
> > +SoC/board maintainers are encouraged to migrate to use synced copies from
> > +`dts/upstream/src/<arch>/<vendor>`. To do that add `imply OF_UPSTREAM` for the
> > +SoC being used via Kconfig and set `DEFAULT_DEVICE_TREE=<vendor>/<name>` when
> > +prompted by Kconfig.
> >
> > -   arch/<arch>/dts/<name>.dts
> > +However, if `dts/upstream/` hasn't yet received devicetree source file for your
> > +newly added board support then you can add corresponding devicetree source file
> > +as `arch/<arch>/dts/<name>.dts`. To select that add `# CONFIG_OF_UPSTREAM is not
> > +set` and set `DEFAULT_DEVICE_TREE=<name>` when prompted by Kconfig.
> >
> > -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.
>
> specific tweaks (see: :ref:`dttweaks`) can be made for your board.
>
> >
> >  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
> > @@ -155,8 +185,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 `dts/upstream` Git subtree, it is ensured that devicetree files in U-Boot
> > +are an exact copy of those in Linux kernel available under
> > +`dts/upstream/src/<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
> > @@ -169,8 +200,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
> > @@ -199,6 +230,48 @@ 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 `dts/upstream/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. For installation
> > +instructions, refer to the DT schema project page (dtschema_).
>
> instructions, refer to the `DT schema project page`_.
>
> > +
> > +Several executables (dt-doc-validate, dt-mk-schema, dt-validate) will be
> > +installed. Ensure they are in your PATH (~/.local/bin by default).
> > +
> > +You should also install yamllint (used by dtschema when present). On Debian/
> > +Ubuntu systems::
> > +
> > +    apt install yamllint
> > +
> > +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
> >  -----------------------
> >
> > @@ -260,8 +333,10 @@ 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
>
> these are stored, with U-Boot taking copies via the `devicetree-rebasing repository`_
>
> > +(see: dtrepo_) and adding tweaks with u-boot.dtsi files.
>
> 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
>
> .. _devicetree-rebasing repository: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git
>
> > +.. _dtschema: https://github.com/devicetree-org/dt-schema/tree/main
>
> .. _DT schema project page: https://github.com/devicetree-org/dt-schema/tree/main
>
> Thanks,
>
> --
> Paul Barker