]>
Commit | Line | Data |
---|---|---|
7a865277 SW |
1 | == Introduction == |
2 | ||
3 | Hardware modules that control pin multiplexing or configuration parameters | |
4 | such as pull-up/down, tri-state, drive-strength etc are designated as pin | |
5 | controllers. Each pin controller must be represented as a node in device tree, | |
6 | just like any other hardware module. | |
7 | ||
8 | Hardware modules whose signals are affected by pin configuration are | |
9 | designated client devices. Again, each client device must be represented as a | |
10 | node in device tree, just like any other hardware module. | |
11 | ||
12 | For a client device to operate correctly, certain pin controllers must | |
13 | set up certain specific pin configurations. Some client devices need a | |
14 | single static pin configuration, e.g. set up during initialization. Others | |
15 | need to reconfigure pins at run-time, for example to tri-state pins when the | |
16 | device is inactive. Hence, each client device can define a set of named | |
17 | states. The number and names of those states is defined by the client device's | |
18 | own binding. | |
19 | ||
20 | The common pinctrl bindings defined in this file provide an infrastructure | |
21 | for client device device tree nodes to map those state names to the pin | |
22 | configuration used by those states. | |
23 | ||
24 | Note that pin controllers themselves may also be client devices of themselves. | |
25 | For example, a pin controller may set up its own "active" state when the | |
26 | driver loads. This would allow representing a board's static pin configuration | |
27 | in a single place, rather than splitting it across multiple client device | |
28 | nodes. The decision to do this or not somewhat rests with the author of | |
29 | individual board device tree files, and any requirements imposed by the | |
30 | bindings for the individual client devices in use by that board, i.e. whether | |
31 | they require certain specific named states for dynamic pin configuration. | |
32 | ||
33 | == Pinctrl client devices == | |
34 | ||
35 | For each client device individually, every pin state is assigned an integer | |
36 | ID. These numbers start at 0, and are contiguous. For each state ID, a unique | |
37 | property exists to define the pin configuration. Each state may also be | |
38 | assigned a name. When names are used, another property exists to map from | |
39 | those names to the integer IDs. | |
40 | ||
f5efed80 | 41 | Each client device's own binding determines the set of states that must be |
7a865277 SW |
42 | defined in its device tree node, and whether to define the set of state |
43 | IDs that must be provided, or whether to define the set of state names that | |
44 | must be provided. | |
45 | ||
46 | Required properties: | |
47 | pinctrl-0: List of phandles, each pointing at a pin configuration | |
48 | node. These referenced pin configuration nodes must be child | |
49 | nodes of the pin controller that they configure. Multiple | |
50 | entries may exist in this list so that multiple pin | |
51 | controllers may be configured, or so that a state may be built | |
52 | from multiple nodes for a single pin controller, each | |
53 | contributing part of the overall configuration. See the next | |
54 | section of this document for details of the format of these | |
55 | pin configuration nodes. | |
56 | ||
57 | In some cases, it may be useful to define a state, but for it | |
58 | to be empty. This may be required when a common IP block is | |
59 | used in an SoC either without a pin controller, or where the | |
60 | pin controller does not affect the HW module in question. If | |
61 | the binding for that IP block requires certain pin states to | |
62 | exist, they must still be defined, but may be left empty. | |
63 | ||
64 | Optional properties: | |
65 | pinctrl-1: List of phandles, each pointing at a pin configuration | |
66 | node within a pin controller. | |
67 | ... | |
68 | pinctrl-n: List of phandles, each pointing at a pin configuration | |
69 | node within a pin controller. | |
70 | pinctrl-names: The list of names to assign states. List entry 0 defines the | |
71 | name for integer state ID 0, list entry 1 for state ID 1, and | |
72 | so on. | |
73 | ||
74 | For example: | |
75 | ||
76 | /* For a client device requiring named states */ | |
77 | device { | |
78 | pinctrl-names = "active", "idle"; | |
79 | pinctrl-0 = <&state_0_node_a>; | |
80 | pinctrl-1 = <&state_1_node_a &state_1_node_b>; | |
81 | }; | |
82 | ||
83 | /* For the same device if using state IDs */ | |
84 | device { | |
85 | pinctrl-0 = <&state_0_node_a>; | |
86 | pinctrl-1 = <&state_1_node_a &state_1_node_b>; | |
87 | }; | |
88 | ||
89 | /* | |
90 | * For an IP block whose binding supports pin configuration, | |
91 | * but in use on an SoC that doesn't have any pin control hardware | |
92 | */ | |
93 | device { | |
94 | pinctrl-names = "active", "idle"; | |
95 | pinctrl-0 = <>; | |
96 | pinctrl-1 = <>; | |
97 | }; | |
98 | ||
99 | == Pin controller devices == | |
42124bc5 TL |
100 | Required properties: See the pin controller driver specific documentation |
101 | ||
102 | Optional properties: | |
103 | #pinctrl-cells: Number of pin control cells in addition to the index within the | |
104 | pin controller device instance | |
7a865277 SW |
105 | |
106 | Pin controller devices should contain the pin configuration nodes that client | |
107 | devices reference. | |
108 | ||
109 | For example: | |
110 | ||
111 | pincontroller { | |
112 | ... /* Standard DT properties for the device itself elided */ | |
113 | ||
114 | state_0_node_a { | |
115 | ... | |
116 | }; | |
117 | state_1_node_a { | |
118 | ... | |
119 | }; | |
120 | state_1_node_b { | |
121 | ... | |
122 | }; | |
123 | } | |
124 | ||
125 | The contents of each of those pin configuration child nodes is defined | |
126 | entirely by the binding for the individual pin controller device. There | |
42124bc5 TL |
127 | exists no common standard for this content. The pinctrl framework only |
128 | provides generic helper bindings that the pin controller driver can use. | |
7a865277 SW |
129 | |
130 | The pin configuration nodes need not be direct children of the pin controller | |
131 | device; they may be grandchildren, for example. Whether this is legal, and | |
132 | whether there is any interaction between the child and intermediate parent | |
133 | nodes, is again defined entirely by the binding for the individual pin | |
134 | controller device. | |
7db9af4b | 135 | |
90d09938 LW |
136 | == Generic pin multiplexing node content == |
137 | ||
138 | pin multiplexing nodes: | |
139 | ||
140 | function - the mux function to select | |
141 | groups - the list of groups to select with this function | |
cec65650 AB |
142 | (either this or "pins" must be specified) |
143 | pins - the list of pins to select with this function (either | |
144 | this or "groups" must be specified) | |
90d09938 LW |
145 | |
146 | Example: | |
147 | ||
148 | state_0_node_a { | |
5757bfe5 BS |
149 | uart0 { |
150 | function = "uart0"; | |
151 | groups = "u0rxtx", "u0rtscts"; | |
152 | }; | |
90d09938 LW |
153 | }; |
154 | state_1_node_a { | |
5757bfe5 BS |
155 | spi0 { |
156 | function = "spi0"; | |
157 | groups = "spi0pins"; | |
158 | }; | |
90d09938 | 159 | }; |
cec65650 AB |
160 | state_2_node_a { |
161 | function = "i2c0"; | |
162 | pins = "mfio29", "mfio30"; | |
163 | }; | |
90d09938 | 164 | |
8d5e7c5d JM |
165 | Optionally an alternative binding can be used if more suitable depending on the |
166 | pin controller hardware. For hardware where there is a large number of identical | |
42124bc5 TL |
167 | pin controller instances, naming each pin and function can easily become |
168 | unmaintainable. This is especially the case if the same controller is used for | |
169 | different pins and functions depending on the SoC revision and packaging. | |
170 | ||
171 | For cases like this, the pin controller driver may use pinctrl-pin-array helper | |
172 | binding with a hardware based index and a number of pin configuration values: | |
173 | ||
174 | pincontroller { | |
175 | ... /* Standard DT properties for the device itself elided */ | |
176 | #pinctrl-cells = <2>; | |
177 | ||
178 | state_0_node_a { | |
179 | pinctrl-pin-array = < | |
180 | 0 A_DELAY_PS(0) G_DELAY_PS(120) | |
181 | 4 A_DELAY_PS(0) G_DELAY_PS(360) | |
182 | ... | |
183 | >; | |
184 | }; | |
185 | ... | |
186 | }; | |
187 | ||
188 | Above #pinctrl-cells specifies the number of value cells in addition to the | |
189 | index of the registers. This is similar to the interrupts-extended binding with | |
190 | one exception. There is no need to specify the phandle for each entry as that | |
191 | is already known as the defined pins are always children of the pin controller | |
192 | node. Further having the phandle pointing to another pin controller would not | |
193 | currently work as the pinctrl framework uses named modes to group pins for each | |
194 | pin control device. | |
195 | ||
196 | The index for pinctrl-pin-array must relate to the hardware for the pinctrl | |
197 | registers, and must not be a virtual index of pin instances. The reason for | |
198 | this is to avoid mapping of the index in the dts files and the pin controller | |
199 | driver as it can change. | |
200 | ||
8d5e7c5d JM |
201 | For hardware where pin multiplexing configurations have to be specified for |
202 | each single pin the number of required sub-nodes containing "pin" and | |
203 | "function" properties can quickly escalate and become hard to write and | |
204 | maintain. | |
205 | ||
206 | For cases like this, the pin controller driver may use the pinmux helper | |
207 | property, where the pin identifier is packed with mux configuration settings | |
208 | in a single integer. | |
209 | ||
210 | The pinmux property accepts an array of integers, each of them describing | |
211 | a single pin multiplexing configuration. | |
212 | ||
213 | pincontroller { | |
214 | state_0_node_a { | |
215 | pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ...; | |
216 | }; | |
217 | }; | |
218 | ||
219 | Each individual pin controller driver bindings documentation shall specify | |
220 | how those values (pin IDs and pin multiplexing configuration) are defined and | |
221 | assembled together. | |
222 | ||
bcd0c8c2 | 223 | == Generic pin configuration node content == |
7db9af4b | 224 | |
bcd0c8c2 SW |
225 | Many data items that are represented in a pin configuration node are common |
226 | and generic. Pin control bindings should use the properties defined below | |
227 | where they are applicable; not all of these properties are relevant or useful | |
228 | for all hardware or binding structures. Each individual binding document | |
229 | should state which of these generic properties, if any, are used, and the | |
230 | structure of the DT nodes that contain these properties. | |
7db9af4b | 231 | |
bcd0c8c2 | 232 | Supported generic properties are: |
7db9af4b | 233 | |
87311d04 | 234 | pins - the list of pins that properties in the node |
8d5e7c5d | 235 | apply to (either this, "group" or "pinmux" has to be |
2cdef8f4 LW |
236 | specified) |
237 | group - the group to apply the properties to, if the driver | |
238 | supports configuration of whole groups rather than | |
8d5e7c5d JM |
239 | individual pins (either this, "pins" or "pinmux" has |
240 | to be specified) | |
241 | pinmux - the list of numeric pin ids and their mux settings | |
242 | that properties in the node apply to (either this, | |
243 | "pins" or "groups" have to be specified) | |
7db9af4b HS |
244 | bias-disable - disable any pin bias |
245 | bias-high-impedance - high impedance mode ("third-state", "floating") | |
246 | bias-bus-hold - latch weakly | |
247 | bias-pull-up - pull up the pin | |
248 | bias-pull-down - pull down the pin | |
249 | bias-pull-pin-default - use pin-default pull state | |
250 | drive-push-pull - drive actively high and low | |
251 | drive-open-drain - drive with open drain | |
252 | drive-open-source - drive with open source | |
253 | drive-strength - sink or source at most X mA | |
8ba3f4d0 SY |
254 | input-enable - enable input on pin (no effect on output) |
255 | input-disable - disable input on pin (no effect on output) | |
7db9af4b HS |
256 | input-schmitt-enable - enable schmitt-trigger mode |
257 | input-schmitt-disable - disable schmitt-trigger mode | |
7db9af4b | 258 | input-debounce - debounce mode with debound time X |
ca6c5518 | 259 | power-source - select between different power supplies |
9ee1f7d2 HS |
260 | low-power-enable - enable low power mode |
261 | low-power-disable - disable low power mode | |
7db9af4b HS |
262 | output-low - set the pin to output mode with low level |
263 | output-high - set the pin to output mode with high level | |
8ba3f4d0 | 264 | slew-rate - set the slew rate |
7db9af4b | 265 | |
90d09938 LW |
266 | For example: |
267 | ||
268 | state_0_node_a { | |
5757bfe5 BS |
269 | cts_rxd { |
270 | pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */ | |
271 | bias-pull-up; | |
272 | }; | |
90d09938 LW |
273 | }; |
274 | state_1_node_a { | |
5757bfe5 BS |
275 | rts_txd { |
276 | pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */ | |
277 | output-high; | |
278 | }; | |
90d09938 | 279 | }; |
2cdef8f4 | 280 | state_2_node_a { |
5757bfe5 BS |
281 | foo { |
282 | group = "foo-group"; | |
283 | bias-pull-up; | |
284 | }; | |
2cdef8f4 | 285 | }; |
8d5e7c5d JM |
286 | state_3_node_a { |
287 | mux { | |
288 | pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>; | |
289 | input-enable; | |
290 | }; | |
291 | }; | |
90d09938 | 292 | |
bcd0c8c2 SW |
293 | Some of the generic properties take arguments. For those that do, the |
294 | arguments are described below. | |
9ee1f7d2 | 295 | |
87311d04 SW |
296 | - pins takes a list of pin names or IDs as a required argument. The specific |
297 | binding for the hardware defines: | |
298 | - Whether the entries are integers or strings, and their meaning. | |
299 | ||
8d5e7c5d JM |
300 | - pinmux takes a list of pin IDs and mux settings as required argument. The |
301 | specific bindings for the hardware defines: | |
302 | - How pin IDs and mux settings are defined and assembled together in a single | |
303 | integer. | |
304 | ||
70637a6d HS |
305 | - bias-pull-up, -down and -pin-default take as optional argument on hardware |
306 | supporting it the pull strength in Ohm. bias-disable will disable the pull. | |
9ee1f7d2 HS |
307 | |
308 | - drive-strength takes as argument the target strength in mA. | |
309 | ||
256aeb64 HS |
310 | - input-debounce takes the debounce time in usec as argument |
311 | or 0 to disable debouncing | |
9ee1f7d2 | 312 | |
7db9af4b | 313 | More in-depth documentation on these parameters can be found in |
ee76a9ab | 314 | <include/linux/pinctrl/pinconf-generic.h> |