Lines Matching +full:use +full:- +full:case
1 .. _dt-phandles:
7 C. You can use phandles to refer to nodes in devicetree similarly to the way
8 you can use pointers to refer to structures in C.
19 .. code-block:: DTS
22 lbl_a: node-1 {};
23 lbl_b: lbl_c: node-2 {};
28 - ``/node-1`` as ``&lbl_a``
29 - ``/node-2`` as either ``&lbl_b`` or ``&lbl_c``
40 :ref:`dt-bindings-properties` in the devicetree bindings documentation.
42 Here are the main ways you will use phandles.
47 You can use phandles to refer to ``node-b`` from ``node-a``, where ``node-b``
48 is related to ``node-a`` in some way.
50 One common example is when ``node-a`` represents some hardware that
51 generates an interrupt, and ``node-b`` represents the interrupt
52 controller that receives the asserted interrupt. In this case, you could
55 .. code-block:: DTS
57 node_b: node-b {
58 interrupt-controller;
61 node-a {
62 interrupt-parent = <&node_b>;
65 This uses the standard ``interrupt-parent`` property defined in the
73 You can use phandles to make an array of references to other nodes.
75 One common example occurs in :ref:`pin control <pinctrl-guide>`. Pin control
76 properties like ``pinctrl-0``, ``pinctrl-1`` etc. may contain multiple
81 .. code-block:: DTS
83 pinctrl-0 = <&quadspi_clk_pe10 &quadspi_ncs_pe11
89 Zero or more nodes with metadata: phandle-array type
92 You can use phandles to refer to and configure one or more resources that are
95 This is the most complex case. There are examples and more details in the
98 These properties have type ``phandle-array``.
100 .. _dt-phandle-arrays:
102 phandle-array properties
111 Usually, properties with this type are written like ``phandle-array-prop`` in
114 .. code-block:: dts
117 phandle-array-prop = <&foo 1 2>, <&bar 3>, <&baz 4 5>;
120 That is, the property's value is written as a comma-separated sequence of
135 document more rules about how to use phandle-array properties in practice.
137 Example phandle-arrays: GPIOs
140 Perhaps the most common use case for phandle-array properties is specifying one
142 reason, we'll focus on that use case here. However, there are **many other use
143 cases** that are handled in devicetree with phandle-array properties.
156 that represents a GPIO pin, and you can't use a single phandle to represent it.
158 Instead, you would use a phandle-array property, like this:
160 .. code-block::
162 my-external-ic {
163 irq-gpios = <&gpioX pin flags>;
166 In this example, ``irq-gpios`` is a phandle-array property with just one
170 GPIO_PULL_UP)``); see :zephyr_file:`include/zephyr/dt-bindings/gpio/gpio.h` for
173 The device driver handling the ``my-external-ic`` node can then use the
174 ``irq-gpios`` property's value to set up interrupt handling for the chip as it
180 .. code-block::
182 my-other-external-ic {
183 handshake-gpios = <&gpioX pinX flagsX>, <&gpioY pinY flagsY>;
188 - ``pinX`` on the GPIO controller with phandle ``&gpioX``, flags ``flagsX``
189 - ``pinY`` on ``&gpioY``, flags ``flagsY``
196 .. _dt-specifier-spaces:
202 use them in phandle-array properties.
212 As described above, a phandle-array property is a sequence of "groups" of
215 .. code-block:: dts
218 phandle-array-prop = <&foo 1 2>, <&bar 3>;
227 Every phandle-array property has an associated *specifier space*. This sounds
234 name, using the ``#SPACE_NAME-cells`` property. For example, let's assume that
235 ``phandle-array-prop``\ 's specifier space is named ``baz``. Then we would need
236 the ``foo`` and ``bar`` nodes to have the following ``#baz-cells`` properties:
238 .. code-block:: DTS
241 #baz-cells = <2>;
245 #baz-cells = <1>;
248 Without the ``#baz-cells`` property, the devicetree tooling would not be able
249 to validate the number of cells in each specifier in ``phandle-array-prop``.
258 .. code-block:: DTS
261 #baz-cells = <2>;
262 #bob-cells = <1>;
266 With that, if ``phandle-array-prop-2`` has specifier space ``bob``, we could
269 .. code-block:: DTS
272 phandle-array-prop = <&foo 1 2>, <&bar 3>;
273 phandle-array-prop-2 = <&foo 4>;
279 case) using different ``#SPACE_NAME-cells`` properties.
293 .. code-block:: DTS
295 gpioX: gpio-controller@deadbeef {
296 gpio-controller;
297 #gpio-cells = <2>;
305 - each phandle-array property has an associated specifier space
306 - specifier spaces are identified by name
307 - devicetree nodes use ``#SPECIFIER_NAME-cells`` properties to
310 In this section, we explain how phandle-array properties get their specifier
316 In general, a ``phandle-array`` property named ``foos`` implicitly has
319 .. code-block:: YAML
323 type: phandle-array
325 type: phandle-array
330 Special case: GPIO
333 ``*-gpios`` properties are special-cased so that e.g. ``foo-gpios`` resolves to
334 ``#gpio-cells`` rather than ``#foo-gpio-cells``.
339 You can manually specify the specifier space for any ``phandle-array``
340 property. See :ref:`dt-bindings-specifier-space`.
346 writing bindings. For details on how to do this, see :ref:`dt-bindings-cells`.
351 - :c:macro:`DT_PHA_BY_IDX`
352 - :c:macro:`DT_PHA_BY_NAME`
354 This feature and these macros are used internally by numerous hardware-specific
357 - :c:macro:`DT_GPIO_PIN_BY_IDX`
358 - :c:macro:`DT_PWMS_CHANNEL_BY_IDX`
359 - :c:macro:`DT_DMAS_CELL_BY_NAME`
360 - :c:macro:`DT_IO_CHANNELS_INPUT_BY_IDX`
361 - :c:macro:`DT_CLOCKS_CELL_BY_NAME`
366 - :ref:`dt-writing-property-values`: how to write phandles in devicetree
369 - :ref:`dt-bindings-properties`: how to write bindings for properties with
370 phandle types (``phandle``, ``phandles``, ``phandle-array``)
372 - :ref:`dt-bindings-specifier-space`: how to manually specify a phandle-array