.. SPDX-License-Identifier: GPL-2.0+
.. sectionauthor:: Copyright 2011 The Chromium OS Authors
+.. Copyright 2023-2024 Linaro Ltd.
Devicetree Control in U-Boot
============================
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, select `OF_CONTROL` via Kconfig.
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.
+The devicetree files and devicetree bindings are maintained as part of the Linux
+kernel git repository. Traditionally, U-Boot placed copies of devicetree source
+files from the Linux kernel into `arch/<arch>/dts/<name>.dts`. However, this
+required each board maintainer to manually keep their devicetree in sync with
+the Linux kernel and often led to divergence between these copies.
+
+U-Boot rather maintains a Git subtree as `dts/upstream/` sub-directory. It is
+regularly synced with the Linux kernel and hence no need for manual devicetree
+sync. You may find that the `dts/upstream/` already has a suitable devicetree
+file for your board. Look in `dts/upstream/src/<arch>/<vendor>`.
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
Failing that, you could write one from scratch yourself!
+Resyncing with devicetree-rebasing
+----------------------------------
+
+The devicetee-rebasing repository (dtrepo_) 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.
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
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
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
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_).
+
+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
-----------------------
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
+.. _dtschema: https://github.com/devicetree-org/dt-schema/tree/main
projects / u-boot.git / commitdiff
