]>
Commit | Line | Data |
---|---|---|
9f4cd020 SG |
1 | Specifying GPIO information for devices |
2 | ============================================ | |
3 | ||
4 | 1) gpios property | |
5 | ----------------- | |
6 | ||
7 | Nodes that makes use of GPIOs should specify them using one or more | |
8 | properties, each containing a 'gpio-list': | |
9 | ||
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 | ||
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 | |
19 | for new bindings. | |
20 | ||
21 | GPIO properties can contain one or more GPIO phandles, but only in exceptional | |
22 | cases should they contain more than one. If your device uses several GPIOs with | |
23 | distinct functions, reference each of them under its own property, giving it a | |
24 | meaningful name. The only case where an array of GPIOs is accepted is when | |
25 | several GPIOs serve the same function (e.g. a parallel data line). | |
26 | ||
27 | The exact purpose of each gpios property must be documented in the device tree | |
28 | binding of the device. | |
29 | ||
30 | The following example could be used to describe GPIO pins used as device enable | |
31 | and bit-banged data signals: | |
32 | ||
33 | gpio1: gpio1 { | |
34 | gpio-controller | |
35 | #gpio-cells = <2>; | |
36 | }; | |
37 | gpio2: gpio2 { | |
38 | gpio-controller | |
39 | #gpio-cells = <1>; | |
40 | }; | |
41 | [...] | |
42 | ||
43 | enable-gpios = <&gpio2 2>; | |
44 | data-gpios = <&gpio1 12 0>, | |
45 | <&gpio1 13 0>, | |
46 | <&gpio1 14 0>, | |
47 | <&gpio1 15 0>; | |
48 | ||
49 | Note that gpio-specifier length is controller dependent. In the | |
50 | above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2 | |
51 | only uses one. | |
52 | ||
53 | gpio-specifier may encode: bank, pin position inside the bank, | |
54 | whether pin is open-drain and whether pin is logically inverted. | |
55 | Exact meaning of each specifier cell is controller specific, and must | |
56 | be documented in the device tree binding for the device. Use the macros | |
57 | defined in include/dt-bindings/gpio/gpio.h whenever possible: | |
58 | ||
59 | Example of a node using GPIOs: | |
60 | ||
61 | node { | |
62 | enable-gpios = <&qe_pio_e 18 GPIO_ACTIVE_HIGH>; | |
63 | }; | |
64 | ||
65 | GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes | |
66 | GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller. | |
67 | ||
1bb257a9 PD |
68 | Optional standard bitfield specifiers for the last cell: |
69 | ||
70 | - Bit 0: 0 means active high, 1 means active low | |
71 | - Bit 1: 0 mean push-pull wiring, see: | |
72 | https://en.wikipedia.org/wiki/Push-pull_output | |
73 | 1 means single-ended wiring, see: | |
74 | https://en.wikipedia.org/wiki/Single-ended_triode | |
75 | - Bit 2: 0 means open-source, 1 means open drain, see: | |
76 | https://en.wikipedia.org/wiki/Open_collector | |
77 | - Bit 3: 0 means the output should be maintained during sleep/low-power mode | |
78 | 1 means the output state can be lost during sleep/low-power mode | |
79 | - Bit 4: 0 means no pull-up resistor should be enabled | |
80 | 1 means a pull-up resistor should be enabled | |
81 | This setting only applies to hardware with a simple on/off | |
82 | control for pull-up configuration. If the hardware has more | |
83 | elaborate pull-up configuration, it should be represented | |
84 | using a pin control binding. | |
85 | - Bit 5: 0 means no pull-down resistor should be enabled | |
86 | 1 means a pull-down resistor should be enabled | |
87 | This setting only applies to hardware with a simple on/off | |
88 | control for pull-down configuration. If the hardware has more | |
89 | elaborate pull-down configuration, it should be represented | |
90 | using a pin control binding. | |
91 | ||
9f4cd020 SG |
92 | 1.1) GPIO specifier best practices |
93 | ---------------------------------- | |
94 | ||
95 | A gpio-specifier should contain a flag indicating the GPIO polarity; active- | |
ba257793 MY |
96 | high or active-low. If it does, the following best practices should be |
97 | followed: | |
9f4cd020 SG |
98 | |
99 | The gpio-specifier's polarity flag should represent the physical level at the | |
100 | GPIO controller that achieves (or represents, for inputs) a logically asserted | |
101 | value at the device. The exact definition of logically asserted should be | |
102 | defined by the binding for the device. If the board inverts the signal between | |
103 | the GPIO controller and the device, then the gpio-specifier will represent the | |
104 | opposite physical level than the signal at the device's pin. | |
105 | ||
106 | When the device's signal polarity is configurable, the binding for the | |
107 | device must either: | |
108 | ||
109 | a) Define a single static polarity for the signal, with the expectation that | |
110 | any software using that binding would statically program the device to use | |
111 | that signal polarity. | |
112 | ||
113 | The static choice of polarity may be either: | |
114 | ||
115 | a1) (Preferred) Dictated by a binding-specific DT property. | |
116 | ||
117 | or: | |
118 | ||
119 | a2) Defined statically by the DT binding itself. | |
120 | ||
121 | In particular, the polarity cannot be derived from the gpio-specifier, since | |
122 | that would prevent the DT from separately representing the two orthogonal | |
123 | concepts of configurable signal polarity in the device, and possible board- | |
124 | level signal inversion. | |
125 | ||
126 | or: | |
127 | ||
128 | b) Pick a single option for device signal polarity, and document this choice | |
129 | in the binding. The gpio-specifier should represent the polarity of the signal | |
130 | (at the GPIO controller) assuming that the device is configured for this | |
131 | particular signal polarity choice. If software chooses to program the device | |
132 | to generate or receive a signal of the opposite polarity, software will be | |
133 | responsible for correctly interpreting (inverting) the GPIO signal at the GPIO | |
134 | controller. | |
135 | ||
136 | 2) gpio-controller nodes | |
137 | ------------------------ | |
138 | ||
139 | Every GPIO controller node must contain both an empty "gpio-controller" | |
140 | property, and a #gpio-cells integer property, which indicates the number of | |
141 | cells in a gpio-specifier. | |
142 | ||
143 | Example of two SOC GPIO banks defined as gpio-controller nodes: | |
144 | ||
145 | qe_pio_a: gpio-controller@1400 { | |
146 | compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; | |
147 | reg = <0x1400 0x18>; | |
148 | gpio-controller; | |
149 | #gpio-cells = <2>; | |
150 | }; | |
151 | ||
152 | qe_pio_e: gpio-controller@1460 { | |
153 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; | |
154 | reg = <0x1460 0x18>; | |
155 | gpio-controller; | |
156 | #gpio-cells = <2>; | |
157 | }; | |
158 | ||
159 | 2.1) gpio- and pin-controller interaction | |
160 | ----------------------------------------- | |
161 | ||
162 | Some or all of the GPIOs provided by a GPIO controller may be routed to pins | |
163 | on the package via a pin controller. This allows muxing those pins between | |
164 | GPIO and other functions. | |
165 | ||
166 | It is useful to represent which GPIOs correspond to which pins on which pin | |
167 | controllers. The gpio-ranges property described below represents this, and | |
168 | contains information structures as follows: | |
169 | ||
170 | gpio-range-list ::= <single-gpio-range> [gpio-range-list] | |
171 | single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range> | |
172 | numeric-gpio-range ::= | |
173 | <pinctrl-phandle> <gpio-base> <pinctrl-base> <count> | |
174 | named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>' | |
ba257793 | 175 | pinctrl-phandle : phandle to pin controller node |
9f4cd020 SG |
176 | gpio-base : Base GPIO ID in the GPIO controller |
177 | pinctrl-base : Base pinctrl pin ID in the pin controller | |
178 | count : The number of GPIOs/pins in this range | |
179 | ||
180 | The "pin controller node" mentioned above must conform to the bindings | |
181 | described in ../pinctrl/pinctrl-bindings.txt. | |
182 | ||
183 | In case named gpio ranges are used (ranges with both <pinctrl-base> and | |
184 | <count> set to 0), the property gpio-ranges-group-names contains one string | |
185 | for every single-gpio-range in gpio-ranges: | |
186 | gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list] | |
187 | gpiorange-name : Name of the pingroup associated to the GPIO range in | |
188 | the respective pin controller. | |
189 | ||
190 | Elements of gpiorange-names-list corresponding to numeric ranges contain | |
191 | the empty string. Elements of gpiorange-names-list corresponding to named | |
192 | ranges contain the name of a pin group defined in the respective pin | |
193 | controller. The number of pins/GPIOs in the range is the number of pins in | |
194 | that pin group. | |
195 | ||
196 | Previous versions of this binding required all pin controller nodes that | |
197 | were referenced by any gpio-ranges property to contain a property named | |
198 | #gpio-range-cells with value <3>. This requirement is now deprecated. | |
199 | However, that property may still exist in older device trees for | |
200 | compatibility reasons, and would still be required even in new device | |
201 | trees that need to be compatible with older software. | |
202 | ||
203 | Example 1: | |
204 | ||
205 | qe_pio_e: gpio-controller@1460 { | |
206 | #gpio-cells = <2>; | |
207 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; | |
208 | reg = <0x1460 0x18>; | |
209 | gpio-controller; | |
210 | gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>; | |
211 | }; | |
212 | ||
213 | Here, a single GPIO controller has GPIOs 0..9 routed to pin controller | |
214 | pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's | |
215 | pins 50..59. | |
216 | ||
217 | Example 2: | |
218 | ||
219 | gpio_pio_i: gpio-controller@14B0 { | |
220 | #gpio-cells = <2>; | |
221 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; | |
222 | reg = <0x1480 0x18>; | |
223 | gpio-controller; | |
224 | gpio-ranges = <&pinctrl1 0 20 10>, | |
225 | <&pinctrl2 10 0 0>, | |
226 | <&pinctrl1 15 0 10>, | |
227 | <&pinctrl2 25 0 0>; | |
228 | gpio-ranges-group-names = "", | |
229 | "foo", | |
230 | "", | |
231 | "bar"; | |
232 | }; | |
233 | ||
234 | Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO | |
235 | ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2 | |
236 | are named "foo" and "bar". | |
5fc7cf8c HS |
237 | |
238 | 3) GPIO hog definitions | |
239 | ----------------------- | |
240 | ||
241 | The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism | |
242 | providing automatic GPIO request and configuration as part of the | |
243 | gpio-controller's driver probe function. | |
244 | ||
245 | Each GPIO hog definition is represented as a child node of the GPIO controller. | |
246 | Required properties: | |
247 | - gpio-hog: A property specifying that this child node represents a GPIO hog. | |
248 | - gpios: Store the GPIO information (id, flags) for the GPIO to | |
249 | affect. | |
250 | ||
251 | ! Not yet support more than one gpio ! | |
252 | ||
253 | Only one of the following properties scanned in the order shown below. | |
254 | - input: A property specifying to set the GPIO direction as input. | |
255 | - output-low A property specifying to set the GPIO direction as output with | |
256 | the value low. | |
257 | - output-high A property specifying to set the GPIO direction as output with | |
258 | the value high. | |
259 | ||
260 | Optional properties: | |
261 | - line-name: The GPIO label name. If not present the node name is used. | |
262 | ||
263 | Example: | |
264 | ||
265 | tca6416@20 { | |
266 | compatible = "ti,tca6416"; | |
267 | reg = <0x20>; | |
268 | #gpio-cells = <2>; | |
269 | gpio-controller; | |
270 | ||
271 | env_reset { | |
272 | gpio-hog; | |
273 | input; | |
274 | gpios = <6 GPIO_ACTIVE_LOW>; | |
275 | }; | |
276 | boot_rescue { | |
277 | gpio-hog; | |
278 | input; | |
49b10cb4 | 279 | line-name = "foo-bar-gpio"; |
5fc7cf8c HS |
280 | gpios = <7 GPIO_ACTIVE_LOW>; |
281 | }; | |
282 | }; | |
283 | ||
284 | For the above Example you can than access the gpio in your boardcode | |
285 | with: | |
286 | ||
49b10cb4 HS |
287 | struct gpio_desc *desc; |
288 | int ret; | |
289 | ||
290 | ret = gpio_hog_lookup_name("boot_rescue", &desc); | |
291 | if (ret) | |
292 | return; | |
293 | if (dm_gpio_get_value(desc) == 1) | |
294 | printf("\nBooting into Rescue System\n"); | |
295 | else if (dm_gpio_get_value(desc) == 0) | |
296 | printf("\nBoot normal\n"); |