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. 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
OpenPGP_0x27F4B3459F002257.asc
Description: OpenPGP public key
OpenPGP_signature.asc
Description: OpenPGP digital signature
