Hi Paul, On Wed, 28 Feb 2024 at 03:08, Paul Barker <paul.barker...@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.g...@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
