1.. _dt-binding-compat:
2
3Introduction to Devicetree Bindings
4###################################
5
6.. note::
7
8   For a detailed syntax reference, see :ref:`dt-bindings-file-syntax`.
9
10Devicetree nodes are matched to bindings using their :ref:`compatible
11properties <dt-important-props>`.
12
13During the :ref:`build_configuration_phase`, the build system tries to match
14each node in the devicetree to a binding file. When this succeeds, the build
15system uses the information in the binding file both when validating the node's
16contents and when generating macros for the node.
17
18.. _dt-bindings-simple-example:
19
20A simple example
21****************
22
23Here is an example devicetree node:
24
25.. code-block:: devicetree
26
27   /* Node in a DTS file */
28   bar-device {
29   	compatible = "foo-company,bar-device";
30        num-foos = <3>;
31   };
32
33Here is a minimal binding file which matches the node:
34
35.. code-block:: yaml
36
37   # A YAML binding matching the node
38
39   compatible: "foo-company,bar-device"
40
41   properties:
42     num-foos:
43       type: int
44       required: true
45
46The build system matches the ``bar-device`` node to its YAML binding because
47the node's ``compatible`` property matches the binding's ``compatible:`` line.
48
49What the build system does with bindings
50****************************************
51
52The build system uses bindings both to validate devicetree nodes and to convert
53the devicetree's contents into the generated :ref:`devicetree_generated.h
54<dt-outputs>` header file.
55
56For example, the build system would use the above binding to check that the
57required ``num-foos`` property is present in the ``bar-device`` node, and that
58its value, ``<3>``, has the correct type.
59
60The build system will then generate a macro for the ``bar-device`` node's
61``num-foos`` property, which will expand to the integer literal ``3``. This
62macro lets you get the value of the property in C code using the API which is
63discussed later in this guide in :ref:`dt-from-c`.
64
65For another example, the following node would cause a build error, because it
66has no ``num-foos`` property, and this property is marked required in the
67binding:
68
69.. code-block:: devicetree
70
71   bad-node {
72   	compatible = "foo-company,bar-device";
73   };
74
75Other ways nodes are matched to bindings
76****************************************
77
78If a node has more than one string in its ``compatible`` property, the build
79system looks for compatible bindings in the listed order and uses the first
80match.
81
82Take this node as an example:
83
84.. code-block:: devicetree
85
86   baz-device {
87   	compatible = "foo-company,baz-device", "generic-baz-device";
88   };
89
90The ``baz-device`` node would get matched to a binding with a ``compatible:
91"generic-baz-device"`` line if the build system can't find a binding with a
92``compatible: "foo-company,baz-device"`` line.
93
94Nodes without compatible properties can be matched to bindings associated with
95their parent nodes. These are called "child bindings". If a node describes
96hardware on a bus, like I2C or SPI, then the bus type is also taken into
97account when matching nodes to bindings. (See :ref:`dt-bindings-on-bus` for
98details).
99
100See :ref:`dt-zephyr-user` for information about a special node that doesn't
101require any binding.
102
103.. _dt-where-bindings-are-located:
104
105Where bindings are located
106**************************
107
108Binding file names usually match their ``compatible:`` lines. For example, the
109above example binding would be named :file:`foo-company,bar-device.yaml` by
110convention.
111
112The build system looks for bindings in :file:`dts/bindings`
113subdirectories of the following places:
114
115- the zephyr repository
116- your :ref:`application source directory <application>`
117- your :ref:`board directory <board_porting_guide>`
118- any :ref:`shield directories <shields>`
119- any directories manually included in the :ref:`DTS_ROOT <dts_root>`
120  CMake variable
121- any :ref:`module <modules>` that defines a ``dts_root`` in its
122  :ref:`modules_build_settings`
123
124The build system will consider any YAML file in any of these, including in any
125subdirectories, when matching nodes to bindings. A file is considered YAML if
126its name ends with ``.yaml`` or ``.yml``.
127
128.. warning::
129
130   The binding files must be located somewhere inside the :file:`dts/bindings`
131   subdirectory of the above places.
132
133   For example, if :file:`my-app` is your application directory, then you must
134   place application-specific bindings inside :file:`my-app/dts/bindings`. So
135   :file:`my-app/dts/bindings/serial/my-company,my-serial-port.yaml` would be
136   found, but :file:`my-app/my-company,my-serial-port.yaml` would be ignored.
137