bbe5e1e6eb
Namespaced the generated headers with `zephyr` to prevent potential conflict with other headers. Introduce a temporary Kconfig `LEGACY_GENERATED_INCLUDE_PATH` that is enabled by default. This allows the developers to continue the use of the old include paths for the time being until it is deprecated and eventually removed. The Kconfig will generate a build-time warning message, similar to the `CONFIG_TIMER_RANDOM_GENERATOR`. Updated the includes path of in-tree sources accordingly. Most of the changes here are scripted, check the PR for more info. Signed-off-by: Yong Cong Sin <ycsin@meta.com>
140 lines
5.4 KiB
ReStructuredText
140 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.
|