Commit | Line | Data |
---|---|---|
0a971810 | 1 | =============================== |
2744e8af | 2 | PINCTRL (PIN CONTROL) subsystem |
0a971810 MCC |
3 | =============================== |
4 | ||
2744e8af LW |
5 | This document outlines the pin control subsystem in Linux |
6 | ||
7 | This subsystem deals with: | |
8 | ||
9 | - Enumerating and naming controllable pins | |
10 | ||
11 | - Multiplexing of pins, pads, fingers (etc) see below for details | |
12 | ||
ae6b4d85 LW |
13 | - Configuration of pins, pads, fingers (etc), such as software-controlled |
14 | biasing and driving mode specific pins, such as pull-up/down, open drain, | |
15 | load capacitance etc. | |
2744e8af LW |
16 | |
17 | Top-level interface | |
18 | =================== | |
19 | ||
20 | Definition of PIN CONTROLLER: | |
21 | ||
22 | - A pin controller is a piece of hardware, usually a set of registers, that | |
23 | can control PINs. It may be able to multiplex, bias, set load capacitance, | |
4dfb0bd7 | 24 | set drive strength, etc. for individual pins or groups of pins. |
2744e8af LW |
25 | |
26 | Definition of PIN: | |
27 | ||
28 | - PINS are equal to pads, fingers, balls or whatever packaging input or | |
29 | output line you want to control and these are denoted by unsigned integers | |
30 | in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so | |
31 | there may be several such number spaces in a system. This pin space may | |
32 | be sparse - i.e. there may be gaps in the space with numbers where no | |
33 | pin exists. | |
34 | ||
336cdba0 | 35 | When a PIN CONTROLLER is instantiated, it will register a descriptor to the |
2744e8af LW |
36 | pin control framework, and this descriptor contains an array of pin descriptors |
37 | describing the pins handled by this specific pin controller. | |
38 | ||
0a971810 | 39 | Here is an example of a PGA (Pin Grid Array) chip seen from underneath:: |
2744e8af LW |
40 | |
41 | A B C D E F G H | |
42 | ||
43 | 8 o o o o o o o o | |
44 | ||
45 | 7 o o o o o o o o | |
46 | ||
47 | 6 o o o o o o o o | |
48 | ||
49 | 5 o o o o o o o o | |
50 | ||
51 | 4 o o o o o o o o | |
52 | ||
53 | 3 o o o o o o o o | |
54 | ||
55 | 2 o o o o o o o o | |
56 | ||
57 | 1 o o o o o o o o | |
58 | ||
59 | To register a pin controller and name all the pins on this package we can do | |
0a971810 | 60 | this in our driver:: |
2744e8af | 61 | |
0a971810 | 62 | #include <linux/pinctrl/pinctrl.h> |
2744e8af | 63 | |
0a971810 MCC |
64 | const struct pinctrl_pin_desc foo_pins[] = { |
65 | PINCTRL_PIN(0, "A8"), | |
66 | PINCTRL_PIN(1, "B8"), | |
67 | PINCTRL_PIN(2, "C8"), | |
68 | ... | |
69 | PINCTRL_PIN(61, "F1"), | |
70 | PINCTRL_PIN(62, "G1"), | |
71 | PINCTRL_PIN(63, "H1"), | |
72 | }; | |
73 | ||
74 | static struct pinctrl_desc foo_desc = { | |
75 | .name = "foo", | |
76 | .pins = foo_pins, | |
77 | .npins = ARRAY_SIZE(foo_pins), | |
78 | .owner = THIS_MODULE, | |
79 | }; | |
80 | ||
81 | int __init foo_probe(void) | |
82 | { | |
83 | int error; | |
61187142 | 84 | |
0a971810 | 85 | struct pinctrl_dev *pctl; |
2744e8af | 86 | |
0a971810 MCC |
87 | error = pinctrl_register_and_init(&foo_desc, <PARENT>, |
88 | NULL, &pctl); | |
89 | if (error) | |
90 | return error; | |
61187142 | 91 | |
0a971810 MCC |
92 | return pinctrl_enable(pctl); |
93 | } | |
2744e8af | 94 | |
ae6b4d85 LW |
95 | To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and |
96 | selected drivers, you need to select them from your machine's Kconfig entry, | |
97 | since these are so tightly integrated with the machines they are used on. | |
98 | See for example arch/arm/mach-u300/Kconfig for an example. | |
99 | ||
4dfb0bd7 | 100 | Pins usually have fancier names than this. You can find these in the datasheet |
2744e8af LW |
101 | for your chip. Notice that the core pinctrl.h file provides a fancy macro |
102 | called PINCTRL_PIN() to create the struct entries. As you can see I enumerated | |
336cdba0 LW |
103 | the pins from 0 in the upper left corner to 63 in the lower right corner. |
104 | This enumeration was arbitrarily chosen, in practice you need to think | |
2744e8af LW |
105 | through your numbering system so that it matches the layout of registers |
106 | and such things in your driver, or the code may become complicated. You must | |
107 | also consider matching of offsets to the GPIO ranges that may be handled by | |
108 | the pin controller. | |
109 | ||
110 | For a padring with 467 pads, as opposed to actual pins, I used an enumeration | |
111 | like this, walking around the edge of the chip, which seems to be industry | |
0a971810 | 112 | standard too (all these pads had names, too):: |
2744e8af LW |
113 | |
114 | ||
115 | 0 ..... 104 | |
116 | 466 105 | |
117 | . . | |
118 | . . | |
119 | 358 224 | |
120 | 357 .... 225 | |
121 | ||
122 | ||
123 | Pin groups | |
124 | ========== | |
125 | ||
126 | Many controllers need to deal with groups of pins, so the pin controller | |
127 | subsystem has a mechanism for enumerating groups of pins and retrieving the | |
128 | actual enumerated pins that are part of a certain group. | |
129 | ||
130 | For example, say that we have a group of pins dealing with an SPI interface | |
131 | on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins | |
132 | on { 24, 25 }. | |
133 | ||
134 | These two groups are presented to the pin control subsystem by implementing | |
0a971810 MCC |
135 | some generic pinctrl_ops like this:: |
136 | ||
137 | #include <linux/pinctrl/pinctrl.h> | |
138 | ||
139 | struct foo_group { | |
140 | const char *name; | |
141 | const unsigned int *pins; | |
142 | const unsigned num_pins; | |
143 | }; | |
144 | ||
145 | static const unsigned int spi0_pins[] = { 0, 8, 16, 24 }; | |
146 | static const unsigned int i2c0_pins[] = { 24, 25 }; | |
147 | ||
148 | static const struct foo_group foo_groups[] = { | |
149 | { | |
150 | .name = "spi0_grp", | |
151 | .pins = spi0_pins, | |
152 | .num_pins = ARRAY_SIZE(spi0_pins), | |
153 | }, | |
154 | { | |
155 | .name = "i2c0_grp", | |
156 | .pins = i2c0_pins, | |
157 | .num_pins = ARRAY_SIZE(i2c0_pins), | |
158 | }, | |
159 | }; | |
160 | ||
161 | ||
162 | static int foo_get_groups_count(struct pinctrl_dev *pctldev) | |
2744e8af | 163 | { |
0a971810 MCC |
164 | return ARRAY_SIZE(foo_groups); |
165 | } | |
2744e8af | 166 | |
0a971810 MCC |
167 | static const char *foo_get_group_name(struct pinctrl_dev *pctldev, |
168 | unsigned selector) | |
169 | { | |
170 | return foo_groups[selector].name; | |
171 | } | |
2744e8af | 172 | |
0a971810 MCC |
173 | static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, |
174 | const unsigned **pins, | |
175 | unsigned *num_pins) | |
176 | { | |
177 | *pins = (unsigned *) foo_groups[selector].pins; | |
178 | *num_pins = foo_groups[selector].num_pins; | |
179 | return 0; | |
180 | } | |
2744e8af | 181 | |
0a971810 MCC |
182 | static struct pinctrl_ops foo_pctrl_ops = { |
183 | .get_groups_count = foo_get_groups_count, | |
184 | .get_group_name = foo_get_group_name, | |
185 | .get_group_pins = foo_get_group_pins, | |
186 | }; | |
2744e8af LW |
187 | |
188 | ||
0a971810 MCC |
189 | static struct pinctrl_desc foo_desc = { |
190 | ... | |
191 | .pctlops = &foo_pctrl_ops, | |
192 | }; | |
2744e8af | 193 | |
d1e90e9e | 194 | The pin control subsystem will call the .get_groups_count() function to |
4dfb0bd7 | 195 | determine the total number of legal selectors, then it will call the other functions |
d1e90e9e VK |
196 | to retrieve the name and pins of the group. Maintaining the data structure of |
197 | the groups is up to the driver, this is just a simple example - in practice you | |
198 | may need more entries in your group structure, for example specific register | |
199 | ranges associated with each group and so on. | |
2744e8af LW |
200 | |
201 | ||
ae6b4d85 LW |
202 | Pin configuration |
203 | ================= | |
204 | ||
4dfb0bd7 | 205 | Pins can sometimes be software-configured in various ways, mostly related |
ae6b4d85 LW |
206 | to their electronic properties when used as inputs or outputs. For example you |
207 | may be able to make an output pin high impedance, or "tristate" meaning it is | |
208 | effectively disconnected. You may be able to connect an input pin to VDD or GND | |
209 | using a certain resistor value - pull up and pull down - so that the pin has a | |
210 | stable value when nothing is driving the rail it is connected to, or when it's | |
211 | unconnected. | |
212 | ||
ad42fc6c LW |
213 | Pin configuration can be programmed by adding configuration entries into the |
214 | mapping table; see section "Board/machine configuration" below. | |
ae6b4d85 | 215 | |
1e2082b5 SW |
216 | The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP |
217 | above, is entirely defined by the pin controller driver. | |
218 | ||
219 | The pin configuration driver implements callbacks for changing pin | |
0a971810 | 220 | configuration in the pin controller ops like this:: |
ae6b4d85 | 221 | |
0a971810 MCC |
222 | #include <linux/pinctrl/pinctrl.h> |
223 | #include <linux/pinctrl/pinconf.h> | |
224 | #include "platform_x_pindefs.h" | |
ae6b4d85 | 225 | |
0a971810 MCC |
226 | static int foo_pin_config_get(struct pinctrl_dev *pctldev, |
227 | unsigned offset, | |
228 | unsigned long *config) | |
229 | { | |
230 | struct my_conftype conf; | |
ae6b4d85 | 231 | |
0a971810 | 232 | ... Find setting for pin @ offset ... |
ae6b4d85 | 233 | |
0a971810 MCC |
234 | *config = (unsigned long) conf; |
235 | } | |
ae6b4d85 | 236 | |
0a971810 MCC |
237 | static int foo_pin_config_set(struct pinctrl_dev *pctldev, |
238 | unsigned offset, | |
239 | unsigned long config) | |
240 | { | |
241 | struct my_conftype *conf = (struct my_conftype *) config; | |
ae6b4d85 | 242 | |
0a971810 MCC |
243 | switch (conf) { |
244 | case PLATFORM_X_PULL_UP: | |
245 | ... | |
246 | } | |
ae6b4d85 LW |
247 | } |
248 | } | |
ae6b4d85 | 249 | |
0a971810 MCC |
250 | static int foo_pin_config_group_get (struct pinctrl_dev *pctldev, |
251 | unsigned selector, | |
252 | unsigned long *config) | |
253 | { | |
254 | ... | |
255 | } | |
ae6b4d85 | 256 | |
0a971810 MCC |
257 | static int foo_pin_config_group_set (struct pinctrl_dev *pctldev, |
258 | unsigned selector, | |
259 | unsigned long config) | |
260 | { | |
261 | ... | |
262 | } | |
ae6b4d85 | 263 | |
0a971810 MCC |
264 | static struct pinconf_ops foo_pconf_ops = { |
265 | .pin_config_get = foo_pin_config_get, | |
266 | .pin_config_set = foo_pin_config_set, | |
267 | .pin_config_group_get = foo_pin_config_group_get, | |
268 | .pin_config_group_set = foo_pin_config_group_set, | |
269 | }; | |
ae6b4d85 | 270 | |
0a971810 MCC |
271 | /* Pin config operations are handled by some pin controller */ |
272 | static struct pinctrl_desc foo_desc = { | |
273 | ... | |
274 | .confops = &foo_pconf_ops, | |
275 | }; | |
ae6b4d85 LW |
276 | |
277 | Since some controllers have special logic for handling entire groups of pins | |
278 | they can exploit the special whole-group pin control function. The | |
279 | pin_config_group_set() callback is allowed to return the error code -EAGAIN, | |
280 | for groups it does not want to handle, or if it just wants to do some | |
281 | group-level handling and then fall through to iterate over all pins, in which | |
282 | case each individual pin will be treated by separate pin_config_set() calls as | |
283 | well. | |
284 | ||
285 | ||
2744e8af LW |
286 | Interaction with the GPIO subsystem |
287 | =================================== | |
288 | ||
289 | The GPIO drivers may want to perform operations of various types on the same | |
290 | physical pins that are also registered as pin controller pins. | |
291 | ||
c31a00cd LW |
292 | First and foremost, the two subsystems can be used as completely orthogonal, |
293 | see the section named "pin control requests from drivers" and | |
294 | "drivers needing both pin control and GPIOs" below for details. But in some | |
295 | situations a cross-subsystem mapping between pins and GPIOs is needed. | |
296 | ||
73f8fed0 AJ |
297 | Since the pin controller subsystem has its pinspace local to the pin controller |
298 | we need a mapping so that the pin control subsystem can figure out which pin | |
299 | controller handles control of a certain GPIO pin. Since a single pin controller | |
300 | may be muxing several GPIO ranges (typically SoCs that have one set of pins, | |
301 | but internally several GPIO silicon blocks, each modelled as a struct | |
302 | gpio_chip) any number of GPIO ranges can be added to a pin controller instance | |
0a971810 MCC |
303 | like this:: |
304 | ||
305 | struct gpio_chip chip_a; | |
306 | struct gpio_chip chip_b; | |
307 | ||
308 | static struct pinctrl_gpio_range gpio_range_a = { | |
309 | .name = "chip a", | |
310 | .id = 0, | |
311 | .base = 32, | |
312 | .pin_base = 32, | |
313 | .npins = 16, | |
314 | .gc = &chip_a; | |
315 | }; | |
316 | ||
317 | static struct pinctrl_gpio_range gpio_range_b = { | |
318 | .name = "chip b", | |
319 | .id = 0, | |
320 | .base = 48, | |
321 | .pin_base = 64, | |
322 | .npins = 8, | |
323 | .gc = &chip_b; | |
324 | }; | |
325 | ||
326 | { | |
327 | struct pinctrl_dev *pctl; | |
328 | ... | |
329 | pinctrl_add_gpio_range(pctl, &gpio_range_a); | |
330 | pinctrl_add_gpio_range(pctl, &gpio_range_b); | |
331 | } | |
2744e8af LW |
332 | |
333 | So this complex system has one pin controller handling two different | |
3c739ad0 CP |
334 | GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and |
335 | "chip b" have different .pin_base, which means a start pin number of the | |
336 | GPIO range. | |
337 | ||
338 | The GPIO range of "chip a" starts from the GPIO base of 32 and actual | |
339 | pin range also starts from 32. However "chip b" has different starting | |
340 | offset for the GPIO range and pin range. The GPIO range of "chip b" starts | |
341 | from GPIO number 48, while the pin range of "chip b" starts from 64. | |
2744e8af | 342 | |
3c739ad0 CP |
343 | We can convert a gpio number to actual pin number using this "pin_base". |
344 | They are mapped in the global GPIO pin space at: | |
345 | ||
346 | chip a: | |
347 | - GPIO range : [32 .. 47] | |
348 | - pin range : [32 .. 47] | |
349 | chip b: | |
350 | - GPIO range : [48 .. 55] | |
351 | - pin range : [64 .. 71] | |
2744e8af | 352 | |
30cf821e LW |
353 | The above examples assume the mapping between the GPIOs and pins is |
354 | linear. If the mapping is sparse or haphazard, an array of arbitrary pin | |
0a971810 | 355 | numbers can be encoded in the range like this:: |
30cf821e | 356 | |
0a971810 | 357 | static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 }; |
30cf821e | 358 | |
0a971810 MCC |
359 | static struct pinctrl_gpio_range gpio_range = { |
360 | .name = "chip", | |
361 | .id = 0, | |
362 | .base = 32, | |
363 | .pins = &range_pins, | |
364 | .npins = ARRAY_SIZE(range_pins), | |
365 | .gc = &chip; | |
366 | }; | |
30cf821e | 367 | |
fe61052a CR |
368 | In this case the pin_base property will be ignored. If the name of a pin |
369 | group is known, the pins and npins elements of the above structure can be | |
370 | initialised using the function pinctrl_get_group_pins(), e.g. for pin | |
0a971810 | 371 | group "foo":: |
fe61052a | 372 | |
0a971810 MCC |
373 | pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, |
374 | &gpio_range.npins); | |
30cf821e | 375 | |
2744e8af | 376 | When GPIO-specific functions in the pin control subsystem are called, these |
336cdba0 | 377 | ranges will be used to look up the appropriate pin controller by inspecting |
2744e8af LW |
378 | and matching the pin to the pin ranges across all controllers. When a |
379 | pin controller handling the matching range is found, GPIO-specific functions | |
380 | will be called on that specific pin controller. | |
381 | ||
382 | For all functionalities dealing with pin biasing, pin muxing etc, the pin | |
30cf821e | 383 | controller subsystem will look up the corresponding pin number from the passed |
4dfb0bd7 | 384 | in gpio number, and use the range's internals to retrieve a pin number. After |
30cf821e | 385 | that, the subsystem passes it on to the pin control driver, so the driver |
4dfb0bd7 | 386 | will get a pin number into its handled number range. Further it is also passed |
2744e8af LW |
387 | the range ID value, so that the pin controller knows which range it should |
388 | deal with. | |
389 | ||
f23f1516 SH |
390 | Calling pinctrl_add_gpio_range from pinctrl driver is DEPRECATED. Please see |
391 | section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind | |
392 | pinctrl and gpio drivers. | |
c31a00cd | 393 | |
30cf821e | 394 | |
2744e8af LW |
395 | PINMUX interfaces |
396 | ================= | |
397 | ||
398 | These calls use the pinmux_* naming prefix. No other calls should use that | |
399 | prefix. | |
400 | ||
401 | ||
402 | What is pinmuxing? | |
403 | ================== | |
404 | ||
405 | PINMUX, also known as padmux, ballmux, alternate functions or mission modes | |
406 | is a way for chip vendors producing some kind of electrical packages to use | |
407 | a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive | |
408 | functions, depending on the application. By "application" in this context | |
409 | we usually mean a way of soldering or wiring the package into an electronic | |
410 | system, even though the framework makes it possible to also change the function | |
411 | at runtime. | |
412 | ||
0a971810 | 413 | Here is an example of a PGA (Pin Grid Array) chip seen from underneath:: |
2744e8af LW |
414 | |
415 | A B C D E F G H | |
416 | +---+ | |
417 | 8 | o | o o o o o o o | |
418 | | | | |
419 | 7 | o | o o o o o o o | |
420 | | | | |
421 | 6 | o | o o o o o o o | |
422 | +---+---+ | |
423 | 5 | o | o | o o o o o o | |
424 | +---+---+ +---+ | |
425 | 4 o o o o o o | o | o | |
426 | | | | |
427 | 3 o o o o o o | o | o | |
428 | | | | |
429 | 2 o o o o o o | o | o | |
430 | +-------+-------+-------+---+---+ | |
431 | 1 | o o | o o | o o | o | o | | |
432 | +-------+-------+-------+---+---+ | |
433 | ||
434 | This is not tetris. The game to think of is chess. Not all PGA/BGA packages | |
435 | are chessboard-like, big ones have "holes" in some arrangement according to | |
436 | different design patterns, but we're using this as a simple example. Of the | |
437 | pins you see some will be taken by things like a few VCC and GND to feed power | |
438 | to the chip, and quite a few will be taken by large ports like an external | |
439 | memory interface. The remaining pins will often be subject to pin multiplexing. | |
440 | ||
4dfb0bd7 LP |
441 | The example 8x8 PGA package above will have pin numbers 0 through 63 assigned |
442 | to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using | |
2744e8af LW |
443 | pinctrl_register_pins() and a suitable data set as shown earlier. |
444 | ||
445 | In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port | |
446 | (these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as | |
447 | some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can | |
448 | be used as an I2C port (these are just two pins: SCL, SDA). Needless to say, | |
449 | we cannot use the SPI port and I2C port at the same time. However in the inside | |
450 | of the package the silicon performing the SPI logic can alternatively be routed | |
451 | out on pins { G4, G3, G2, G1 }. | |
452 | ||
4dfb0bd7 | 453 | On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something |
2744e8af LW |
454 | special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will |
455 | consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or | |
456 | { A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI | |
457 | port on pins { G4, G3, G2, G1 } of course. | |
458 | ||
459 | This way the silicon blocks present inside the chip can be multiplexed "muxed" | |
460 | out on different pin ranges. Often contemporary SoC (systems on chip) will | |
461 | contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to | |
462 | different pins by pinmux settings. | |
463 | ||
464 | Since general-purpose I/O pins (GPIO) are typically always in shortage, it is | |
465 | common to be able to use almost any pin as a GPIO pin if it is not currently | |
466 | in use by some other I/O port. | |
467 | ||
468 | ||
469 | Pinmux conventions | |
470 | ================== | |
471 | ||
472 | The purpose of the pinmux functionality in the pin controller subsystem is to | |
473 | abstract and provide pinmux settings to the devices you choose to instantiate | |
474 | in your machine configuration. It is inspired by the clk, GPIO and regulator | |
475 | subsystems, so devices will request their mux setting, but it's also possible | |
476 | to request a single pin for e.g. GPIO. | |
477 | ||
478 | Definitions: | |
479 | ||
480 | - FUNCTIONS can be switched in and out by a driver residing with the pin | |
481 | control subsystem in the drivers/pinctrl/* directory of the kernel. The | |
482 | pin control driver knows the possible functions. In the example above you can | |
483 | identify three pinmux functions, one for spi, one for i2c and one for mmc. | |
484 | ||
485 | - FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array. | |
486 | In this case the array could be something like: { spi0, i2c0, mmc0 } | |
487 | for the three available functions. | |
488 | ||
489 | - FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain | |
490 | function is *always* associated with a certain set of pin groups, could | |
491 | be just a single one, but could also be many. In the example above the | |
492 | function i2c is associated with the pins { A5, B5 }, enumerated as | |
493 | { 24, 25 } in the controller pin space. | |
494 | ||
495 | The Function spi is associated with pin groups { A8, A7, A6, A5 } | |
496 | and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and | |
497 | { 38, 46, 54, 62 } respectively. | |
498 | ||
499 | Group names must be unique per pin controller, no two groups on the same | |
500 | controller may have the same name. | |
501 | ||
502 | - The combination of a FUNCTION and a PIN GROUP determine a certain function | |
503 | for a certain set of pins. The knowledge of the functions and pin groups | |
504 | and their machine-specific particulars are kept inside the pinmux driver, | |
191a79ff AJ |
505 | from the outside only the enumerators are known, and the driver core can |
506 | request: | |
2744e8af | 507 | |
191a79ff | 508 | - The name of a function with a certain selector (>= 0) |
2744e8af | 509 | - A list of groups associated with a certain function |
191a79ff | 510 | - That a certain group in that list to be activated for a certain function |
2744e8af LW |
511 | |
512 | As already described above, pin groups are in turn self-descriptive, so | |
513 | the core will retrieve the actual pin range in a certain group from the | |
514 | driver. | |
515 | ||
516 | - FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain | |
517 | device by the board file, device tree or similar machine setup configuration | |
518 | mechanism, similar to how regulators are connected to devices, usually by | |
519 | name. Defining a pin controller, function and group thus uniquely identify | |
520 | the set of pins to be used by a certain device. (If only one possible group | |
521 | of pins is available for the function, no group name need to be supplied - | |
522 | the core will simply select the first and only group available.) | |
523 | ||
524 | In the example case we can define that this particular machine shall | |
525 | use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function | |
526 | fi2c0 group gi2c0, on the primary pin controller, we get mappings | |
0a971810 | 527 | like these:: |
2744e8af | 528 | |
0a971810 MCC |
529 | { |
530 | {"map-spi0", spi0, pinctrl0, fspi0, gspi0}, | |
531 | {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0} | |
532 | } | |
2744e8af | 533 | |
1681f5ae SW |
534 | Every map must be assigned a state name, pin controller, device and |
535 | function. The group is not compulsory - if it is omitted the first group | |
536 | presented by the driver as applicable for the function will be selected, | |
537 | which is useful for simple cases. | |
2744e8af LW |
538 | |
539 | It is possible to map several groups to the same combination of device, | |
540 | pin controller and function. This is for cases where a certain function on | |
541 | a certain pin controller may use different sets of pins in different | |
542 | configurations. | |
543 | ||
544 | - PINS for a certain FUNCTION using a certain PIN GROUP on a certain | |
545 | PIN CONTROLLER are provided on a first-come first-serve basis, so if some | |
546 | other device mux setting or GPIO pin request has already taken your physical | |
547 | pin, you will be denied the use of it. To get (activate) a new setting, the | |
548 | old one has to be put (deactivated) first. | |
549 | ||
550 | Sometimes the documentation and hardware registers will be oriented around | |
551 | pads (or "fingers") rather than pins - these are the soldering surfaces on the | |
552 | silicon inside the package, and may or may not match the actual number of | |
553 | pins/balls underneath the capsule. Pick some enumeration that makes sense to | |
554 | you. Define enumerators only for the pins you can control if that makes sense. | |
555 | ||
556 | Assumptions: | |
557 | ||
336cdba0 | 558 | We assume that the number of possible function maps to pin groups is limited by |
2744e8af | 559 | the hardware. I.e. we assume that there is no system where any function can be |
4dfb0bd7 | 560 | mapped to any pin, like in a phone exchange. So the available pin groups for |
2744e8af LW |
561 | a certain function will be limited to a few choices (say up to eight or so), |
562 | not hundreds or any amount of choices. This is the characteristic we have found | |
563 | by inspecting available pinmux hardware, and a necessary assumption since we | |
564 | expect pinmux drivers to present *all* possible function vs pin group mappings | |
565 | to the subsystem. | |
566 | ||
567 | ||
568 | Pinmux drivers | |
569 | ============== | |
570 | ||
571 | The pinmux core takes care of preventing conflicts on pins and calling | |
572 | the pin controller driver to execute different settings. | |
573 | ||
574 | It is the responsibility of the pinmux driver to impose further restrictions | |
4dfb0bd7 | 575 | (say for example infer electronic limitations due to load, etc.) to determine |
2744e8af LW |
576 | whether or not the requested function can actually be allowed, and in case it |
577 | is possible to perform the requested mux setting, poke the hardware so that | |
578 | this happens. | |
579 | ||
580 | Pinmux drivers are required to supply a few callback functions, some are | |
260463d4 BS |
581 | optional. Usually the set_mux() function is implemented, writing values into |
582 | some certain registers to activate a certain mux setting for a certain pin. | |
2744e8af LW |
583 | |
584 | A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4 | |
585 | into some register named MUX to select a certain function with a certain | |
0a971810 MCC |
586 | group of pins would work something like this:: |
587 | ||
588 | #include <linux/pinctrl/pinctrl.h> | |
589 | #include <linux/pinctrl/pinmux.h> | |
590 | ||
591 | struct foo_group { | |
592 | const char *name; | |
593 | const unsigned int *pins; | |
594 | const unsigned num_pins; | |
595 | }; | |
596 | ||
597 | static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 }; | |
598 | static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 }; | |
599 | static const unsigned i2c0_pins[] = { 24, 25 }; | |
600 | static const unsigned mmc0_1_pins[] = { 56, 57 }; | |
601 | static const unsigned mmc0_2_pins[] = { 58, 59 }; | |
602 | static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 }; | |
603 | ||
604 | static const struct foo_group foo_groups[] = { | |
605 | { | |
606 | .name = "spi0_0_grp", | |
607 | .pins = spi0_0_pins, | |
608 | .num_pins = ARRAY_SIZE(spi0_0_pins), | |
609 | }, | |
610 | { | |
611 | .name = "spi0_1_grp", | |
612 | .pins = spi0_1_pins, | |
613 | .num_pins = ARRAY_SIZE(spi0_1_pins), | |
614 | }, | |
615 | { | |
616 | .name = "i2c0_grp", | |
617 | .pins = i2c0_pins, | |
618 | .num_pins = ARRAY_SIZE(i2c0_pins), | |
619 | }, | |
620 | { | |
621 | .name = "mmc0_1_grp", | |
622 | .pins = mmc0_1_pins, | |
623 | .num_pins = ARRAY_SIZE(mmc0_1_pins), | |
624 | }, | |
625 | { | |
626 | .name = "mmc0_2_grp", | |
627 | .pins = mmc0_2_pins, | |
628 | .num_pins = ARRAY_SIZE(mmc0_2_pins), | |
629 | }, | |
630 | { | |
631 | .name = "mmc0_3_grp", | |
632 | .pins = mmc0_3_pins, | |
633 | .num_pins = ARRAY_SIZE(mmc0_3_pins), | |
634 | }, | |
635 | }; | |
636 | ||
637 | ||
638 | static int foo_get_groups_count(struct pinctrl_dev *pctldev) | |
2744e8af | 639 | { |
0a971810 MCC |
640 | return ARRAY_SIZE(foo_groups); |
641 | } | |
642 | ||
643 | static const char *foo_get_group_name(struct pinctrl_dev *pctldev, | |
644 | unsigned selector) | |
2744e8af | 645 | { |
0a971810 MCC |
646 | return foo_groups[selector].name; |
647 | } | |
648 | ||
649 | static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, | |
650 | unsigned ** const pins, | |
651 | unsigned * const num_pins) | |
2744e8af | 652 | { |
0a971810 MCC |
653 | *pins = (unsigned *) foo_groups[selector].pins; |
654 | *num_pins = foo_groups[selector].num_pins; | |
655 | return 0; | |
656 | } | |
657 | ||
658 | static struct pinctrl_ops foo_pctrl_ops = { | |
659 | .get_groups_count = foo_get_groups_count, | |
660 | .get_group_name = foo_get_group_name, | |
661 | .get_group_pins = foo_get_group_pins, | |
662 | }; | |
663 | ||
664 | struct foo_pmx_func { | |
665 | const char *name; | |
666 | const char * const *groups; | |
667 | const unsigned num_groups; | |
668 | }; | |
669 | ||
670 | static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" }; | |
671 | static const char * const i2c0_groups[] = { "i2c0_grp" }; | |
672 | static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", | |
673 | "mmc0_3_grp" }; | |
674 | ||
675 | static const struct foo_pmx_func foo_functions[] = { | |
676 | { | |
677 | .name = "spi0", | |
678 | .groups = spi0_groups, | |
679 | .num_groups = ARRAY_SIZE(spi0_groups), | |
680 | }, | |
681 | { | |
682 | .name = "i2c0", | |
683 | .groups = i2c0_groups, | |
684 | .num_groups = ARRAY_SIZE(i2c0_groups), | |
685 | }, | |
686 | { | |
687 | .name = "mmc0", | |
688 | .groups = mmc0_groups, | |
689 | .num_groups = ARRAY_SIZE(mmc0_groups), | |
690 | }, | |
691 | }; | |
692 | ||
693 | static int foo_get_functions_count(struct pinctrl_dev *pctldev) | |
2744e8af | 694 | { |
0a971810 MCC |
695 | return ARRAY_SIZE(foo_functions); |
696 | } | |
697 | ||
698 | static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector) | |
2744e8af | 699 | { |
0a971810 MCC |
700 | return foo_functions[selector].name; |
701 | } | |
702 | ||
703 | static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector, | |
704 | const char * const **groups, | |
705 | unsigned * const num_groups) | |
2744e8af | 706 | { |
0a971810 MCC |
707 | *groups = foo_functions[selector].groups; |
708 | *num_groups = foo_functions[selector].num_groups; | |
709 | return 0; | |
710 | } | |
711 | ||
712 | static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector, | |
713 | unsigned group) | |
2744e8af | 714 | { |
0a971810 MCC |
715 | u8 regbit = (1 << selector + group); |
716 | ||
717 | writeb((readb(MUX)|regbit), MUX) | |
718 | return 0; | |
719 | } | |
720 | ||
721 | static struct pinmux_ops foo_pmxops = { | |
722 | .get_functions_count = foo_get_functions_count, | |
723 | .get_function_name = foo_get_fname, | |
724 | .get_function_groups = foo_get_groups, | |
725 | .set_mux = foo_set_mux, | |
726 | .strict = true, | |
727 | }; | |
728 | ||
729 | /* Pinmux operations are handled by some pin controller */ | |
730 | static struct pinctrl_desc foo_desc = { | |
731 | ... | |
732 | .pctlops = &foo_pctrl_ops, | |
733 | .pmxops = &foo_pmxops, | |
734 | }; | |
2744e8af LW |
735 | |
736 | In the example activating muxing 0 and 1 at the same time setting bits | |
737 | 0 and 1, uses one pin in common so they would collide. | |
738 | ||
739 | The beauty of the pinmux subsystem is that since it keeps track of all | |
740 | pins and who is using them, it will already have denied an impossible | |
741 | request like that, so the driver does not need to worry about such | |
742 | things - when it gets a selector passed in, the pinmux subsystem makes | |
743 | sure no other device or GPIO assignment is already using the selected | |
744 | pins. Thus bits 0 and 1 in the control register will never be set at the | |
745 | same time. | |
746 | ||
747 | All the above functions are mandatory to implement for a pinmux driver. | |
748 | ||
749 | ||
e93bcee0 LW |
750 | Pin control interaction with the GPIO subsystem |
751 | =============================================== | |
2744e8af | 752 | |
fdba2d06 LW |
753 | Note that the following implies that the use case is to use a certain pin |
754 | from the Linux kernel using the API in <linux/gpio.h> with gpio_request() | |
755 | and similar functions. There are cases where you may be using something | |
4dfb0bd7 | 756 | that your datasheet calls "GPIO mode", but actually is just an electrical |
fdba2d06 LW |
757 | configuration for a certain device. See the section below named |
758 | "GPIO mode pitfalls" for more details on this scenario. | |
759 | ||
a9a1d2a7 LW |
760 | The public pinmux API contains two functions named pinctrl_gpio_request() |
761 | and pinctrl_gpio_free(). These two functions shall *ONLY* be called from | |
542e704f | 762 | gpiolib-based drivers as part of their gpio_request() and |
e93bcee0 | 763 | gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output] |
542e704f LW |
764 | shall only be called from within respective gpio_direction_[input|output] |
765 | gpiolib implementation. | |
766 | ||
767 | NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be | |
e93bcee0 LW |
768 | controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have |
769 | that driver request proper muxing and other control for its pins. | |
542e704f | 770 | |
2744e8af LW |
771 | The function list could become long, especially if you can convert every |
772 | individual pin into a GPIO pin independent of any other pins, and then try | |
773 | the approach to define every pin as a function. | |
774 | ||
775 | In this case, the function array would become 64 entries for each GPIO | |
776 | setting and then the device functions. | |
777 | ||
e93bcee0 | 778 | For this reason there are two functions a pin control driver can implement |
542e704f LW |
779 | to enable only GPIO on an individual pin: .gpio_request_enable() and |
780 | .gpio_disable_free(). | |
2744e8af LW |
781 | |
782 | This function will pass in the affected GPIO range identified by the pin | |
783 | controller core, so you know which GPIO pins are being affected by the request | |
784 | operation. | |
785 | ||
542e704f LW |
786 | If your driver needs to have an indication from the framework of whether the |
787 | GPIO pin shall be used for input or output you can implement the | |
788 | .gpio_set_direction() function. As described this shall be called from the | |
789 | gpiolib driver and the affected GPIO range, pin offset and desired direction | |
790 | will be passed along to this function. | |
791 | ||
792 | Alternatively to using these special functions, it is fully allowed to use | |
a9a1d2a7 | 793 | named functions for each GPIO pin, the pinctrl_gpio_request() will attempt to |
542e704f LW |
794 | obtain the function "gpioN" where "N" is the global GPIO pin number if no |
795 | special GPIO-handler is registered. | |
2744e8af LW |
796 | |
797 | ||
fdba2d06 LW |
798 | GPIO mode pitfalls |
799 | ================== | |
800 | ||
eb6002d5 LW |
801 | Due to the naming conventions used by hardware engineers, where "GPIO" |
802 | is taken to mean different things than what the kernel does, the developer | |
803 | may be confused by a datasheet talking about a pin being possible to set | |
804 | into "GPIO mode". It appears that what hardware engineers mean with | |
805 | "GPIO mode" is not necessarily the use case that is implied in the kernel | |
806 | interface <linux/gpio.h>: a pin that you grab from kernel code and then | |
807 | either listen for input or drive high/low to assert/deassert some | |
808 | external line. | |
fdba2d06 LW |
809 | |
810 | Rather hardware engineers think that "GPIO mode" means that you can | |
811 | software-control a few electrical properties of the pin that you would | |
812 | not be able to control if the pin was in some other mode, such as muxed in | |
813 | for a device. | |
814 | ||
eb6002d5 LW |
815 | The GPIO portions of a pin and its relation to a certain pin controller |
816 | configuration and muxing logic can be constructed in several ways. Here | |
0a971810 | 817 | are two examples:: |
eb6002d5 | 818 | |
0a971810 | 819 | (A) |
eb6002d5 LW |
820 | pin config |
821 | logic regs | |
822 | | +- SPI | |
823 | Physical pins --- pad --- pinmux -+- I2C | |
824 | | +- mmc | |
825 | | +- GPIO | |
826 | pin | |
827 | multiplex | |
828 | logic regs | |
829 | ||
830 | Here some electrical properties of the pin can be configured no matter | |
831 | whether the pin is used for GPIO or not. If you multiplex a GPIO onto a | |
832 | pin, you can also drive it high/low from "GPIO" registers. | |
833 | Alternatively, the pin can be controlled by a certain peripheral, while | |
834 | still applying desired pin config properties. GPIO functionality is thus | |
835 | orthogonal to any other device using the pin. | |
836 | ||
837 | In this arrangement the registers for the GPIO portions of the pin controller, | |
838 | or the registers for the GPIO hardware module are likely to reside in a | |
839 | separate memory range only intended for GPIO driving, and the register | |
840 | range dealing with pin config and pin multiplexing get placed into a | |
841 | different memory range and a separate section of the data sheet. | |
842 | ||
7440926e | 843 | A flag "strict" in struct pinmux_ops is available to check and deny |
fa76a3db SZ |
844 | simultaneous access to the same pin from GPIO and pin multiplexing |
845 | consumers on hardware of this type. The pinctrl driver should set this flag | |
846 | accordingly. | |
847 | ||
0a971810 MCC |
848 | :: |
849 | ||
850 | (B) | |
eb6002d5 LW |
851 | |
852 | pin config | |
853 | logic regs | |
854 | | +- SPI | |
855 | Physical pins --- pad --- pinmux -+- I2C | |
856 | | | +- mmc | |
857 | | | | |
858 | GPIO pin | |
859 | multiplex | |
860 | logic regs | |
861 | ||
862 | In this arrangement, the GPIO functionality can always be enabled, such that | |
863 | e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is | |
864 | pulsed out. It is likely possible to disrupt the traffic on the pin by doing | |
865 | wrong things on the GPIO block, as it is never really disconnected. It is | |
866 | possible that the GPIO, pin config and pin multiplex registers are placed into | |
867 | the same memory range and the same section of the data sheet, although that | |
868 | need not be the case. | |
869 | ||
fa76a3db SZ |
870 | In some pin controllers, although the physical pins are designed in the same |
871 | way as (B), the GPIO function still can't be enabled at the same time as the | |
872 | peripheral functions. So again the "strict" flag should be set, denying | |
873 | simultaneous activation by GPIO and other muxed in devices. | |
874 | ||
eb6002d5 LW |
875 | From a kernel point of view, however, these are different aspects of the |
876 | hardware and shall be put into different subsystems: | |
877 | ||
878 | - Registers (or fields within registers) that control electrical | |
879 | properties of the pin such as biasing and drive strength should be | |
880 | exposed through the pinctrl subsystem, as "pin configuration" settings. | |
881 | ||
882 | - Registers (or fields within registers) that control muxing of signals | |
883 | from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should | |
4dfb0bd7 | 884 | be exposed through the pinctrl subsystem, as mux functions. |
eb6002d5 LW |
885 | |
886 | - Registers (or fields within registers) that control GPIO functionality | |
887 | such as setting a GPIO's output value, reading a GPIO's input value, or | |
888 | setting GPIO pin direction should be exposed through the GPIO subsystem, | |
889 | and if they also support interrupt capabilities, through the irqchip | |
890 | abstraction. | |
891 | ||
892 | Depending on the exact HW register design, some functions exposed by the | |
893 | GPIO subsystem may call into the pinctrl subsystem in order to | |
894 | co-ordinate register settings across HW modules. In particular, this may | |
895 | be needed for HW with separate GPIO and pin controller HW modules, where | |
896 | e.g. GPIO direction is determined by a register in the pin controller HW | |
897 | module rather than the GPIO HW module. | |
898 | ||
899 | Electrical properties of the pin such as biasing and drive strength | |
900 | may be placed at some pin-specific register in all cases or as part | |
901 | of the GPIO register in case (B) especially. This doesn't mean that such | |
902 | properties necessarily pertain to what the Linux kernel calls "GPIO". | |
903 | ||
fdba2d06 LW |
904 | Example: a pin is usually muxed in to be used as a UART TX line. But during |
905 | system sleep, we need to put this pin into "GPIO mode" and ground it. | |
906 | ||
907 | If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start | |
4dfb0bd7 | 908 | to think that you need to come up with something really complex, that the |
fdba2d06 LW |
909 | pin shall be used for UART TX and GPIO at the same time, that you will grab |
910 | a pin control handle and set it to a certain state to enable UART TX to be | |
911 | muxed in, then twist it over to GPIO mode and use gpio_direction_output() | |
912 | to drive it low during sleep, then mux it over to UART TX again when you | |
913 | wake up and maybe even gpio_request/gpio_free as part of this cycle. This | |
914 | all gets very complicated. | |
915 | ||
916 | The solution is to not think that what the datasheet calls "GPIO mode" | |
917 | has to be handled by the <linux/gpio.h> interface. Instead view this as | |
918 | a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h> | |
919 | and you find this in the documentation: | |
920 | ||
0a971810 MCC |
921 | PIN_CONFIG_OUTPUT: |
922 | this will configure the pin in output, use argument | |
fdba2d06 LW |
923 | 1 to indicate high level, argument 0 to indicate low level. |
924 | ||
925 | So it is perfectly possible to push a pin into "GPIO mode" and drive the | |
926 | line low as part of the usual pin control map. So for example your UART | |
0a971810 | 927 | driver may look like this:: |
fdba2d06 | 928 | |
0a971810 | 929 | #include <linux/pinctrl/consumer.h> |
fdba2d06 | 930 | |
0a971810 MCC |
931 | struct pinctrl *pinctrl; |
932 | struct pinctrl_state *pins_default; | |
933 | struct pinctrl_state *pins_sleep; | |
fdba2d06 | 934 | |
0a971810 MCC |
935 | pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT); |
936 | pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP); | |
fdba2d06 | 937 | |
0a971810 MCC |
938 | /* Normal mode */ |
939 | retval = pinctrl_select_state(pinctrl, pins_default); | |
940 | /* Sleep mode */ | |
941 | retval = pinctrl_select_state(pinctrl, pins_sleep); | |
fdba2d06 LW |
942 | |
943 | And your machine configuration may look like this: | |
944 | -------------------------------------------------- | |
945 | ||
0a971810 MCC |
946 | :: |
947 | ||
948 | static unsigned long uart_default_mode[] = { | |
949 | PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0), | |
950 | }; | |
951 | ||
952 | static unsigned long uart_sleep_mode[] = { | |
953 | PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0), | |
954 | }; | |
955 | ||
956 | static struct pinctrl_map pinmap[] __initdata = { | |
957 | PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", | |
958 | "u0_group", "u0"), | |
959 | PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", | |
960 | "UART_TX_PIN", uart_default_mode), | |
961 | PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", | |
962 | "u0_group", "gpio-mode"), | |
963 | PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", | |
964 | "UART_TX_PIN", uart_sleep_mode), | |
965 | }; | |
966 | ||
967 | foo_init(void) { | |
968 | pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap)); | |
969 | } | |
fdba2d06 LW |
970 | |
971 | Here the pins we want to control are in the "u0_group" and there is some | |
972 | function called "u0" that can be enabled on this group of pins, and then | |
973 | everything is UART business as usual. But there is also some function | |
974 | named "gpio-mode" that can be mapped onto the same pins to move them into | |
975 | GPIO mode. | |
976 | ||
977 | This will give the desired effect without any bogus interaction with the | |
978 | GPIO subsystem. It is just an electrical configuration used by that device | |
979 | when going to sleep, it might imply that the pin is set into something the | |
4dfb0bd7 | 980 | datasheet calls "GPIO mode", but that is not the point: it is still used |
fdba2d06 LW |
981 | by that UART device to control the pins that pertain to that very UART |
982 | driver, putting them into modes needed by the UART. GPIO in the Linux | |
983 | kernel sense are just some 1-bit line, and is a different use case. | |
984 | ||
4dfb0bd7 | 985 | How the registers are poked to attain the push or pull, and output low |
fdba2d06 LW |
986 | configuration and the muxing of the "u0" or "gpio-mode" group onto these |
987 | pins is a question for the driver. | |
988 | ||
989 | Some datasheets will be more helpful and refer to the "GPIO mode" as | |
990 | "low power mode" rather than anything to do with GPIO. This often means | |
991 | the same thing electrically speaking, but in this latter case the | |
992 | software engineers will usually quickly identify that this is some | |
4dfb0bd7 | 993 | specific muxing or configuration rather than anything related to the GPIO |
fdba2d06 LW |
994 | API. |
995 | ||
996 | ||
1e2082b5 | 997 | Board/machine configuration |
0a971810 | 998 | =========================== |
2744e8af LW |
999 | |
1000 | Boards and machines define how a certain complete running system is put | |
1001 | together, including how GPIOs and devices are muxed, how regulators are | |
1002 | constrained and how the clock tree looks. Of course pinmux settings are also | |
1003 | part of this. | |
1004 | ||
1e2082b5 SW |
1005 | A pin controller configuration for a machine looks pretty much like a simple |
1006 | regulator configuration, so for the example array above we want to enable i2c | |
0a971810 MCC |
1007 | and spi on the second function mapping:: |
1008 | ||
1009 | #include <linux/pinctrl/machine.h> | |
1010 | ||
1011 | static const struct pinctrl_map mapping[] __initconst = { | |
1012 | { | |
1013 | .dev_name = "foo-spi.0", | |
1014 | .name = PINCTRL_STATE_DEFAULT, | |
1015 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1016 | .ctrl_dev_name = "pinctrl-foo", | |
1017 | .data.mux.function = "spi0", | |
1018 | }, | |
1019 | { | |
1020 | .dev_name = "foo-i2c.0", | |
1021 | .name = PINCTRL_STATE_DEFAULT, | |
1022 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1023 | .ctrl_dev_name = "pinctrl-foo", | |
1024 | .data.mux.function = "i2c0", | |
1025 | }, | |
1026 | { | |
1027 | .dev_name = "foo-mmc.0", | |
1028 | .name = PINCTRL_STATE_DEFAULT, | |
1029 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1030 | .ctrl_dev_name = "pinctrl-foo", | |
1031 | .data.mux.function = "mmc0", | |
1032 | }, | |
1033 | }; | |
2744e8af LW |
1034 | |
1035 | The dev_name here matches to the unique device name that can be used to look | |
1036 | up the device struct (just like with clockdev or regulators). The function name | |
1037 | must match a function provided by the pinmux driver handling this pin range. | |
1038 | ||
1039 | As you can see we may have several pin controllers on the system and thus | |
4dfb0bd7 | 1040 | we need to specify which one of them contains the functions we wish to map. |
2744e8af | 1041 | |
0a971810 | 1042 | You register this pinmux mapping to the pinmux subsystem by simply:: |
2744e8af | 1043 | |
e93bcee0 | 1044 | ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping)); |
2744e8af LW |
1045 | |
1046 | Since the above construct is pretty common there is a helper macro to make | |
51cd24ee | 1047 | it even more compact which assumes you want to use pinctrl-foo and position |
0a971810 | 1048 | 0 for mapping, for example:: |
2744e8af | 1049 | |
0a971810 MCC |
1050 | static struct pinctrl_map mapping[] __initdata = { |
1051 | PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, | |
1052 | "pinctrl-foo", NULL, "i2c0"), | |
1053 | }; | |
1e2082b5 SW |
1054 | |
1055 | The mapping table may also contain pin configuration entries. It's common for | |
1056 | each pin/group to have a number of configuration entries that affect it, so | |
1057 | the table entries for configuration reference an array of config parameters | |
0a971810 MCC |
1058 | and values. An example using the convenience macros is shown below:: |
1059 | ||
1060 | static unsigned long i2c_grp_configs[] = { | |
1061 | FOO_PIN_DRIVEN, | |
1062 | FOO_PIN_PULLUP, | |
1063 | }; | |
1064 | ||
1065 | static unsigned long i2c_pin_configs[] = { | |
1066 | FOO_OPEN_COLLECTOR, | |
1067 | FOO_SLEW_RATE_SLOW, | |
1068 | }; | |
1069 | ||
1070 | static struct pinctrl_map mapping[] __initdata = { | |
1071 | PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, | |
1072 | "pinctrl-foo", "i2c0", "i2c0"), | |
1073 | PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, | |
1074 | "pinctrl-foo", "i2c0", i2c_grp_configs), | |
1075 | PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, | |
1076 | "pinctrl-foo", "i2c0scl", i2c_pin_configs), | |
1077 | PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, | |
1078 | "pinctrl-foo", "i2c0sda", i2c_pin_configs), | |
1079 | }; | |
1e2082b5 SW |
1080 | |
1081 | Finally, some devices expect the mapping table to contain certain specific | |
1082 | named states. When running on hardware that doesn't need any pin controller | |
1083 | configuration, the mapping table must still contain those named states, in | |
1084 | order to explicitly indicate that the states were provided and intended to | |
1085 | be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining | |
0a971810 | 1086 | a named state without causing any pin controller to be programmed:: |
1e2082b5 | 1087 | |
0a971810 MCC |
1088 | static struct pinctrl_map mapping[] __initdata = { |
1089 | PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT), | |
1090 | }; | |
2744e8af LW |
1091 | |
1092 | ||
1093 | Complex mappings | |
1094 | ================ | |
1095 | ||
1096 | As it is possible to map a function to different groups of pins an optional | |
0a971810 MCC |
1097 | .group can be specified like this:: |
1098 | ||
1099 | ... | |
1100 | { | |
1101 | .dev_name = "foo-spi.0", | |
1102 | .name = "spi0-pos-A", | |
1103 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1104 | .ctrl_dev_name = "pinctrl-foo", | |
1105 | .function = "spi0", | |
1106 | .group = "spi0_0_grp", | |
1107 | }, | |
1108 | { | |
1109 | .dev_name = "foo-spi.0", | |
1110 | .name = "spi0-pos-B", | |
1111 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1112 | .ctrl_dev_name = "pinctrl-foo", | |
1113 | .function = "spi0", | |
1114 | .group = "spi0_1_grp", | |
1115 | }, | |
1116 | ... | |
2744e8af LW |
1117 | |
1118 | This example mapping is used to switch between two positions for spi0 at | |
1119 | runtime, as described further below under the heading "Runtime pinmuxing". | |
1120 | ||
6e5e959d SW |
1121 | Further it is possible for one named state to affect the muxing of several |
1122 | groups of pins, say for example in the mmc0 example above, where you can | |
2744e8af LW |
1123 | additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all |
1124 | three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the | |
0a971810 MCC |
1125 | case), we define a mapping like this:: |
1126 | ||
1127 | ... | |
1128 | { | |
1129 | .dev_name = "foo-mmc.0", | |
1130 | .name = "2bit" | |
1131 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1132 | .ctrl_dev_name = "pinctrl-foo", | |
1133 | .function = "mmc0", | |
1134 | .group = "mmc0_1_grp", | |
1135 | }, | |
1136 | { | |
1137 | .dev_name = "foo-mmc.0", | |
1138 | .name = "4bit" | |
1139 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1140 | .ctrl_dev_name = "pinctrl-foo", | |
1141 | .function = "mmc0", | |
1142 | .group = "mmc0_1_grp", | |
1143 | }, | |
1144 | { | |
1145 | .dev_name = "foo-mmc.0", | |
1146 | .name = "4bit" | |
1147 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1148 | .ctrl_dev_name = "pinctrl-foo", | |
1149 | .function = "mmc0", | |
1150 | .group = "mmc0_2_grp", | |
1151 | }, | |
1152 | { | |
1153 | .dev_name = "foo-mmc.0", | |
1154 | .name = "8bit" | |
1155 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1156 | .ctrl_dev_name = "pinctrl-foo", | |
1157 | .function = "mmc0", | |
1158 | .group = "mmc0_1_grp", | |
1159 | }, | |
1160 | { | |
1161 | .dev_name = "foo-mmc.0", | |
1162 | .name = "8bit" | |
1163 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1164 | .ctrl_dev_name = "pinctrl-foo", | |
1165 | .function = "mmc0", | |
1166 | .group = "mmc0_2_grp", | |
1167 | }, | |
1168 | { | |
1169 | .dev_name = "foo-mmc.0", | |
1170 | .name = "8bit" | |
1171 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1172 | .ctrl_dev_name = "pinctrl-foo", | |
1173 | .function = "mmc0", | |
1174 | .group = "mmc0_3_grp", | |
1175 | }, | |
1176 | ... | |
2744e8af LW |
1177 | |
1178 | The result of grabbing this mapping from the device with something like | |
0a971810 | 1179 | this (see next paragraph):: |
2744e8af | 1180 | |
6d4ca1fb | 1181 | p = devm_pinctrl_get(dev); |
6e5e959d SW |
1182 | s = pinctrl_lookup_state(p, "8bit"); |
1183 | ret = pinctrl_select_state(p, s); | |
1184 | ||
0a971810 | 1185 | or more simply:: |
6e5e959d | 1186 | |
6d4ca1fb | 1187 | p = devm_pinctrl_get_select(dev, "8bit"); |
2744e8af LW |
1188 | |
1189 | Will be that you activate all the three bottom records in the mapping at | |
6e5e959d | 1190 | once. Since they share the same name, pin controller device, function and |
2744e8af LW |
1191 | device, and since we allow multiple groups to match to a single device, they |
1192 | all get selected, and they all get enabled and disable simultaneously by the | |
1193 | pinmux core. | |
1194 | ||
1195 | ||
c31a00cd LW |
1196 | Pin control requests from drivers |
1197 | ================================= | |
2744e8af | 1198 | |
ab78029e LW |
1199 | When a device driver is about to probe the device core will automatically |
1200 | attempt to issue pinctrl_get_select_default() on these devices. | |
1201 | This way driver writers do not need to add any of the boilerplate code | |
1202 | of the type found below. However when doing fine-grained state selection | |
1203 | and not using the "default" state, you may have to do some device driver | |
1204 | handling of the pinctrl handles and states. | |
1205 | ||
1206 | So if you just want to put the pins for a certain device into the default | |
1207 | state and be done with it, there is nothing you need to do besides | |
1208 | providing the proper mapping table. The device core will take care of | |
1209 | the rest. | |
1210 | ||
e93bcee0 LW |
1211 | Generally it is discouraged to let individual drivers get and enable pin |
1212 | control. So if possible, handle the pin control in platform code or some other | |
1213 | place where you have access to all the affected struct device * pointers. In | |
1214 | some cases where a driver needs to e.g. switch between different mux mappings | |
1215 | at runtime this is not possible. | |
2744e8af | 1216 | |
c31a00cd LW |
1217 | A typical case is if a driver needs to switch bias of pins from normal |
1218 | operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to | |
1219 | PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save | |
1220 | current in sleep mode. | |
1221 | ||
e93bcee0 | 1222 | A driver may request a certain control state to be activated, usually just the |
0a971810 | 1223 | default state like this:: |
2744e8af | 1224 | |
0a971810 | 1225 | #include <linux/pinctrl/consumer.h> |
2744e8af | 1226 | |
0a971810 MCC |
1227 | struct foo_state { |
1228 | struct pinctrl *p; | |
1229 | struct pinctrl_state *s; | |
1230 | ... | |
1231 | }; | |
2744e8af | 1232 | |
0a971810 MCC |
1233 | foo_probe() |
1234 | { | |
1235 | /* Allocate a state holder named "foo" etc */ | |
1236 | struct foo_state *foo = ...; | |
6e5e959d | 1237 | |
0a971810 MCC |
1238 | foo->p = devm_pinctrl_get(&device); |
1239 | if (IS_ERR(foo->p)) { | |
1240 | /* FIXME: clean up "foo" here */ | |
1241 | return PTR_ERR(foo->p); | |
1242 | } | |
2744e8af | 1243 | |
0a971810 MCC |
1244 | foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT); |
1245 | if (IS_ERR(foo->s)) { | |
1246 | /* FIXME: clean up "foo" here */ | |
1247 | return PTR_ERR(s); | |
1248 | } | |
2744e8af | 1249 | |
0a971810 MCC |
1250 | ret = pinctrl_select_state(foo->s); |
1251 | if (ret < 0) { | |
1252 | /* FIXME: clean up "foo" here */ | |
1253 | return ret; | |
1254 | } | |
6e5e959d | 1255 | } |
2744e8af | 1256 | |
6e5e959d | 1257 | This get/lookup/select/put sequence can just as well be handled by bus drivers |
2744e8af LW |
1258 | if you don't want each and every driver to handle it and you know the |
1259 | arrangement on your bus. | |
1260 | ||
6e5e959d SW |
1261 | The semantics of the pinctrl APIs are: |
1262 | ||
1263 | - pinctrl_get() is called in process context to obtain a handle to all pinctrl | |
1264 | information for a given client device. It will allocate a struct from the | |
1265 | kernel memory to hold the pinmux state. All mapping table parsing or similar | |
1266 | slow operations take place within this API. | |
2744e8af | 1267 | |
6d4ca1fb SW |
1268 | - devm_pinctrl_get() is a variant of pinctrl_get() that causes pinctrl_put() |
1269 | to be called automatically on the retrieved pointer when the associated | |
1270 | device is removed. It is recommended to use this function over plain | |
1271 | pinctrl_get(). | |
1272 | ||
6e5e959d | 1273 | - pinctrl_lookup_state() is called in process context to obtain a handle to a |
4dfb0bd7 | 1274 | specific state for a client device. This operation may be slow, too. |
2744e8af | 1275 | |
6e5e959d | 1276 | - pinctrl_select_state() programs pin controller hardware according to the |
4dfb0bd7 | 1277 | definition of the state as given by the mapping table. In theory, this is a |
6e5e959d SW |
1278 | fast-path operation, since it only involved blasting some register settings |
1279 | into hardware. However, note that some pin controllers may have their | |
1280 | registers on a slow/IRQ-based bus, so client devices should not assume they | |
1281 | can call pinctrl_select_state() from non-blocking contexts. | |
2744e8af | 1282 | |
6e5e959d | 1283 | - pinctrl_put() frees all information associated with a pinctrl handle. |
2744e8af | 1284 | |
6d4ca1fb SW |
1285 | - devm_pinctrl_put() is a variant of pinctrl_put() that may be used to |
1286 | explicitly destroy a pinctrl object returned by devm_pinctrl_get(). | |
1287 | However, use of this function will be rare, due to the automatic cleanup | |
1288 | that will occur even without calling it. | |
1289 | ||
1290 | pinctrl_get() must be paired with a plain pinctrl_put(). | |
1291 | pinctrl_get() may not be paired with devm_pinctrl_put(). | |
1292 | devm_pinctrl_get() can optionally be paired with devm_pinctrl_put(). | |
1293 | devm_pinctrl_get() may not be paired with plain pinctrl_put(). | |
1294 | ||
e93bcee0 LW |
1295 | Usually the pin control core handled the get/put pair and call out to the |
1296 | device drivers bookkeeping operations, like checking available functions and | |
b18104c0 | 1297 | the associated pins, whereas select_state pass on to the pin controller |
2744e8af LW |
1298 | driver which takes care of activating and/or deactivating the mux setting by |
1299 | quickly poking some registers. | |
1300 | ||
6d4ca1fb SW |
1301 | The pins are allocated for your device when you issue the devm_pinctrl_get() |
1302 | call, after this you should be able to see this in the debugfs listing of all | |
1303 | pins. | |
2744e8af | 1304 | |
c05127c4 LW |
1305 | NOTE: the pinctrl system will return -EPROBE_DEFER if it cannot find the |
1306 | requested pinctrl handles, for example if the pinctrl driver has not yet | |
1307 | registered. Thus make sure that the error path in your driver gracefully | |
1308 | cleans up and is ready to retry the probing later in the startup process. | |
1309 | ||
2744e8af | 1310 | |
c31a00cd LW |
1311 | Drivers needing both pin control and GPIOs |
1312 | ========================================== | |
1313 | ||
1314 | Again, it is discouraged to let drivers lookup and select pin control states | |
1315 | themselves, but again sometimes this is unavoidable. | |
1316 | ||
0a971810 | 1317 | So say that your driver is fetching its resources like this:: |
c31a00cd | 1318 | |
0a971810 MCC |
1319 | #include <linux/pinctrl/consumer.h> |
1320 | #include <linux/gpio.h> | |
c31a00cd | 1321 | |
0a971810 MCC |
1322 | struct pinctrl *pinctrl; |
1323 | int gpio; | |
c31a00cd | 1324 | |
0a971810 MCC |
1325 | pinctrl = devm_pinctrl_get_select_default(&dev); |
1326 | gpio = devm_gpio_request(&dev, 14, "foo"); | |
c31a00cd LW |
1327 | |
1328 | Here we first request a certain pin state and then request GPIO 14 to be | |
1329 | used. If you're using the subsystems orthogonally like this, you should | |
1330 | nominally always get your pinctrl handle and select the desired pinctrl | |
1331 | state BEFORE requesting the GPIO. This is a semantic convention to avoid | |
1332 | situations that can be electrically unpleasant, you will certainly want to | |
1333 | mux in and bias pins in a certain way before the GPIO subsystems starts to | |
1334 | deal with them. | |
1335 | ||
ab78029e LW |
1336 | The above can be hidden: using the device core, the pinctrl core may be |
1337 | setting up the config and muxing for the pins right before the device is | |
1338 | probing, nevertheless orthogonal to the GPIO subsystem. | |
c31a00cd LW |
1339 | |
1340 | But there are also situations where it makes sense for the GPIO subsystem | |
7bbc87b8 JH |
1341 | to communicate directly with the pinctrl subsystem, using the latter as a |
1342 | back-end. This is when the GPIO driver may call out to the functions | |
c31a00cd LW |
1343 | described in the section "Pin control interaction with the GPIO subsystem" |
1344 | above. This only involves per-pin multiplexing, and will be completely | |
1345 | hidden behind the gpio_*() function namespace. In this case, the driver | |
1346 | need not interact with the pin control subsystem at all. | |
1347 | ||
1348 | If a pin control driver and a GPIO driver is dealing with the same pins | |
1349 | and the use cases involve multiplexing, you MUST implement the pin controller | |
1350 | as a back-end for the GPIO driver like this, unless your hardware design | |
1351 | is such that the GPIO controller can override the pin controller's | |
1352 | multiplexing state through hardware without the need to interact with the | |
1353 | pin control system. | |
1354 | ||
1355 | ||
e93bcee0 LW |
1356 | System pin control hogging |
1357 | ========================== | |
2744e8af | 1358 | |
1681f5ae | 1359 | Pin control map entries can be hogged by the core when the pin controller |
6e5e959d SW |
1360 | is registered. This means that the core will attempt to call pinctrl_get(), |
1361 | lookup_state() and select_state() on it immediately after the pin control | |
1362 | device has been registered. | |
2744e8af | 1363 | |
6e5e959d | 1364 | This occurs for mapping table entries where the client device name is equal |
0a971810 | 1365 | to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT:: |
2744e8af | 1366 | |
0a971810 MCC |
1367 | { |
1368 | .dev_name = "pinctrl-foo", | |
1369 | .name = PINCTRL_STATE_DEFAULT, | |
1370 | .type = PIN_MAP_TYPE_MUX_GROUP, | |
1371 | .ctrl_dev_name = "pinctrl-foo", | |
1372 | .function = "power_func", | |
1373 | }, | |
2744e8af LW |
1374 | |
1375 | Since it may be common to request the core to hog a few always-applicable | |
1376 | mux settings on the primary pin controller, there is a convenience macro for | |
0a971810 | 1377 | this:: |
2744e8af | 1378 | |
0a971810 MCC |
1379 | PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, |
1380 | "power_func") | |
2744e8af LW |
1381 | |
1382 | This gives the exact same result as the above construction. | |
1383 | ||
1384 | ||
1385 | Runtime pinmuxing | |
1386 | ================= | |
1387 | ||
1388 | It is possible to mux a certain function in and out at runtime, say to move | |
1389 | an SPI port from one set of pins to another set of pins. Say for example for | |
1390 | spi0 in the example above, we expose two different groups of pins for the same | |
1391 | function, but with different named in the mapping as described under | |
6e5e959d SW |
1392 | "Advanced mapping" above. So that for an SPI device, we have two states named |
1393 | "pos-A" and "pos-B". | |
2744e8af | 1394 | |
b18104c0 BS |
1395 | This snippet first initializes a state object for both groups (in foo_probe()), |
1396 | then muxes the function in the pins defined by group A, and finally muxes it in | |
0a971810 | 1397 | on the pins defined by group B:: |
2744e8af | 1398 | |
0a971810 | 1399 | #include <linux/pinctrl/consumer.h> |
28a8d14c | 1400 | |
0a971810 MCC |
1401 | struct pinctrl *p; |
1402 | struct pinctrl_state *s1, *s2; | |
6e5e959d | 1403 | |
0a971810 MCC |
1404 | foo_probe() |
1405 | { | |
1406 | /* Setup */ | |
1407 | p = devm_pinctrl_get(&device); | |
1408 | if (IS_ERR(p)) | |
1409 | ... | |
1410 | ||
1411 | s1 = pinctrl_lookup_state(foo->p, "pos-A"); | |
1412 | if (IS_ERR(s1)) | |
1413 | ... | |
1414 | ||
1415 | s2 = pinctrl_lookup_state(foo->p, "pos-B"); | |
1416 | if (IS_ERR(s2)) | |
1417 | ... | |
1418 | } | |
6e5e959d | 1419 | |
0a971810 MCC |
1420 | foo_switch() |
1421 | { | |
1422 | /* Enable on position A */ | |
1423 | ret = pinctrl_select_state(s1); | |
1424 | if (ret < 0) | |
6e5e959d SW |
1425 | ... |
1426 | ||
6e5e959d | 1427 | ... |
2744e8af | 1428 | |
0a971810 MCC |
1429 | /* Enable on position B */ |
1430 | ret = pinctrl_select_state(s2); | |
1431 | if (ret < 0) | |
1432 | ... | |
6e5e959d | 1433 | |
0a971810 MCC |
1434 | ... |
1435 | } | |
2744e8af | 1436 | |
1a78958d LW |
1437 | The above has to be done from process context. The reservation of the pins |
1438 | will be done when the state is activated, so in effect one specific pin | |
1439 | can be used by different functions at different times on a running system. |