Lines Matching +full:child +full:- +full:binding
1 .. _dt-bindings-file-syntax:
7 files are YAML files. A :ref:`simple example <dt-bindings-simple-example>` was
17 The top level of a bindings file maps keys to values. The top-level keys look
20 .. code-block:: yaml
22 # A high level description of the device the binding applies to:
24 This is the Vendomatic company's foo-device.
29 See https://yaml-multiline.info/ for formatting help.
34 # Used to match nodes to this binding:
35 compatible: "manufacturer,foo-device"
39 # binding's nodes need to satisfy go here.
41 child-binding:
42 # You can constrain the children of the nodes matching this binding
50 # SPI memory chip, use 'on-bus:' to say what type of bus, like this.
53 on-bus: spi
55 foo-cells:
61 .. _dt-bindings-description:
66 A free-form description of node hardware goes here. You can put links to
69 .. _dt-bindings-compatible:
74 This key is used to match nodes to this binding as described in
75 :ref:`dt-binding-compat`. It should look like this in a binding file:
77 .. code-block:: YAML
79 # Note the comma-separated vendor prefix and device name
82 This devicetree node would match the above binding:
84 .. code-block:: devicetree
90 Assuming no binding has ``compatible: "manufacturer,device-v2"``, it would also
93 .. code-block:: devicetree
95 device-2 {
96 compatible = "manufacturer,device-v2", "manufacturer,device";
100 binding is used. The :ref:`on-bus: <dt-bindings-on-bus>` key can be used to
103 If more than one binding for a compatible is found, an error is raised.
106 :zephyr_file:`dts/bindings/vendor-prefixes.txt` for a list of accepted vendor
111 :dtcompatible:`gpio-leds` compatible which is commonly used to describe board
114 .. _dt-bindings-properties:
119 The ``properties:`` key describes properties that nodes which match the binding
120 contain. For example, a binding for a UART peripheral might look something like
123 .. code-block:: YAML
132 current-speed:
138 a property named ``current-speed``. The property's value must be a single
143 source code from these macros in :ref:`dt-from-c`. Generally speaking, the
145 key for the matching binding. Properties not mentioned in the binding are
149 standard properties, like :ref:`reg <dt-important-props>`, whose meaning is
151 node has a matching binding or not.
158 .. code-block:: none
162 type: <string | int | boolean | array | uint8-array | string-array |
163 phandle | phandles | phandle-array | path | compound>
168 - <item1>
169 - <item2>
171 - <itemN>
172 const: <string | int | array | uint8-array | string-array>
173 specifier-space: <space-name>
175 .. _dt-bindings-example-properties:
182 .. code-block:: YAML
185 # Describes a property like 'current-speed = <115200>;'. We pretend that
187 current-speed:
190 description: Initial baud rate for bar-device
194 type: string-array
195 description: Keys for bar-device
197 # Describes an optional property like 'maximum-speed = "full-speed";'
199 maximum-speed:
203 - "low-speed"
204 - "full-speed"
205 - "high-speed"
206 - "super-speed"
213 - 8
214 - 16
215 - 24
216 - 32
218 # Describes a required property '#address-cells = <1>'; the const
220 "#address-cells":
225 int-with-default:
228 description: Value for int register, default is power-up configuration.
230 array-with-default:
232 default: [1, 2, 3] # Same as 'array-with-default = <1 2 3>'
234 string-with-default:
238 string-array-with-default:
239 type: string-array
240 default: ["foo", "bar"] # Same as 'string-array-with-default = "foo", "bar"'
242 uint8-array-with-default:
243 type: uint8-array
244 default: [0x12, 0x34] # Same as 'uint8-array-with-default = [12 34]'
250 node matches the binding, but does not contain the property.
260 available. See :ref:`dt-writing-property-values` for more details about writing
261 values of each type in a DTS file. See :ref:`dt-phandles` for more information
264 .. list-table::
265 :header-rows: 1
268 * - Type
269 - Description
270 - Example in DTS
272 * - ``string``
273 - exactly one string
274 - ``status = "disabled";``
276 * - ``int``
277 - exactly one 32-bit value (cell)
278 - ``current-speed = <115200>;``
280 * - ``boolean``
281 - flags that don't take a value when true, and are absent if false
282 - ``hw-flow-control;``
284 * - ``array``
285 - zero or more 32-bit values (cells)
286 - ``offsets = <0x100 0x200 0x300>;``
288 * - ``uint8-array``
289 - zero or more bytes, in hex ('bytestring' in the Devicetree specification)
290 - ``local-mac-address = [de ad be ef 12 34];``
292 * - ``string-array``
293 - zero or more strings
294 - ``dma-names = "tx", "rx";``
296 * - ``phandle``
297 - exactly one phandle
298 - ``interrupt-parent = <&gic>;``
300 * - ``phandles``
301 - zero or more phandles
302 - ``pinctrl-0 = <&usart2_tx_pd5 &usart2_rx_pd6>;``
304 * - ``phandle-array``
305 - a list of phandles and 32-bit cells (usually specifiers)
306 - ``dmas = <&dma0 2>, <&dma0 3>;``
308 * - ``path``
309 - a path to a node as a phandle path reference or path string
310 - ``zephyr,bt-c2h-uart = &uart0;`` or
313 * - ``compound``
314 - a catch-all for more complex types (no macros will be generated)
315 - ``foo = <&label>, [01 02];``
330 .. _dt-bindings-default:
338 For example, with this binding fragment:
340 .. code-block:: YAML
354 :ref:`dt-bindings-default-rules`.
356 See :ref:`dt-bindings-example-properties` for examples. Putting ``default:`` on
357 any property type besides those used in :ref:`dt-bindings-example-properties`
364 a property value in DTS is not in the ``enum:`` list in the binding, an error
365 is raised. See :ref:`dt-bindings-example-properties` for examples.
374 .. _dt-bindings-specifier-space:
376 specifier-space
385 ``my-pin``, then assigning it to the "gpio" specifier space using this
387 end in ``-gpios`` or ``-gpio``.
390 property with type ``phandle-array``.
393 property named ``foos`` with type ``phandle-array`` implicitly has specifier
394 space ``foo``. As a special case, ``*-gpios`` properties have specifier space
395 "gpio", so that ``foo-gpios`` will have specifier space "gpio" rather than
396 "foo-gpio".
398 You can use ``specifier-space`` to manually provide a space if
403 .. code-block:: YAML
408 type: phandle-array
409 specifier-space: my-custom-space
411 Above, the ``bar`` property's specifier space is set to "my-custom-space".
415 .. code-block:: DTS
417 controller1: custom-controller@1000 {
418 #my-custom-space-cells = <2>;
421 controller2: custom-controller@2000 {
422 #my-custom-space-cells = <1>;
425 my-node {
434 .. code-block:: YAML
438 type: phandle-array
439 specifier-space: mbox
441 .. _dt-bindings-child:
443 Child-binding section in Devicetree bindings syntax
446 ``child-binding`` can be used when a node has children that all share the same
447 properties. Each child gets the contents of ``child-binding`` as its binding,
448 though an explicit ``compatible = ...`` on the child node takes precedence, if
449 a binding is found for it.
451 Consider a binding for a PWM LED node like this one, where the child nodes are
454 .. code-block:: devicetree
457 compatible = "pwm-leds";
468 The binding would look like this:
470 .. code-block:: YAML
472 compatible: "pwm-leds"
474 child-binding:
479 type: phandle-array
482 ``child-binding`` also works recursively. For example, this binding:
484 .. code-block:: YAML
488 child-binding:
489 child-binding:
491 my-property:
497 .. code-block:: devicetree
501 child {
503 my-property = <123>;
508 .. _dt-bindings-bus:
513 If the node is a bus controller, use ``bus:`` in the binding to say what type
514 of bus. For example, a binding for a SPI peripheral on an SoC would look like
517 .. code-block:: YAML
519 compatible: "manufacturer,spi-peripheral"
523 The presence of this key in the binding informs the build system that the
524 children of any node matching this binding appear on this type of bus.
526 This in turn influences the way ``on-bus:`` is used to match bindings for the
527 child nodes.
530 in the binding can have a list as value:
532 .. code-block:: YAML
534 compatible: "manufacturer,i3c-controller"
538 .. _dt-bindings-on-bus:
540 On-bus
543 If the node appears as a device on a bus, use ``on-bus:`` in the binding to say
546 For example, a binding for an external SPI memory chip should include this line:
548 .. code-block:: YAML
550 on-bus: spi
552 And a binding for an I2C based temperature sensor should include this line:
554 .. code-block:: YAML
556 on-bus: i2c
558 When looking for a binding for a node, the build system checks if the binding
560 bindings with a matching ``on-bus: <bus type>`` and bindings without an
561 explicit ``on-bus`` are considered. Bindings with an explicit ``on-bus: <bus
562 type>`` are searched for first, before bindings without an explicit ``on-bus``.
570 The sensor node may therefore appear in the devicetree as a child node of
573 .. code-block:: devicetree
575 spi-bus@0 {
585 i2c-bus@0 {
595 You can write two separate binding files which match these individual sensor
598 .. code-block:: YAML
600 # manufacturer,sensor-spi.yaml, which matches sensor@0 on the SPI bus:
602 on-bus: spi
604 # manufacturer,sensor-i2c.yaml, which matches sensor@79 on the I2C bus:
607 uses-clock-stretching:
609 on-bus: i2c
611 Only ``sensor@79`` can have a ``use-clock-stretching`` property. The
612 bus-sensitive logic ignores :file:`manufacturer,sensor-i2c.yaml` when searching
613 for a binding for ``sensor@0``.
615 .. _dt-bindings-cells:
617 Specifier cell names (\*-cells)
620 This section documents how to name the cells in a specifier within a binding.
622 :ref:`dt-phandle-arrays`.
624 Consider a binding for a node whose phandle may appear in a ``phandle-array``
627 .. code-block:: DTS
631 #pwm-cells = <2>;
636 #pwm-cells = <1>;
639 my-node {
644 the cells that appear in a PWM specifier using ``pwm-cells:``, like this:
646 .. code-block:: YAML
651 pwm-cells:
652 - channel
653 - period
658 pwm-cells:
659 - period
661 A ``*-names`` (e.g. ``pwm-names``) property can appear on the node as well,
667 If the specifier is empty (e.g. ``#clock-cells = <0>``), then ``*-cells`` can
669 array is specified as e.g. ``clock-cells: []`` in YAML.
671 .. _dt-bindings-include:
683 .. code-block:: YAML
688 :ref:`dt-where-bindings-are-located` for the search process), it will be
689 included into this binding.
692 merge. The build system will check that the resulting merged binding is
693 well-formed. It is allowed to include at any level, including ``child-binding``,
696 .. code-block:: YAML
701 child-binding:
705 It is an error if a key appears with a different value in a binding and in a
706 file it includes, with one exception: a binding can have ``required: true`` for
707 a :ref:`property definition <dt-bindings-properties>` for which the included
716 definitions for many common properties. When writing a new binding, it is a
721 taking :ref:`reg <dt-important-props>` as an example:
723 .. code-block:: YAML
733 .. code-block:: YAML
736 - foo.yaml
737 - bar.yaml
751 .. code-block:: YAML
754 - name: foo.yaml
755 property-allowlist:
756 - i-want-this-one
757 - and-this-one
758 - name: bar.yaml
759 property-blocklist:
760 - do-not-include-this-one
761 - or-this-one
764 may have ``property-allowlist`` and ``property-blocklist`` keys that filter
767 You cannot have a single map element with both ``property-allowlist`` and
768 ``property-blocklist`` keys. A map element with neither ``property-allowlist``
769 nor ``property-blocklist`` is valid; no additional filtering is done.
773 .. code-block:: YAML
776 - foo.yaml
777 - name: bar.yaml
778 property-blocklist:
779 - do-not-include-this-one
780 - or-this-one
782 Finally, you can filter from a child binding like this:
784 .. code-block:: YAML
787 - name: bar.yaml
788 child-binding:
789 property-allowlist:
790 - child-prop-to-allow
795 All ``phandle-array`` type properties support mapping through ``*-map``
796 properties, e.g. ``gpio-map``, as defined by the Devicetree specification.