Hi Sumit, On Thu, 14 Dec 2023 at 06:52, Sumit Garg <sumit.g...@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.g...@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