Hi Paul,
On Wed, 28 Feb 2024 at 03:08, Paul Barker paul.barker.ct@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@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-rebasi...
.. _devicetree-rebasing repository: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasi...
+.. _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