]>
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 | ||
68 | 1.1) GPIO specifier best practices | |
69 | ---------------------------------- | |
70 | ||
71 | A gpio-specifier should contain a flag indicating the GPIO polarity; active- | |
ba257793 MY |
72 | high or active-low. If it does, the following best practices should be |
73 | followed: | |
9f4cd020 SG |
74 | |
75 | The gpio-specifier's polarity flag should represent the physical level at the | |
76 | GPIO controller that achieves (or represents, for inputs) a logically asserted | |
77 | value at the device. The exact definition of logically asserted should be | |
78 | defined by the binding for the device. If the board inverts the signal between | |
79 | the GPIO controller and the device, then the gpio-specifier will represent the | |
80 | opposite physical level than the signal at the device's pin. | |
81 | ||
82 | When the device's signal polarity is configurable, the binding for the | |
83 | device must either: | |
84 | ||
85 | a) Define a single static polarity for the signal, with the expectation that | |
86 | any software using that binding would statically program the device to use | |
87 | that signal polarity. | |
88 | ||
89 | The static choice of polarity may be either: | |
90 | ||
91 | a1) (Preferred) Dictated by a binding-specific DT property. | |
92 | ||
93 | or: | |
94 | ||
95 | a2) Defined statically by the DT binding itself. | |
96 | ||
97 | In particular, the polarity cannot be derived from the gpio-specifier, since | |
98 | that would prevent the DT from separately representing the two orthogonal | |
99 | concepts of configurable signal polarity in the device, and possible board- | |
100 | level signal inversion. | |
101 | ||
102 | or: | |
103 | ||
104 | b) Pick a single option for device signal polarity, and document this choice | |
105 | in the binding. The gpio-specifier should represent the polarity of the signal | |
106 | (at the GPIO controller) assuming that the device is configured for this | |
107 | particular signal polarity choice. If software chooses to program the device | |
108 | to generate or receive a signal of the opposite polarity, software will be | |
109 | responsible for correctly interpreting (inverting) the GPIO signal at the GPIO | |
110 | controller. | |
111 | ||
112 | 2) gpio-controller nodes | |
113 | ------------------------ | |
114 | ||
115 | Every GPIO controller node must contain both an empty "gpio-controller" | |
116 | property, and a #gpio-cells integer property, which indicates the number of | |
117 | cells in a gpio-specifier. | |
118 | ||
119 | Example of two SOC GPIO banks defined as gpio-controller nodes: | |
120 | ||
121 | qe_pio_a: gpio-controller@1400 { | |
122 | compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank"; | |
123 | reg = <0x1400 0x18>; | |
124 | gpio-controller; | |
125 | #gpio-cells = <2>; | |
126 | }; | |
127 | ||
128 | qe_pio_e: gpio-controller@1460 { | |
129 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; | |
130 | reg = <0x1460 0x18>; | |
131 | gpio-controller; | |
132 | #gpio-cells = <2>; | |
133 | }; | |
134 | ||
135 | 2.1) gpio- and pin-controller interaction | |
136 | ----------------------------------------- | |
137 | ||
138 | Some or all of the GPIOs provided by a GPIO controller may be routed to pins | |
139 | on the package via a pin controller. This allows muxing those pins between | |
140 | GPIO and other functions. | |
141 | ||
142 | It is useful to represent which GPIOs correspond to which pins on which pin | |
143 | controllers. The gpio-ranges property described below represents this, and | |
144 | contains information structures as follows: | |
145 | ||
146 | gpio-range-list ::= <single-gpio-range> [gpio-range-list] | |
147 | single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range> | |
148 | numeric-gpio-range ::= | |
149 | <pinctrl-phandle> <gpio-base> <pinctrl-base> <count> | |
150 | named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>' | |
ba257793 | 151 | pinctrl-phandle : phandle to pin controller node |
9f4cd020 SG |
152 | gpio-base : Base GPIO ID in the GPIO controller |
153 | pinctrl-base : Base pinctrl pin ID in the pin controller | |
154 | count : The number of GPIOs/pins in this range | |
155 | ||
156 | The "pin controller node" mentioned above must conform to the bindings | |
157 | described in ../pinctrl/pinctrl-bindings.txt. | |
158 | ||
159 | In case named gpio ranges are used (ranges with both <pinctrl-base> and | |
160 | <count> set to 0), the property gpio-ranges-group-names contains one string | |
161 | for every single-gpio-range in gpio-ranges: | |
162 | gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list] | |
163 | gpiorange-name : Name of the pingroup associated to the GPIO range in | |
164 | the respective pin controller. | |
165 | ||
166 | Elements of gpiorange-names-list corresponding to numeric ranges contain | |
167 | the empty string. Elements of gpiorange-names-list corresponding to named | |
168 | ranges contain the name of a pin group defined in the respective pin | |
169 | controller. The number of pins/GPIOs in the range is the number of pins in | |
170 | that pin group. | |
171 | ||
172 | Previous versions of this binding required all pin controller nodes that | |
173 | were referenced by any gpio-ranges property to contain a property named | |
174 | #gpio-range-cells with value <3>. This requirement is now deprecated. | |
175 | However, that property may still exist in older device trees for | |
176 | compatibility reasons, and would still be required even in new device | |
177 | trees that need to be compatible with older software. | |
178 | ||
179 | Example 1: | |
180 | ||
181 | qe_pio_e: gpio-controller@1460 { | |
182 | #gpio-cells = <2>; | |
183 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; | |
184 | reg = <0x1460 0x18>; | |
185 | gpio-controller; | |
186 | gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>; | |
187 | }; | |
188 | ||
189 | Here, a single GPIO controller has GPIOs 0..9 routed to pin controller | |
190 | pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's | |
191 | pins 50..59. | |
192 | ||
193 | Example 2: | |
194 | ||
195 | gpio_pio_i: gpio-controller@14B0 { | |
196 | #gpio-cells = <2>; | |
197 | compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank"; | |
198 | reg = <0x1480 0x18>; | |
199 | gpio-controller; | |
200 | gpio-ranges = <&pinctrl1 0 20 10>, | |
201 | <&pinctrl2 10 0 0>, | |
202 | <&pinctrl1 15 0 10>, | |
203 | <&pinctrl2 25 0 0>; | |
204 | gpio-ranges-group-names = "", | |
205 | "foo", | |
206 | "", | |
207 | "bar"; | |
208 | }; | |
209 | ||
210 | Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO | |
211 | ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2 | |
212 | are named "foo" and "bar". |