112 lines
3.6 KiB
ReStructuredText
112 lines
3.6 KiB
ReStructuredText
.. _dt-bindings:
|
|
|
|
Devicetree bindings
|
|
###################
|
|
|
|
A devicetree on its own is only half the story for describing hardware. The
|
|
devicetree format itself is relatively unstructured, and doesn't tell the
|
|
:ref:`build system <build_overview>` which pieces of information in a
|
|
particular devicetree are useful to :ref:`device drivers <device_model_api>` or
|
|
:ref:`applications <application>`.
|
|
|
|
*Devicetree bindings* provide the other half of this information. Zephyr
|
|
devicetree bindings are YAML files in a custom format (Zephyr does not use the
|
|
dt-schema tools used by the Linux kernel). With one exception in
|
|
:ref:`dt-inferred-bindings` the build system uses bindings when generating
|
|
code for :ref:`dt-from-c`.
|
|
|
|
.. note::
|
|
|
|
See the :ref:`devicetree_binding_index` for information on existing
|
|
bindings.
|
|
|
|
.. _dt-binding-compat:
|
|
|
|
Mapping nodes to bindings
|
|
*************************
|
|
|
|
During the :ref:`build_configuration_phase`, the build system tries to map each
|
|
node in the devicetree to a binding file. When this succeeds, the build system
|
|
uses the information in the binding file when generating macros for the node.
|
|
|
|
Nodes are mapped to binding files by their :ref:`compatible properties
|
|
<dt-syntax>`. Take the following node as an example:
|
|
|
|
.. code-block:: DTS
|
|
|
|
bar-device {
|
|
compatible = "foo-company,bar-device";
|
|
/* ... */
|
|
};
|
|
|
|
The build system will try to map the ``bar-device`` node to a YAML binding with
|
|
this ``compatible:`` line:
|
|
|
|
.. code-block:: yaml
|
|
|
|
compatible: "foo-company,bar-device"
|
|
|
|
Built-in bindings are stored in :zephyr_file:`dts/bindings/`. Binding file
|
|
names usually match their ``compatible:`` lines, so the above binding would be
|
|
named :file:`foo-company,bar-device.yaml`.
|
|
|
|
If a node has more than one string in its ``compatible`` property, the build
|
|
system looks for compatible bindings in the listed order and uses the first
|
|
match. Take this node as an example:
|
|
|
|
.. code-block:: DTS
|
|
|
|
baz-device {
|
|
compatible = "foo-company,baz-device", "generic-baz-device";
|
|
};
|
|
|
|
The ``baz-device`` node would get mapped to the binding for compatible
|
|
``"generic-baz-device"`` if the build system can't find a binding for
|
|
``"foo-company,baz-device"``.
|
|
|
|
Nodes without compatible properties can be mapped to bindings associated with
|
|
their parent nodes. For an example, see the ``pwmleds`` node in the bindings
|
|
file format described below.
|
|
|
|
If a node describes hardware on a bus, like I2C or SPI, then the bus type is
|
|
also taken into account when mapping nodes to bindings. See the comments near
|
|
``on-bus:`` in the bindings syntax for details.
|
|
|
|
Bindings file syntax
|
|
********************
|
|
|
|
Below is a template that shows the Zephyr bindings file syntax. It is stored in
|
|
:zephyr_file:`dts/binding-template.yaml`.
|
|
|
|
.. literalinclude:: ../../../dts/binding-template.yaml
|
|
:language: yaml
|
|
|
|
.. _dt-inferred-bindings:
|
|
|
|
Inferred bindings
|
|
*****************
|
|
|
|
For sample code and applications it can be inconvenient to define a devicetree
|
|
binding when only a few simple properties are needed, such as the identify of
|
|
a GPIO for an application task. The devicetree syntax allows inference of a
|
|
binding for properties based on the value observed. This inference is
|
|
supported only for the ``/zephyr,user`` node. The properties referenced can
|
|
be accessed through the standard devicetree macros,
|
|
e.g. ``DT_PROP(DT_PATH(zephyr_user), bytes)``.
|
|
|
|
.. code-block:: DTS
|
|
|
|
/ {
|
|
zephyr,user {
|
|
boolean;
|
|
bytes = [81 82 83];
|
|
number = <23>;
|
|
numbers = <1>, <2>, <3>;
|
|
string = "text";
|
|
strings = "a", "b", "c";
|
|
handle = <&gpio0>;
|
|
handles = <&gpio0>, <&gpio1>;
|
|
signal-gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
|
|
};
|
|
};
|