Lines Matching full:devicetree
3 Introduction to devicetree
8 This is a conceptual overview of devicetree and how Zephyr uses it. For
11 A *devicetree* is a hierarchical data structure that describes hardware. The
12 `Devicetree specification`_ defines its source and binary representations.
13 Zephyr uses devicetree to describe the hardware available on its :ref:`boards`,
16 There are two types of devicetree input files: *devicetree sources* and
17 *devicetree bindings*. The sources contain the devicetree itself. The bindings
19 <build_overview>` uses devicetree sources and bindings to produce a generated C
20 header. The generated header's contents are abstracted by the ``devicetree.h``
21 API, which you can use to get information from your devicetree.
28 Devicetree build flow
31 ``devicetree.h``. This includes :ref:`device drivers <device_model_api>`,
36 it's probably a ``devicetree.h`` macro. The generated C header contains macros
39 generated macros have some lowercased letters, while the ``devicetree.h`` macro
42 Some information defined in devicetree is available via ``CONFIG_`` macros
44 compatibility, since Zephyr has used Kconfig for longer than devicetree, and is
45 still in the process of converting some information from Kconfig to devicetree.
47 devicetree. Devicetree information is referenced from Kconfig via :ref:`Kconfig
56 As the name indicates, a devicetree is a tree. The human-readable text format
57 for this tree is called DTS (for devicetree source), and is defined in the
58 `Devicetree specification`_.
60 .. _Devicetree specification: https://www.devicetree.org/
64 .. code-block:: devicetree
88 refer to the labeled node elsewhere in the devicetree. Above, ``a-sub-node``
92 Devicetree nodes have *paths* identifying their locations in the tree. Like
93 Unix file system paths, devicetree paths are strings separated by slashes
99 Devicetree nodes can also have *properties*. Properties are name/value pairs.
108 In practice, devicetree nodes usually correspond to some hardware, and the node
118 present in the devicetree. Reflecting the hardware layout, the
124 .. code-block:: devicetree
151 I2C devicetree example with real-world names and properties.
157 .. code-block:: devicetree
190 introduces a new devicetree concept: unit addresses. Unit addresses are the
200 In devicetree, unit addresses give a node's address in the
229 This applies when the devicetree is used to store a flash partition table.
233 .. code-block:: devicetree
273 ``devicetree.h`` to find nodes with relevant compatibles, in order to
317 The devicetree specification allows this property to have values
323 not defined (i.e. does not exist in the devicetree source). Nodes with
326 this usage is deprecated.) Devicetree nodes which correspond to physical
334 `Devicetree Specification release v0.3`_ for more details.
336 Zephyr's devicetree bindings language lets you give a name to each cell in
340 https://www.devicetree.org/specifications/
353 curious about details, see the devicetree specification.
422 - Property values refer to other nodes in the devicetree by their *phandles*.
424 <dt-node-labels>`. Here is an example devicetree fragment:
426 .. code-block:: devicetree
440 In the devicetree, a phandle value is a cell -- which again is just a 32-bit
441 unsigned int. However, the Zephyr devicetree API generally exposes these
466 Here is an example devicetree which uses both:
468 .. code-block:: devicetree
489 device. Their purpose is to specify other nodes in the devicetree.
501 subsystem-wide values. See :ref:`devicetree-chosen-nodes` for more information.
509 :ref:`top of this introduction <devicetree-intro>` in more detail.
514 Devicetree input (green) and output (yellow) files
521 There are four types of devicetree input files:
528 The devicetree files inside the :file:`zephyr` directory look like this::
546 include file for defining a complete devicetree. Architecture-specific
550 The C preprocessor is run on all devicetree files to expand macro references,
556 their purpose clear. Overlays adapt the base devicetree for different purposes:
568 :ref:`set-devicetree-overlays` for details.
572 allows merging overlapping definitions of nodes in the devicetree. See
579 the contents of devicetree sources, includes, and overlays in a way that allows
603 properties and give a higher-level view of the devicetree. Uses dtlib to do
608 devicetree and bindings.
610 In addition to these, the standard ``dtc`` (devicetree compiler) tool is run on
611 the final devicetree if it is installed on your system. This is just to catch
634 The generated macros and additional comments describing the devicetree.
635 Included by ``devicetree.h``.
639 Included by ``devicetree.h``.
642 The final merged devicetree. This file is output by :file:`gen_defines.py`