forked from OERV-BSP/u-boot
doc: devicetree: Updates for devicetree-rebasing subtree
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>
This commit is contained in:
Sumit Garg
@@ -1,5 +1,6 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0+
|
||||
.. sectionauthor:: Copyright 2011 The Chromium OS Authors
|
||||
.. Copyright 2023-2024 Linaro Ltd.
|
||||
|
||||
Devicetree Control in U-Boot
|
||||
============================
|
||||
@@ -22,12 +23,11 @@ for three reasons:
|
||||
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.
|
||||
|
||||
@@ -68,8 +68,16 @@ a binary file. U-Boot adds its own `fdtgrep` for creating subsets of the file.
|
||||
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
|
||||
@@ -78,17 +86,39 @@ 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
|
||||
@@ -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_).
|
||||
|
||||
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
|
||||
(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
|
||||
|
||||
Reference in New Issue
Block a user