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