1.. _devicetree-scope-purpose:
2
3Scope and purpose
4*****************
5
6A *devicetree* is primarily a hierarchical data structure that describes
7hardware. The `Devicetree specification`_ defines its source and binary
8representations.
9
10.. _Devicetree specification: https://www.devicetree.org/
11
12Zephyr uses devicetree to describe:
13
14- the hardware available on its :ref:`boards`
15- that hardware's initial configuration
16
17As such, devicetree is both a hardware description language and a configuration
18language for Zephyr. See :ref:`dt_vs_kconfig` for some comparisons between
19devicetree and Zephyr's other main configuration language, Kconfig.
20
21There are two types of devicetree input files: *devicetree sources* and
22*devicetree bindings*. The sources contain the devicetree itself. The bindings
23describe its contents, including data types. The :ref:`build system
24<build_overview>` uses devicetree sources and bindings to produce a generated C
25header. The generated header's contents are abstracted by the ``devicetree.h``
26API, which you can use to get information from your devicetree.
27
28Here is a simplified view of the process:
29
30.. figure:: zephyr_dt_build_flow.png
31   :figclass: align-center
32
33   Devicetree build flow
34
35All Zephyr and application source code files can include and use
36``devicetree.h``. This includes :ref:`device drivers <device_model_api>`,
37:ref:`applications <application>`, :ref:`tests <testing>`, the kernel, etc.
38
39The API itself is based on C macros. The macro names all start with ``DT_``. In
40general, if you see a macro that starts with ``DT_`` in a Zephyr source file,
41it's probably a ``devicetree.h`` macro. The generated C header contains macros
42that start with ``DT_`` as well; you might see those in compiler error
43messages. You always can tell a generated- from a non-generated macro:
44generated macros have some lowercased letters, while the ``devicetree.h`` macro
45names have all capital letters.
46