1.. _devicetree-in-out-files:
2
3Input and output files
4######################
5
6This section describes the input and output files shown in the figure in
7:ref:`devicetree-scope-purpose` in more detail.
8
9.. figure:: zephyr_dt_inputs_outputs.svg
10   :figclass: align-center
11
12   Devicetree input (green) and output (yellow) files
13
14.. _dt-input-files:
15
16Input files
17***********
18
19There are four types of devicetree input files:
20
21- sources (``.dts``)
22- includes (``.dtsi``)
23- overlays (``.overlay``)
24- bindings (``.yaml``)
25
26The devicetree files inside the :file:`zephyr` directory look like this:
27
28.. code-block:: none
29
30  boards/<ARCH>/<BOARD>/<BOARD>.dts
31  dts/common/skeleton.dtsi
32  dts/<ARCH>/.../<SOC>.dtsi
33  dts/bindings/.../binding.yaml
34
35Generally speaking, every supported board has a :file:`BOARD.dts` file
36describing its hardware. For example, the ``reel_board`` has
37:zephyr_file:`boards/phytec/reel_board/reel_board.dts`.
38
39:file:`BOARD.dts` includes one or more ``.dtsi`` files. These ``.dtsi`` files
40describe the CPU or system-on-chip Zephyr runs on, perhaps by including other
41``.dtsi`` files. They can also describe other common hardware features shared by
42multiple boards. In addition to these includes, :file:`BOARD.dts` also describes
43the board's specific hardware.
44
45The :file:`dts/common` directory contains :file:`skeleton.dtsi`, a minimal
46include file for defining a complete devicetree. Architecture-specific
47subdirectories (:file:`dts/<ARCH>`) contain ``.dtsi`` files for CPUs or SoCs
48which extend :file:`skeleton.dtsi`.
49
50The C preprocessor is run on all devicetree files to expand macro references,
51and includes are generally done with ``#include <filename>`` directives, even
52though DTS has a ``/include/ "<filename>"`` syntax.
53
54:file:`BOARD.dts` can be extended or modified using *overlays*. Overlays are
55also DTS files; the :file:`.overlay` extension is just a convention which makes
56their purpose clear. Overlays adapt the base devicetree for different purposes:
57
58- Zephyr applications can use overlays to enable a peripheral that is disabled
59  by default, select a sensor on the board for an application specific purpose,
60  etc. Along with :ref:`kconfig`, this makes it possible to reconfigure the
61  kernel and device drivers without modifying source code.
62
63- Overlays are also used when defining :ref:`shields`.
64
65The build system automatically picks up :file:`.overlay` files stored in
66certain locations. It is also possible to explicitly list the overlays to
67include, via the :makevar:`DTC_OVERLAY_FILE` CMake variable. See
68:ref:`set-devicetree-overlays` for details.
69
70The build system combines :file:`BOARD.dts` and any :file:`.overlay` files by
71concatenating them, with the overlays put last. This relies on DTS syntax which
72allows merging overlapping definitions of nodes in the devicetree. See
73:ref:`dt_k6x_example` for an example of how this works (in the context of
74``.dtsi`` files, but the principle is the same for overlays). Putting the
75contents of the :file:`.overlay` files last allows them to override
76:file:`BOARD.dts`.
77
78:ref:`dt-bindings` (which are YAML files) are essentially glue. They describe
79the contents of devicetree sources, includes, and overlays in a way that allows
80the build system to generate C macros usable by device drivers and
81applications. The :file:`dts/bindings` directory contains bindings.
82
83.. _dt-scripts:
84
85Scripts and tools
86*****************
87
88The following libraries and scripts, located in :zephyr_file:`scripts/dts/`,
89create output files from input files. Their sources have extensive
90documentation.
91
92:zephyr_file:`dtlib.py <scripts/dts/python-devicetree/src/devicetree/dtlib.py>`
93    A low-level DTS parsing library.
94
95:zephyr_file:`edtlib.py <scripts/dts/python-devicetree/src/devicetree/edtlib.py>`
96    A library layered on top of dtlib that uses bindings to interpret
97    properties and give a higher-level view of the devicetree. Uses dtlib to do
98    the DTS parsing.
99
100:zephyr_file:`gen_defines.py <scripts/dts/python-devicetree/src/devicetree/edtlib.py>`
101    A script that uses edtlib to generate C preprocessor macros from the
102    devicetree and bindings.
103
104In addition to these, the standard ``dtc`` (devicetree compiler) tool is run on
105the final devicetree if it is installed on your system. This is just to catch
106errors or warnings. The output is unused. Boards may need to pass ``dtc``
107additional flags, e.g. for warning suppression. Board directories can contain a
108file named :file:`pre_dt_board.cmake` which configures these extra flags, like
109this:
110
111.. code-block:: cmake
112
113   list(APPEND EXTRA_DTC_FLAGS "-Wno-simple_bus_reg")
114
115.. _dt-outputs:
116
117Output files
118************
119
120These are created in your application's build directory.
121
122.. warning::
123
124   Don't include the header files directly. :ref:`dt-from-c` explains
125   what to do instead.
126
127:file:`<build>/zephyr/zephyr.dts.pre`
128   The preprocessed DTS source. This is an intermediate output file, which is
129   input to :file:`gen_defines.py` and used to create :file:`zephyr.dts` and
130   :file:`devicetree_generated.h`.
131
132:file:`<build>/zephyr/include/generated/zephyr/devicetree_generated.h`
133   The generated macros and additional comments describing the devicetree.
134   Included by ``devicetree.h``.
135
136:file:`<build>/zephyr/zephyr.dts`
137   The final merged devicetree. This file is output by :file:`gen_defines.py`.
138   It is useful for debugging any issues. If the devicetree compiler ``dtc`` is
139   installed, it is also run on this file, to catch any additional warnings or
140   errors.
141