1Specifying GPIO information for devices
2=======================================
3
41) gpios property
5-----------------
6
7GPIO properties should be named "[<name>-]gpios", with <name> being the purpose
8of this GPIO for the device. While a non-existent <name> is considered valid
9for compatibility reasons (resolving to the "gpios" property), it is not allowed
10for new bindings. Also, GPIO properties named "[<name>-]gpio" are valid and old
11bindings use it, but are only supported for compatibility reasons and should not
12be used for newer bindings since it has been deprecated.
13
14GPIO properties can contain one or more GPIO phandles, but only in exceptional
15cases should they contain more than one. If your device uses several GPIOs with
16distinct functions, reference each of them under its own property, giving it a
17meaningful name. The only case where an array of GPIOs is accepted is when
18several GPIOs serve the same function (e.g. a parallel data line).
19
20The exact purpose of each gpios property must be documented in the device tree
21binding of the device.
22
23The following example could be used to describe GPIO pins used as device enable
24and bit-banged data signals:
25
26	gpio1: gpio1 {
27		gpio-controller;
28		#gpio-cells = <2>;
29	};
30	[...]
31
32	data-gpios = <&gpio1 12 0>,
33		     <&gpio1 13 0>,
34		     <&gpio1 14 0>,
35		     <&gpio1 15 0>;
36
37In the above example, &gpio1 uses 2 cells to specify a gpio. The first cell is
38a local offset to the GPIO line and the second cell represent consumer flags,
39such as if the consumer desire the line to be active low (inverted) or open
40drain. This is the recommended practice.
41
42The exact meaning of each specifier cell is controller specific, and must be
43documented in the device tree binding for the device, but it is strongly
44recommended to use the two-cell approach.
45
46Most controllers are specifying a generic flag bitfield in the last cell, so
47for these, use the macros defined in
48include/dt-bindings/gpio/gpio.h whenever possible:
49
50Example of a node using GPIOs:
51
52	node {
53		enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>;
54	};
55
56GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes
57GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
58
59Optional standard bitfield specifiers for the last cell:
60
61- Bit 0: 0 means active high, 1 means active low
62- Bit 1: 0 mean push-pull wiring, see:
63           https://en.wikipedia.org/wiki/Push-pull_output
64         1 means single-ended wiring, see:
65           https://en.wikipedia.org/wiki/Single-ended_triode
66- Bit 2: 0 means open-source, 1 means open drain, see:
67           https://en.wikipedia.org/wiki/Open_collector
68- Bit 3: 0 means the output should be maintained during sleep/low-power mode
69         1 means the output state can be lost during sleep/low-power mode
70- Bit 4: 0 means no pull-up resistor should be enabled
71         1 means a pull-up resistor should be enabled
72         This setting only applies to hardware with a simple on/off
73         control for pull-up configuration. If the hardware has more
74         elaborate pull-up configuration, it should be represented
75         using a pin control binding.
76- Bit 5: 0 means no pull-down resistor should be enabled
77         1 means a pull-down resistor should be enabled
78         This setting only applies to hardware with a simple on/off
79         control for pull-down configuration. If the hardware has more
80         elaborate pull-down configuration, it should be represented
81         using a pin control binding.
82
831.1) GPIO specifier best practices
84----------------------------------
85
86A gpio-specifier should contain a flag indicating the GPIO polarity; active-
87high or active-low. If it does, the following best practices should be
88followed:
89
90The gpio-specifier's polarity flag should represent the physical level at the
91GPIO controller that achieves (or represents, for inputs) a logically asserted
92value at the device. The exact definition of logically asserted should be
93defined by the binding for the device. If the board inverts the signal between
94the GPIO controller and the device, then the gpio-specifier will represent the
95opposite physical level than the signal at the device's pin.
96
97When the device's signal polarity is configurable, the binding for the
98device must either:
99
100a) Define a single static polarity for the signal, with the expectation that
101any software using that binding would statically program the device to use
102that signal polarity.
103
104The static choice of polarity may be either:
105
106a1) (Preferred) Dictated by a binding-specific DT property.
107
108or:
109
110a2) Defined statically by the DT binding itself.
111
112In particular, the polarity cannot be derived from the gpio-specifier, since
113that would prevent the DT from separately representing the two orthogonal
114concepts of configurable signal polarity in the device, and possible board-
115level signal inversion.
116
117or:
118
119b) Pick a single option for device signal polarity, and document this choice
120in the binding. The gpio-specifier should represent the polarity of the signal
121(at the GPIO controller) assuming that the device is configured for this
122particular signal polarity choice. If software chooses to program the device
123to generate or receive a signal of the opposite polarity, software will be
124responsible for correctly interpreting (inverting) the GPIO signal at the GPIO
125controller.
126
1272) gpio-controller nodes
128------------------------
129
130Every GPIO controller node must contain both an empty "gpio-controller"
131property, and a #gpio-cells integer property, which indicates the number of
132cells in a gpio-specifier.
133
134Some system-on-chips (SoCs) use the concept of GPIO banks. A GPIO bank is an
135instance of a hardware IP core on a silicon die, usually exposed to the
136programmer as a coherent range of I/O addresses. Usually each such bank is
137exposed in the device tree as an individual gpio-controller node, reflecting
138the fact that the hardware was synthesized by reusing the same IP block a
139few times over.
140
141Optionally, a GPIO controller may have a "ngpios" property. This property
142indicates the number of in-use slots of available slots for GPIOs. The
143typical example is something like this: the hardware register is 32 bits
144wide, but only 18 of the bits have a physical counterpart. The driver is
145generally written so that all 32 bits can be used, but the IP block is reused
146in a lot of designs, some using all 32 bits, some using 18 and some using
14712. In this case, setting "ngpios = <18>;" informs the driver that only the
148first 18 GPIOs, at local offset 0 .. 17, are in use.
149
150If these GPIOs do not happen to be the first N GPIOs at offset 0...N-1, an
151additional set of tuples is needed to specify which GPIOs are unusable, with
152the gpio-reserved-ranges binding. This property indicates the start and size
153of the GPIOs that can't be used.
154
155Optionally, a GPIO controller may have a "gpio-line-names" property. This is
156an array of strings defining the names of the GPIO lines going out of the
157GPIO controller. This name should be the most meaningful producer name
158for the system, such as a rail name indicating the usage. Package names
159such as pin name are discouraged: such lines have opaque names (since they
160are by definition generic purpose) and such names are usually not very
161helpful. For example "MMC-CD", "Red LED Vdd" and "ethernet reset" are
162reasonable line names as they describe what the line is used for. "GPIO0"
163is not a good name to give to a GPIO line. Placeholders are discouraged:
164rather use the "" (blank string) if the use of the GPIO line is undefined
165in your design. The names are assigned starting from line offset 0 from
166left to right from the passed array. An incomplete array (where the number
167of passed named are less than ngpios) will still be used up until the last
168provided valid line index.
169
170Example:
171
172gpio-controller@00000000 {
173	compatible = "foo";
174	reg = <0x00000000 0x1000>;
175	gpio-controller;
176	#gpio-cells = <2>;
177	ngpios = <18>;
178	gpio-reserved-ranges = <0 4>, <12 2>;
179	gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R",
180		"LED G", "LED B", "Col A", "Col B", "Col C", "Col D",
181		"Row A", "Row B", "Row C", "Row D", "NMI button",
182		"poweroff", "reset";
183}
184
185The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism
186providing automatic GPIO request and configuration as part of the
187gpio-controller's driver probe function.
188
189Each GPIO hog definition is represented as a child node of the GPIO controller.
190Required properties:
191- gpio-hog:   A property specifying that this child node represents a GPIO hog.
192- gpios:      Store the GPIO information (id, flags, ...) for each GPIO to
193	      affect. Shall contain an integer multiple of the number of cells
194	      specified in its parent node (GPIO controller node).
195Only one of the following properties scanned in the order shown below.
196This means that when multiple properties are present they will be searched
197in the order presented below and the first match is taken as the intended
198configuration.
199- input:      A property specifying to set the GPIO direction as input.
200- output-low  A property specifying to set the GPIO direction as output with
201	      the value low.
202- output-high A property specifying to set the GPIO direction as output with
203	      the value high.
204
205Optional properties:
206- line-name:  The GPIO label name. If not present the node name is used.
207
208Example of two SOC GPIO banks defined as gpio-controller nodes:
209
210	qe_pio_a: gpio-controller@1400 {
211		compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
212		reg = <0x1400 0x18>;
213		gpio-controller;
214		#gpio-cells = <2>;
215
216		line_b {
217			gpio-hog;
218			gpios = <6 0>;
219			output-low;
220			line-name = "foo-bar-gpio";
221		};
222	};
223
224	qe_pio_e: gpio-controller@1460 {
225		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
226		reg = <0x1460 0x18>;
227		gpio-controller;
228		#gpio-cells = <2>;
229	};
230
2312.1) gpio- and pin-controller interaction
232-----------------------------------------
233
234Some or all of the GPIOs provided by a GPIO controller may be routed to pins
235on the package via a pin controller. This allows muxing those pins between
236GPIO and other functions. It is a fairly common practice among silicon
237engineers.
238
2392.2) Ordinary (numerical) GPIO ranges
240-------------------------------------
241
242It is useful to represent which GPIOs correspond to which pins on which pin
243controllers. The gpio-ranges property described below represents this with
244a discrete set of ranges mapping pins from the pin controller local number space
245to pins in the GPIO controller local number space.
246
247The format is: <[pin controller phandle], [GPIO controller offset],
248                [pin controller offset], [number of pins]>;
249
250The GPIO controller offset pertains to the GPIO controller node containing the
251range definition.
252
253The pin controller node referenced by the phandle must conform to the bindings
254described in pinctrl/pinctrl-bindings.txt.
255
256Each offset runs from 0 to N. It is perfectly fine to pile any number of
257ranges with just one pin-to-GPIO line mapping if the ranges are concocted, but
258in practice these ranges are often lumped in discrete sets.
259
260Example:
261
262    gpio-ranges = <&foo 0 20 10>, <&bar 10 50 20>;
263
264This means:
265- pins 20..29 on pin controller "foo" is mapped to GPIO line 0..9 and
266- pins 50..69 on pin controller "bar" is mapped to GPIO line 10..29
267
268
269Verbose example:
270
271	qe_pio_e: gpio-controller@1460 {
272		#gpio-cells = <2>;
273		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
274		reg = <0x1460 0x18>;
275		gpio-controller;
276		gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
277	};
278
279Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
280pinctrl1's pins 20..29, and GPIOs 10..29 routed to pin controller pinctrl2's
281pins 50..69.
282
283
2842.3) GPIO ranges from named pin groups
285--------------------------------------
286
287It is also possible to use pin groups for gpio ranges when pin groups are the
288easiest and most convenient mapping.
289
290Both both <pinctrl-base> and <count> must set to 0 when using named pin groups
291names.
292
293The property gpio-ranges-group-names must contain exactly one string for each
294range.
295
296Elements of gpio-ranges-group-names must contain the name of a pin group
297defined in the respective pin controller. The number of pins/GPIO lines in the
298range is the number of pins in that pin group. The number of pins of that
299group is defined int the implementation and not in the device tree.
300
301If numerical and named pin groups are mixed, the string corresponding to a
302numerical pin range in gpio-ranges-group-names must be empty.
303
304Example:
305
306	gpio_pio_i: gpio-controller@14b0 {
307		#gpio-cells = <2>;
308		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
309		reg = <0x1480 0x18>;
310		gpio-controller;
311		gpio-ranges =			<&pinctrl1 0 20 10>,
312						<&pinctrl2 10 0 0>,
313						<&pinctrl1 15 0 10>,
314						<&pinctrl2 25 0 0>;
315		gpio-ranges-group-names =	"",
316						"foo",
317						"",
318						"bar";
319	};
320
321Here, three GPIO ranges are defined referring to two pin controllers.
322
323pinctrl1 GPIO ranges are defined using pin numbers whereas the GPIO ranges
324in pinctrl2 are defined using the pin groups named "foo" and "bar".
325
326Previous versions of this binding required all pin controller nodes that
327were referenced by any gpio-ranges property to contain a property named
328#gpio-range-cells with value <3>. This requirement is now deprecated.
329However, that property may still exist in older device trees for
330compatibility reasons, and would still be required even in new device
331trees that need to be compatible with older software.
332