Lines Matching +full:gpio +full:- +full:group
1 .. _dt-phandles:
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.
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
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
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
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
121 "groups", where each "group" is written inside of angle brackets (``< ... >``).
122 Each "group" starts with a phandle (``&foo``, ``&bar``, ``&baz``). The values
123 that follow the phandle in each "group" are called *specifiers*. There are
130 The phandle in each "group" is used to "point" to the hardware that controls
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
143 cases** that are handled in devicetree with phandle-array properties.
146 to a GPIO on your SoC. You will typically need to provide that GPIO's
147 information (GPIO controller and pin number) to the :ref:`device driver
149 metadata about the GPIO, like whether it is active low or high, what kind of
153 In the devicetree, there will be a node that represents the GPIO controller
154 that controls a group of pins. This reflects the way GPIO IP blocks are usually
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
167 "group" in its value. ``&gpioX`` is the phandle for the GPIO controller node
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.
281 Example specifier space: gpio
285 works: in the "gpio" space, specifiers almost always have two cells:
290 Therefore, almost all GPIO controller nodes you will see in practice will look
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