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

Tue Feb 27 22:38:34 CET 2024

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. 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_0x27F4B3459F002257.asc
Type: application/pgp-keys
Size: 3520 bytes
Desc: OpenPGP public key
URL: <https://lists.denx.de/pipermail/u-boot-custodians/attachments/20240227/a4bcc429/attachment.key>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_signature.asc
Type: application/pgp-signature
Size: 236 bytes
Desc: OpenPGP digital signature
URL: <https://lists.denx.de/pipermail/u-boot-custodians/attachments/20240227/a4bcc429/attachment.sig>