242 lines
8.8 KiB
ReStructuredText
242 lines
8.8 KiB
ReStructuredText
.. _dt-writing-bindings:
|
|
|
|
Rules for upstream bindings
|
|
###########################
|
|
|
|
This section includes general rules for writing bindings that you want to
|
|
submit to the upstream Zephyr Project. (You don't need to follow these rules
|
|
for bindings you don't intend to contribute to the Zephyr Project, but it's a
|
|
good idea.)
|
|
|
|
Decisions made by the Zephyr devicetree maintainer override the contents of
|
|
this section. If that happens, though, please let them know so they can update
|
|
this page, or you can send a patch yourself.
|
|
|
|
.. contents:: Contents
|
|
:local:
|
|
|
|
Always check for existing bindings
|
|
**********************************
|
|
|
|
Zephyr aims for devicetree :ref:`dt-source-compatibility`. Therefore, if there
|
|
is an existing binding for your device in an authoritative location, you should
|
|
try to replicate its properties when writing a Zephyr binding, and you must
|
|
justify any Zephyr-specific divergences.
|
|
|
|
In particular, this rule applies if:
|
|
|
|
- There is an existing binding in the mainline Linux kernel. See
|
|
:file:`Documentation/devicetree/bindings` in `Linus's tree`_ for existing
|
|
bindings and the `Linux devicetree documentation`_ for more information.
|
|
|
|
- Your hardware vendor provides an official binding outside of the Linux
|
|
kernel.
|
|
|
|
.. _Linus's tree:
|
|
https://github.com/torvalds/linux/
|
|
|
|
.. _Linux devicetree documentation:
|
|
https://www.kernel.org/doc/html/latest/devicetree/index.html
|
|
|
|
General rules
|
|
*************
|
|
|
|
Wherever possible, when writing Devicetree bindings for Zephyr, try to follow
|
|
the same `design guidelines laid out by Linux`_.
|
|
|
|
.. _design guidelines laid out by Linux:
|
|
https://docs.kernel.org/devicetree/bindings/writing-bindings.html
|
|
|
|
File names
|
|
==========
|
|
|
|
Bindings which match a compatible must have file names based on the compatible.
|
|
|
|
- For example, a binding for compatible ``vnd,foo`` must be named ``vnd,foo.yaml``.
|
|
- If the binding is bus-specific, you can append the bus to the file name;
|
|
for example, if the binding YAML has ``on-bus: bar``, you may name the file
|
|
``vnd,foo-bar.yaml``.
|
|
|
|
Recommendations are requirements
|
|
================================
|
|
|
|
All recommendations in :ref:`dt-bindings-default` are requirements when
|
|
submitting the binding.
|
|
|
|
In particular, if you use the ``default:`` feature, you must justify the
|
|
value in the property's description.
|
|
|
|
Descriptions
|
|
============
|
|
|
|
There are only two acceptable ways to write property ``description:``
|
|
strings.
|
|
|
|
If your description is short, it's fine to use this style:
|
|
|
|
.. code-block:: yaml
|
|
|
|
description: my short string
|
|
|
|
If your description is long or spans multiple lines, you must use this
|
|
style:
|
|
|
|
.. code-block:: yaml
|
|
|
|
description: |
|
|
My very long string
|
|
goes here.
|
|
Look at all these lines!
|
|
|
|
This ``|`` style prevents YAML parsers from removing the newlines in
|
|
multi-line descriptions. This in turn makes these long strings
|
|
display properly in the :ref:`devicetree_binding_index`.
|
|
|
|
Naming conventions
|
|
==================
|
|
|
|
Do not use uppercase letters (``A`` through ``Z``) or underscores (``_``) in
|
|
property names. Use lowercase letters (``a`` through ``z``) instead of
|
|
uppercase. Use dashes (``-``) instead of underscores. (The one exception to
|
|
this rule is if you are replicating a well-established binding from somewhere
|
|
like Linux.)
|
|
|
|
Rules for vendor prefixes
|
|
*************************
|
|
|
|
The following general rules apply to vendor prefixes in :ref:`compatible
|
|
<dt-important-props>` properties.
|
|
|
|
- If your device is manufactured by a specific vendor, then its compatible
|
|
should have a vendor prefix.
|
|
|
|
If your binding describes hardware with a well known vendor from the list in
|
|
:zephyr_file:`dts/bindings/vendor-prefixes.txt`, you must use that vendor
|
|
prefix.
|
|
|
|
- If your device is not manufactured by a specific hardware vendor, do **not**
|
|
invent a vendor prefix. Vendor prefixes are not mandatory parts of compatible
|
|
properties, and compatibles should not include them unless they refer to an
|
|
actual vendor. There are some exceptions to this rule, but the practice is
|
|
strongly discouraged.
|
|
|
|
- Do not submit additions to Zephyr's :file:`dts/bindings/vendor-prefixes.txt`
|
|
file unless you also include users of the new prefix. This means at least a
|
|
binding and a devicetree using the vendor prefix, and should ideally include
|
|
a device driver handling that compatible.
|
|
|
|
For custom bindings, you can add a custom
|
|
:file:`dts/bindings/vendor-prefixes.txt` file to any directory in your
|
|
:ref:`DTS_ROOT <dts_root>`. The devicetree tooling will respect these
|
|
prefixes, and will not generate warnings or errors if you use them in your
|
|
own bindings or devicetrees.
|
|
|
|
- We sometimes synchronize Zephyr's vendor-prefixes.txt file with the Linux
|
|
kernel's equivalent file; this process is exempt from the previous rule.
|
|
|
|
- If your binding is describing an abstract class of hardware with Zephyr
|
|
specific drivers handling the nodes, it's usually best to use ``zephyr`` as
|
|
the vendor prefix. See :ref:`dt_vendor_zephyr` for examples.
|
|
|
|
.. _dt-bindings-default-rules:
|
|
|
|
Rules for default values
|
|
************************
|
|
|
|
In any case where ``default:`` is used in a devicetree binding, the
|
|
``description:`` for that property **must** explain *why* the value was
|
|
selected and any conditions that would make it necessary to provide a different
|
|
value. Additionally, if changing one property would require changing another to
|
|
create a consistent configuration, then those properties should be made
|
|
required.
|
|
|
|
There is no need to document the default value itself; this is already present
|
|
in the :ref:`devicetree_binding_index` output.
|
|
|
|
There is a risk in using ``default:`` when the value in the binding may be
|
|
incorrect for a particular board or hardware configuration. For example,
|
|
defaulting the capacity of the connected power cell in a charging IC binding
|
|
is likely to be incorrect. For such properties it's better to make the
|
|
property ``required: true``, forcing the user to make an explicit choice.
|
|
|
|
Driver developers should use their best judgment as to whether a value can be
|
|
safely defaulted. Candidates for default values include:
|
|
|
|
- delays that would be different only under unusual conditions
|
|
(such as intervening hardware)
|
|
- configuration for devices that have a standard initial configuration (such as
|
|
a USB audio headset)
|
|
- defaults which match the vendor-specified power-on reset value
|
|
(as long as they are independent from other properties)
|
|
|
|
Examples of how to write descriptions according to these rules:
|
|
|
|
.. code-block:: yaml
|
|
|
|
properties:
|
|
cs-interval:
|
|
type: int
|
|
default: 0
|
|
description: |
|
|
Minimum interval between chip select deassertion and assertion.
|
|
The default corresponds to the reset value of the register field.
|
|
hold-time-ms:
|
|
type: int
|
|
default: 20
|
|
description: |
|
|
Amount of time to hold the power enable GPIO asserted before
|
|
initiating communication. The default was recommended in the
|
|
manufacturer datasheet, and would only change under very
|
|
cold temperatures.
|
|
|
|
Some examples of what **not** to do, and why:
|
|
|
|
.. code-block:: yaml
|
|
|
|
properties:
|
|
# Description doesn't mention anything about the default
|
|
foo:
|
|
type: int
|
|
default: 1
|
|
description: number of foos
|
|
|
|
# Description mentions the default value instead of why it
|
|
# was chosen
|
|
bar:
|
|
type: int
|
|
default: 2
|
|
description: bar size; default is 2
|
|
|
|
# Explanation of the default value is in a comment instead
|
|
# of the description. This won't be shown in the bindings index.
|
|
baz:
|
|
type: int
|
|
# This is the recommended value chosen by the manufacturer.
|
|
default: 2
|
|
description: baz time in milliseconds
|
|
|
|
The ``zephyr,`` prefix
|
|
**********************
|
|
|
|
You must add this prefix to property names in the following cases:
|
|
|
|
- Zephyr-specific extensions to bindings we share with upstream Linux. One
|
|
example is the ``zephyr,vref-mv`` ADC channel property which is common to ADC
|
|
controllers defined in :zephyr_file:`dts/bindings/adc/adc-controller.yaml`.
|
|
This channel binding is partially shared with an analogous Linux binding, and
|
|
Zephyr-specific extensions are marked as such with the prefix.
|
|
|
|
- Configuration values that are specific to a Zephyr device driver. One example
|
|
is the ``zephyr,lazy-load`` property in the :dtcompatible:`ti,bq274xx`
|
|
binding. Though devicetree in general is a hardware description and
|
|
configuration language, it is Zephyr's only mechanism for configuring driver
|
|
behavior for an individual ``struct device``. Therefore, as a compromise,
|
|
we do allow some software configuration in Zephyr's devicetree bindings, as
|
|
long as they use this prefix to show that they are Zephyr specific.
|
|
|
|
You may use the ``zephyr,`` prefix when naming a devicetree compatible that is
|
|
specific to Zephyr. One example is
|
|
:dtcompatible:`zephyr,ipc-openamp-static-vrings`. In this case, it's permitted
|
|
but not required to add the ``zephyr,`` prefix to properties defined in the
|
|
binding.
|