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