141 lines
5.4 KiB
ReStructuredText
141 lines
5.4 KiB
ReStructuredText
.. _devicetree-in-out-files:
|
|
|
|
Input and output files
|
|
######################
|
|
|
|
This section describes the input and output files shown in the figure in
|
|
:ref:`devicetree-scope-purpose` in more detail.
|
|
|
|
.. figure:: zephyr_dt_inputs_outputs.svg
|
|
:figclass: align-center
|
|
|
|
Devicetree input (green) and output (yellow) files
|
|
|
|
.. _dt-input-files:
|
|
|
|
Input files
|
|
***********
|
|
|
|
There are four types of devicetree input files:
|
|
|
|
- sources (``.dts``)
|
|
- includes (``.dtsi``)
|
|
- overlays (``.overlay``)
|
|
- bindings (``.yaml``)
|
|
|
|
The devicetree files inside the :file:`zephyr` directory look like this:
|
|
|
|
.. code-block:: none
|
|
|
|
boards/<ARCH>/<BOARD>/<BOARD>.dts
|
|
dts/common/skeleton.dtsi
|
|
dts/<ARCH>/.../<SOC>.dtsi
|
|
dts/bindings/.../binding.yaml
|
|
|
|
Generally speaking, every supported board has a :file:`BOARD.dts` file
|
|
describing its hardware. For example, the ``reel_board`` has
|
|
:zephyr_file:`boards/phytec/reel_board/reel_board.dts`.
|
|
|
|
:file:`BOARD.dts` includes one or more ``.dtsi`` files. These ``.dtsi`` files
|
|
describe the CPU or system-on-chip Zephyr runs on, perhaps by including other
|
|
``.dtsi`` files. They can also describe other common hardware features shared by
|
|
multiple boards. In addition to these includes, :file:`BOARD.dts` also describes
|
|
the board's specific hardware.
|
|
|
|
The :file:`dts/common` directory contains :file:`skeleton.dtsi`, a minimal
|
|
include file for defining a complete devicetree. Architecture-specific
|
|
subdirectories (:file:`dts/<ARCH>`) contain ``.dtsi`` files for CPUs or SoCs
|
|
which extend :file:`skeleton.dtsi`.
|
|
|
|
The C preprocessor is run on all devicetree files to expand macro references,
|
|
and includes are generally done with ``#include <filename>`` directives, even
|
|
though DTS has a ``/include/ "<filename>"`` syntax.
|
|
|
|
:file:`BOARD.dts` can be extended or modified using *overlays*. Overlays are
|
|
also DTS files; the :file:`.overlay` extension is just a convention which makes
|
|
their purpose clear. Overlays adapt the base devicetree for different purposes:
|
|
|
|
- Zephyr applications can use overlays to enable a peripheral that is disabled
|
|
by default, select a sensor on the board for an application specific purpose,
|
|
etc. Along with :ref:`kconfig`, this makes it possible to reconfigure the
|
|
kernel and device drivers without modifying source code.
|
|
|
|
- Overlays are also used when defining :ref:`shields`.
|
|
|
|
The build system automatically picks up :file:`.overlay` files stored in
|
|
certain locations. It is also possible to explicitly list the overlays to
|
|
include, via the :makevar:`DTC_OVERLAY_FILE` CMake variable. See
|
|
:ref:`set-devicetree-overlays` for details.
|
|
|
|
The build system combines :file:`BOARD.dts` and any :file:`.overlay` files by
|
|
concatenating them, with the overlays put last. This relies on DTS syntax which
|
|
allows merging overlapping definitions of nodes in the devicetree. See
|
|
:ref:`dt_k6x_example` for an example of how this works (in the context of
|
|
``.dtsi`` files, but the principle is the same for overlays). Putting the
|
|
contents of the :file:`.overlay` files last allows them to override
|
|
:file:`BOARD.dts`.
|
|
|
|
:ref:`dt-bindings` (which are YAML files) are essentially glue. They describe
|
|
the contents of devicetree sources, includes, and overlays in a way that allows
|
|
the build system to generate C macros usable by device drivers and
|
|
applications. The :file:`dts/bindings` directory contains bindings.
|
|
|
|
.. _dt-scripts:
|
|
|
|
Scripts and tools
|
|
*****************
|
|
|
|
The following libraries and scripts, located in :zephyr_file:`scripts/dts/`,
|
|
create output files from input files. Their sources have extensive
|
|
documentation.
|
|
|
|
:zephyr_file:`dtlib.py <scripts/dts/python-devicetree/src/devicetree/dtlib.py>`
|
|
A low-level DTS parsing library.
|
|
|
|
:zephyr_file:`edtlib.py <scripts/dts/python-devicetree/src/devicetree/edtlib.py>`
|
|
A library layered on top of dtlib that uses bindings to interpret
|
|
properties and give a higher-level view of the devicetree. Uses dtlib to do
|
|
the DTS parsing.
|
|
|
|
:zephyr_file:`gen_defines.py <scripts/dts/python-devicetree/src/devicetree/edtlib.py>`
|
|
A script that uses edtlib to generate C preprocessor macros from the
|
|
devicetree and bindings.
|
|
|
|
In addition to these, the standard ``dtc`` (devicetree compiler) tool is run on
|
|
the final devicetree if it is installed on your system. This is just to catch
|
|
errors or warnings. The output is unused. Boards may need to pass ``dtc``
|
|
additional flags, e.g. for warning suppression. Board directories can contain a
|
|
file named :file:`pre_dt_board.cmake` which configures these extra flags, like
|
|
this:
|
|
|
|
.. code-block:: cmake
|
|
|
|
list(APPEND EXTRA_DTC_FLAGS "-Wno-simple_bus_reg")
|
|
|
|
.. _dt-outputs:
|
|
|
|
Output files
|
|
************
|
|
|
|
These are created in your application's build directory.
|
|
|
|
.. warning::
|
|
|
|
Don't include the header files directly. :ref:`dt-from-c` explains
|
|
what to do instead.
|
|
|
|
:file:`<build>/zephyr/zephyr.dts.pre`
|
|
The preprocessed DTS source. This is an intermediate output file, which is
|
|
input to :file:`gen_defines.py` and used to create :file:`zephyr.dts` and
|
|
:file:`devicetree_generated.h`.
|
|
|
|
:file:`<build>/zephyr/include/generated/zephyr/devicetree_generated.h`
|
|
The generated macros and additional comments describing the devicetree.
|
|
Included by ``devicetree.h``.
|
|
|
|
:file:`<build>/zephyr/zephyr.dts`
|
|
The final merged devicetree. This file is output by :file:`gen_defines.py`.
|
|
It is useful for debugging any issues. If the devicetree compiler ``dtc`` is
|
|
installed, it is also run on this file, to catch any additional warnings or
|
|
errors.
|