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