1.. _dt-writing-bindings:
2
3Rules for upstream bindings
4###########################
5
6This section includes general rules for writing bindings that you want to
7submit to the upstream Zephyr Project. (You don't need to follow these rules
8for bindings you don't intend to contribute to the Zephyr Project, but it's a
9good idea.)
10
11Decisions made by the Zephyr devicetree maintainer override the contents of
12this section. If that happens, though, please let them know so they can update
13this page, or you can send a patch yourself.
14
15.. contents:: Contents
16   :local:
17
18Always check for existing bindings
19**********************************
20
21Zephyr aims for devicetree :ref:`dt-source-compatibility`. Therefore, if there
22is an existing binding for your device in an authoritative location, you should
23try to replicate its properties when writing a Zephyr binding, and you must
24justify any Zephyr-specific divergences.
25
26In particular, this rule applies if:
27
28- There is an existing binding in the mainline Linux kernel. See
29  :file:`Documentation/devicetree/bindings` in `Linus's tree`_ for existing
30  bindings and the `Linux devicetree documentation`_ for more information.
31
32- Your hardware vendor provides an official binding outside of the Linux
33  kernel.
34
35.. _Linus's tree:
36   https://github.com/torvalds/linux/
37
38.. _Linux devicetree documentation:
39   https://www.kernel.org/doc/html/latest/devicetree/index.html
40
41General rules
42*************
43
44Wherever possible, when writing Devicetree bindings for Zephyr, try to follow
45the same `design guidelines laid out by Linux`_.
46
47.. _design guidelines laid out by Linux:
48   https://docs.kernel.org/devicetree/bindings/writing-bindings.html
49
50File names
51==========
52
53Bindings which match a compatible must have file names based on the compatible.
54
55- For example, a binding for compatible ``vnd,foo`` must be named ``vnd,foo.yaml``.
56- If the binding is bus-specific, you can append the bus to the file name;
57  for example, if the binding YAML has ``on-bus: bar``, you may name the file
58  ``vnd,foo-bar.yaml``.
59
60Recommendations are requirements
61================================
62
63All recommendations in :ref:`dt-bindings-default` are requirements when
64submitting the binding.
65
66In particular, if you use the ``default:`` feature, you must justify the
67value in the property's description.
68
69Descriptions
70============
71
72There are only two acceptable ways to write property ``description:``
73strings.
74
75If your description is short, it's fine to use this style:
76
77.. code-block:: yaml
78
79   description: my short string
80
81If your description is long or spans multiple lines, you must use this
82style:
83
84.. code-block:: yaml
85
86   description: |
87     My very long string
88     goes here.
89     Look at all these lines!
90
91This ``|`` style prevents YAML parsers from removing the newlines in
92multi-line descriptions. This in turn makes these long strings
93display properly in the :ref:`devicetree_binding_index`.
94
95Naming conventions
96==================
97
98Do not use uppercase letters (``A`` through ``Z``) or underscores (``_``) in
99property names. Use lowercase letters (``a`` through ``z``) instead of
100uppercase. Use dashes (``-``) instead of underscores. (The one exception to
101this rule is if you are replicating a well-established binding from somewhere
102like Linux.)
103
104Rules for vendor prefixes
105*************************
106
107The following general rules apply to vendor prefixes in :ref:`compatible
108<dt-important-props>` properties.
109
110- If your device is manufactured by a specific vendor, then its compatible
111  should have a vendor prefix.
112
113  If your binding describes hardware with a well known vendor from the list in
114  :zephyr_file:`dts/bindings/vendor-prefixes.txt`, you must use that vendor
115  prefix.
116
117- If your device is not manufactured by a specific hardware vendor, do **not**
118  invent a vendor prefix. Vendor prefixes are not mandatory parts of compatible
119  properties, and compatibles should not include them unless they refer to an
120  actual vendor. There are some exceptions to this rule, but the practice is
121  strongly discouraged.
122
123- Do not submit additions to Zephyr's :file:`dts/bindings/vendor-prefixes.txt`
124  file unless you also include users of the new prefix. This means at least a
125  binding and a devicetree using the vendor prefix, and should ideally include
126  a device driver handling that compatible.
127
128  For custom bindings, you can add a custom
129  :file:`dts/bindings/vendor-prefixes.txt` file to any directory in your
130  :ref:`DTS_ROOT <dts_root>`. The devicetree tooling will respect these
131  prefixes, and will not generate warnings or errors if you use them in your
132  own bindings or devicetrees.
133
134- We sometimes synchronize Zephyr's vendor-prefixes.txt file with the Linux
135  kernel's equivalent file; this process is exempt from the previous rule.
136
137- If your binding is describing an abstract class of hardware with Zephyr
138  specific drivers handling the nodes, it's usually best to use ``zephyr`` as
139  the vendor prefix. See :ref:`dt_vendor_zephyr` for examples.
140
141.. _dt-bindings-default-rules:
142
143Rules for default values
144************************
145
146In any case where ``default:`` is used in a devicetree binding, the
147``description:`` for that property **must** explain *why* the value was
148selected and any conditions that would make it necessary to provide a different
149value. Additionally, if changing one property would require changing another to
150create a consistent configuration, then those properties should be made
151required.
152
153There is no need to document the default value itself; this is already present
154in the :ref:`devicetree_binding_index` output.
155
156There is a risk in using ``default:`` when the value in the binding may be
157incorrect for a particular board or hardware configuration.  For example,
158defaulting the capacity of the connected power cell in a charging IC binding
159is likely to be incorrect.  For such properties it's better to make the
160property ``required: true``, forcing the user to make an explicit choice.
161
162Driver developers should use their best judgment as to whether a value can be
163safely defaulted. Candidates for default values include:
164
165- delays that would be different only under unusual conditions
166  (such as intervening hardware)
167- configuration for devices that have a standard initial configuration (such as
168  a USB audio headset)
169- defaults which match the vendor-specified power-on reset value
170  (as long as they are independent from other properties)
171
172Examples of how to write descriptions according to these rules:
173
174.. code-block:: yaml
175
176   properties:
177     cs-interval:
178       type: int
179       default: 0
180       description: |
181         Minimum interval between chip select deassertion and assertion.
182         The default corresponds to the reset value of the register field.
183     hold-time-ms:
184       type: int
185       default: 20
186       description: |
187         Amount of time to hold the power enable GPIO asserted before
188         initiating communication. The default was recommended in the
189         manufacturer datasheet, and would only change under very
190         cold temperatures.
191
192Some examples of what **not** to do, and why:
193
194.. code-block:: yaml
195
196   properties:
197     # Description doesn't mention anything about the default
198     foo:
199       type: int
200       default: 1
201       description: number of foos
202
203     # Description mentions the default value instead of why it
204     # was chosen
205     bar:
206       type: int
207       default: 2
208       description: bar size; default is 2
209
210     # Explanation of the default value is in a comment instead
211     # of the description. This won't be shown in the bindings index.
212     baz:
213       type: int
214       # This is the recommended value chosen by the manufacturer.
215       default: 2
216       description: baz time in milliseconds
217
218The ``zephyr,`` prefix
219**********************
220
221You must add this prefix to property names in the following cases:
222
223- Zephyr-specific extensions to bindings we share with upstream Linux. One
224  example is the ``zephyr,vref-mv`` ADC channel property which is common to ADC
225  controllers defined in :zephyr_file:`dts/bindings/adc/adc-controller.yaml`.
226  This channel binding is partially shared with an analogous Linux binding, and
227  Zephyr-specific extensions are marked as such with the prefix.
228
229- Configuration values that are specific to a Zephyr device driver. One example
230  is the ``zephyr,lazy-load`` property in the :dtcompatible:`ti,bq274xx`
231  binding. Though devicetree in general is a hardware description and
232  configuration language, it is Zephyr's only mechanism for configuring driver
233  behavior for an individual ``struct device``. Therefore, as a compromise,
234  we do allow some software configuration in Zephyr's devicetree bindings, as
235  long as they use this prefix to show that they are Zephyr specific.
236
237You may use the ``zephyr,`` prefix when naming a devicetree compatible that is
238specific to Zephyr. One example is
239:dtcompatible:`zephyr,ipc-openamp-static-vrings`. In this case, it's permitted
240but not required to add the ``zephyr,`` prefix to properties defined in the
241binding.
242