Lines Matching +full:phandle +full:- +full:array +full:- +full:foo +full:- +full:cells
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:
56 # "Specifier" cell names for the 'foo' domain go here; example 'foo'
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
129 type: array
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
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
192 # Describes an optional property like 'keys = "foo", "bar";'
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:
231 type: array
232 default: [1, 2, 3] # Same as 'array-with-default = <1 2 3>'
234 string-with-default:
236 default: "foo"
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
262 about the ``phandle*`` type properties.
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
311 ``foo = "/path/to/some/node";``
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
343 foo:
347 If property ``foo`` is missing in a matching node, then the output will be as
348 if ``foo = <3>;`` had appeared in the DTS (except YAML data types are used for
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
486 compatible: foo
488 child-binding:
489 child-binding:
491 my-property:
497 .. code-block:: devicetree
500 compatible = "foo";
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)
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
630 compatible = "foo,pwm";
631 #pwm-cells = <2>;
636 #pwm-cells = <1>;
639 my-node {
643 The bindings for compatible ``"foo,pwm"`` and ``"bar,pwm"`` must give a name to
644 the cells that appear in a PWM specifier using ``pwm-cells:``, like this:
646 .. code-block:: YAML
648 # foo,pwm.yaml
649 compatible: "foo,pwm"
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,
664 This allows the cells in the specifiers to be accessed by name, e.g. using APIs
667 If the specifier is empty (e.g. ``#clock-cells = <0>``), then ``*-cells`` can
668 either be omitted (recommended) or set to an empty array. Note that an empty
669 array is specified as e.g. ``clock-cells: []`` in YAML.
671 .. _dt-bindings-include:
683 .. code-block:: YAML
685 include: foo.yaml
687 If any file named :file:`foo.yaml` is found (see
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
698 # foo.yaml will be merged with content at this level
699 include: foo.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
739 This includes the files :file:`foo.yaml` and :file:`bar.yaml`. (You can
740 write this list in a single line of YAML as ``include: [foo.yaml, 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.