Lines Matching +full:grandchild +full:- +full:prop
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
24 This is the Vendomatic company's foo-device.
29 See https://yaml-multiline.info/ for formatting help.
35 compatible: "manufacturer,foo-device"
41 child-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:
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
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
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:
123 .. code-block:: YAML
132 current-speed:
138 a node named ``current-speed``. The property's value must be a single integer.
143 source code from these macros in :ref:`dt-from-c`. Generally speaking, the
149 standard properties, like :ref:`reg <dt-important-props>`, whose meaning is
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]'
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:
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`
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
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,
454 .. code-block:: devicetree
457 compatible = "pwm-leds";
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:
495 will apply to the ``grandchild`` node in this DTS:
497 .. code-block:: devicetree
502 grandchild {
503 my-property = <123>;
508 .. _dt-bindings-bus:
517 .. code-block:: YAML
519 compatible: "manufacturer,spi-peripheral"
526 This in turn influences the way ``on-bus:`` is used to match bindings for the
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
548 .. code-block:: YAML
550 on-bus: spi
554 .. code-block:: YAML
556 on-bus: i2c
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``.
573 .. code-block:: devicetree
575 spi-bus@0 {
585 i2c-bus@0 {
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
615 .. _dt-bindings-cells:
617 Specifier cell names (\*-cells)
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
693 well-formed. It is allowed to include at any level, including ``child-binding``,
696 .. code-block:: YAML
701 child-binding:
707 a :ref:`property definition <dt-bindings-properties>` for which the included
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
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.