]>
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, | |
21 | set drive strength etc for individual pins or groups of pins. | |
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), | |
75 | .maxpin = 63, | |
76 | .owner = THIS_MODULE, | |
77 | }; | |
78 | ||
79 | int __init foo_probe(void) | |
80 | { | |
81 | struct pinctrl_dev *pctl; | |
82 | ||
83 | pctl = pinctrl_register(&foo_desc, <PARENT>, NULL); | |
84 | if (IS_ERR(pctl)) | |
85 | pr_err("could not register foo pin driver\n"); | |
86 | } | |
87 | ||
ae6b4d85 LW |
88 | To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and |
89 | selected drivers, you need to select them from your machine's Kconfig entry, | |
90 | since these are so tightly integrated with the machines they are used on. | |
91 | See for example arch/arm/mach-u300/Kconfig for an example. | |
92 | ||
2744e8af LW |
93 | Pins usually have fancier names than this. You can find these in the dataheet |
94 | for your chip. Notice that the core pinctrl.h file provides a fancy macro | |
95 | called PINCTRL_PIN() to create the struct entries. As you can see I enumerated | |
336cdba0 LW |
96 | the pins from 0 in the upper left corner to 63 in the lower right corner. |
97 | This enumeration was arbitrarily chosen, in practice you need to think | |
2744e8af LW |
98 | through your numbering system so that it matches the layout of registers |
99 | and such things in your driver, or the code may become complicated. You must | |
100 | also consider matching of offsets to the GPIO ranges that may be handled by | |
101 | the pin controller. | |
102 | ||
103 | For a padring with 467 pads, as opposed to actual pins, I used an enumeration | |
104 | like this, walking around the edge of the chip, which seems to be industry | |
105 | standard too (all these pads had names, too): | |
106 | ||
107 | ||
108 | 0 ..... 104 | |
109 | 466 105 | |
110 | . . | |
111 | . . | |
112 | 358 224 | |
113 | 357 .... 225 | |
114 | ||
115 | ||
116 | Pin groups | |
117 | ========== | |
118 | ||
119 | Many controllers need to deal with groups of pins, so the pin controller | |
120 | subsystem has a mechanism for enumerating groups of pins and retrieving the | |
121 | actual enumerated pins that are part of a certain group. | |
122 | ||
123 | For example, say that we have a group of pins dealing with an SPI interface | |
124 | on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins | |
125 | on { 24, 25 }. | |
126 | ||
127 | These two groups are presented to the pin control subsystem by implementing | |
128 | some generic pinctrl_ops like this: | |
129 | ||
130 | #include <linux/pinctrl/pinctrl.h> | |
131 | ||
132 | struct foo_group { | |
133 | const char *name; | |
134 | const unsigned int *pins; | |
135 | const unsigned num_pins; | |
136 | }; | |
137 | ||
336cdba0 LW |
138 | static const unsigned int spi0_pins[] = { 0, 8, 16, 24 }; |
139 | static const unsigned int i2c0_pins[] = { 24, 25 }; | |
2744e8af LW |
140 | |
141 | static const struct foo_group foo_groups[] = { | |
142 | { | |
143 | .name = "spi0_grp", | |
144 | .pins = spi0_pins, | |
145 | .num_pins = ARRAY_SIZE(spi0_pins), | |
146 | }, | |
147 | { | |
148 | .name = "i2c0_grp", | |
149 | .pins = i2c0_pins, | |
150 | .num_pins = ARRAY_SIZE(i2c0_pins), | |
151 | }, | |
152 | }; | |
153 | ||
154 | ||
155 | static int foo_list_groups(struct pinctrl_dev *pctldev, unsigned selector) | |
156 | { | |
157 | if (selector >= ARRAY_SIZE(foo_groups)) | |
158 | return -EINVAL; | |
159 | return 0; | |
160 | } | |
161 | ||
162 | static const char *foo_get_group_name(struct pinctrl_dev *pctldev, | |
163 | unsigned selector) | |
164 | { | |
165 | return foo_groups[selector].name; | |
166 | } | |
167 | ||
168 | static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, | |
169 | unsigned ** const pins, | |
170 | unsigned * const num_pins) | |
171 | { | |
172 | *pins = (unsigned *) foo_groups[selector].pins; | |
173 | *num_pins = foo_groups[selector].num_pins; | |
174 | return 0; | |
175 | } | |
176 | ||
177 | static struct pinctrl_ops foo_pctrl_ops = { | |
178 | .list_groups = foo_list_groups, | |
179 | .get_group_name = foo_get_group_name, | |
180 | .get_group_pins = foo_get_group_pins, | |
181 | }; | |
182 | ||
183 | ||
184 | static struct pinctrl_desc foo_desc = { | |
185 | ... | |
186 | .pctlops = &foo_pctrl_ops, | |
187 | }; | |
188 | ||
189 | The pin control subsystem will call the .list_groups() function repeatedly | |
190 | beginning on 0 until it returns non-zero to determine legal selectors, then | |
191 | it will call the other functions to retrieve the name and pins of the group. | |
192 | Maintaining the data structure of the groups is up to the driver, this is | |
193 | just a simple example - in practice you may need more entries in your group | |
194 | structure, for example specific register ranges associated with each group | |
195 | and so on. | |
196 | ||
197 | ||
ae6b4d85 LW |
198 | Pin configuration |
199 | ================= | |
200 | ||
201 | Pins can sometimes be software-configured in an various ways, mostly related | |
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 | ||
209 | For example, a platform may do this: | |
210 | ||
28a8d14c LW |
211 | #include <linux/pinctrl/consumer.h> |
212 | ||
43699dea | 213 | ret = pin_config_set("foo-dev", "FOO_GPIO_PIN", PLATFORM_X_PULL_UP); |
ae6b4d85 LW |
214 | |
215 | To pull up a pin to VDD. The pin configuration driver implements callbacks for | |
216 | changing pin configuration in the pin controller ops like this: | |
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 | ||
288 | Since the pin controller subsystem have its pinspace local to the pin | |
289 | controller we need a mapping so that the pin control subsystem can figure out | |
290 | which pin controller handles control of a certain GPIO pin. Since a single | |
291 | pin controller may be muxing several GPIO ranges (typically SoCs that have | |
292 | one set of pins but internally several GPIO silicon blocks, each modeled as | |
293 | a struct gpio_chip) any number of GPIO ranges can be added to a pin controller | |
294 | instance like this: | |
295 | ||
296 | struct gpio_chip chip_a; | |
297 | struct gpio_chip chip_b; | |
298 | ||
299 | static struct pinctrl_gpio_range gpio_range_a = { | |
300 | .name = "chip a", | |
301 | .id = 0, | |
302 | .base = 32, | |
3c739ad0 | 303 | .pin_base = 32, |
2744e8af LW |
304 | .npins = 16, |
305 | .gc = &chip_a; | |
306 | }; | |
307 | ||
3c739ad0 | 308 | static struct pinctrl_gpio_range gpio_range_b = { |
2744e8af LW |
309 | .name = "chip b", |
310 | .id = 0, | |
311 | .base = 48, | |
3c739ad0 | 312 | .pin_base = 64, |
2744e8af LW |
313 | .npins = 8, |
314 | .gc = &chip_b; | |
315 | }; | |
316 | ||
2744e8af LW |
317 | { |
318 | struct pinctrl_dev *pctl; | |
319 | ... | |
320 | pinctrl_add_gpio_range(pctl, &gpio_range_a); | |
321 | pinctrl_add_gpio_range(pctl, &gpio_range_b); | |
322 | } | |
323 | ||
324 | So this complex system has one pin controller handling two different | |
3c739ad0 CP |
325 | GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and |
326 | "chip b" have different .pin_base, which means a start pin number of the | |
327 | GPIO range. | |
328 | ||
329 | The GPIO range of "chip a" starts from the GPIO base of 32 and actual | |
330 | pin range also starts from 32. However "chip b" has different starting | |
331 | offset for the GPIO range and pin range. The GPIO range of "chip b" starts | |
332 | from GPIO number 48, while the pin range of "chip b" starts from 64. | |
2744e8af | 333 | |
3c739ad0 CP |
334 | We can convert a gpio number to actual pin number using this "pin_base". |
335 | They are mapped in the global GPIO pin space at: | |
336 | ||
337 | chip a: | |
338 | - GPIO range : [32 .. 47] | |
339 | - pin range : [32 .. 47] | |
340 | chip b: | |
341 | - GPIO range : [48 .. 55] | |
342 | - pin range : [64 .. 71] | |
2744e8af LW |
343 | |
344 | When GPIO-specific functions in the pin control subsystem are called, these | |
336cdba0 | 345 | ranges will be used to look up the appropriate pin controller by inspecting |
2744e8af LW |
346 | and matching the pin to the pin ranges across all controllers. When a |
347 | pin controller handling the matching range is found, GPIO-specific functions | |
348 | will be called on that specific pin controller. | |
349 | ||
350 | For all functionalities dealing with pin biasing, pin muxing etc, the pin | |
351 | controller subsystem will subtract the range's .base offset from the passed | |
3c739ad0 CP |
352 | in gpio number, and add the ranges's .pin_base offset to retrive a pin number. |
353 | After that, the subsystem passes it on to the pin control driver, so the driver | |
354 | will get an pin number into its handled number range. Further it is also passed | |
2744e8af LW |
355 | the range ID value, so that the pin controller knows which range it should |
356 | deal with. | |
357 | ||
2744e8af LW |
358 | PINMUX interfaces |
359 | ================= | |
360 | ||
361 | These calls use the pinmux_* naming prefix. No other calls should use that | |
362 | prefix. | |
363 | ||
364 | ||
365 | What is pinmuxing? | |
366 | ================== | |
367 | ||
368 | PINMUX, also known as padmux, ballmux, alternate functions or mission modes | |
369 | is a way for chip vendors producing some kind of electrical packages to use | |
370 | a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive | |
371 | functions, depending on the application. By "application" in this context | |
372 | we usually mean a way of soldering or wiring the package into an electronic | |
373 | system, even though the framework makes it possible to also change the function | |
374 | at runtime. | |
375 | ||
376 | Here is an example of a PGA (Pin Grid Array) chip seen from underneath: | |
377 | ||
378 | A B C D E F G H | |
379 | +---+ | |
380 | 8 | o | o o o o o o o | |
381 | | | | |
382 | 7 | o | o o o o o o o | |
383 | | | | |
384 | 6 | o | o o o o o o o | |
385 | +---+---+ | |
386 | 5 | o | o | o o o o o o | |
387 | +---+---+ +---+ | |
388 | 4 o o o o o o | o | o | |
389 | | | | |
390 | 3 o o o o o o | o | o | |
391 | | | | |
392 | 2 o o o o o o | o | o | |
393 | +-------+-------+-------+---+---+ | |
394 | 1 | o o | o o | o o | o | o | | |
395 | +-------+-------+-------+---+---+ | |
396 | ||
397 | This is not tetris. The game to think of is chess. Not all PGA/BGA packages | |
398 | are chessboard-like, big ones have "holes" in some arrangement according to | |
399 | different design patterns, but we're using this as a simple example. Of the | |
400 | pins you see some will be taken by things like a few VCC and GND to feed power | |
401 | to the chip, and quite a few will be taken by large ports like an external | |
402 | memory interface. The remaining pins will often be subject to pin multiplexing. | |
403 | ||
404 | The example 8x8 PGA package above will have pin numbers 0 thru 63 assigned to | |
405 | its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using | |
406 | pinctrl_register_pins() and a suitable data set as shown earlier. | |
407 | ||
408 | In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port | |
409 | (these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as | |
410 | some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can | |
411 | be used as an I2C port (these are just two pins: SCL, SDA). Needless to say, | |
412 | we cannot use the SPI port and I2C port at the same time. However in the inside | |
413 | of the package the silicon performing the SPI logic can alternatively be routed | |
414 | out on pins { G4, G3, G2, G1 }. | |
415 | ||
416 | On the botton row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something | |
417 | special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will | |
418 | consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or | |
419 | { A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI | |
420 | port on pins { G4, G3, G2, G1 } of course. | |
421 | ||
422 | This way the silicon blocks present inside the chip can be multiplexed "muxed" | |
423 | out on different pin ranges. Often contemporary SoC (systems on chip) will | |
424 | contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to | |
425 | different pins by pinmux settings. | |
426 | ||
427 | Since general-purpose I/O pins (GPIO) are typically always in shortage, it is | |
428 | common to be able to use almost any pin as a GPIO pin if it is not currently | |
429 | in use by some other I/O port. | |
430 | ||
431 | ||
432 | Pinmux conventions | |
433 | ================== | |
434 | ||
435 | The purpose of the pinmux functionality in the pin controller subsystem is to | |
436 | abstract and provide pinmux settings to the devices you choose to instantiate | |
437 | in your machine configuration. It is inspired by the clk, GPIO and regulator | |
438 | subsystems, so devices will request their mux setting, but it's also possible | |
439 | to request a single pin for e.g. GPIO. | |
440 | ||
441 | Definitions: | |
442 | ||
443 | - FUNCTIONS can be switched in and out by a driver residing with the pin | |
444 | control subsystem in the drivers/pinctrl/* directory of the kernel. The | |
445 | pin control driver knows the possible functions. In the example above you can | |
446 | identify three pinmux functions, one for spi, one for i2c and one for mmc. | |
447 | ||
448 | - FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array. | |
449 | In this case the array could be something like: { spi0, i2c0, mmc0 } | |
450 | for the three available functions. | |
451 | ||
452 | - FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain | |
453 | function is *always* associated with a certain set of pin groups, could | |
454 | be just a single one, but could also be many. In the example above the | |
455 | function i2c is associated with the pins { A5, B5 }, enumerated as | |
456 | { 24, 25 } in the controller pin space. | |
457 | ||
458 | The Function spi is associated with pin groups { A8, A7, A6, A5 } | |
459 | and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and | |
460 | { 38, 46, 54, 62 } respectively. | |
461 | ||
462 | Group names must be unique per pin controller, no two groups on the same | |
463 | controller may have the same name. | |
464 | ||
465 | - The combination of a FUNCTION and a PIN GROUP determine a certain function | |
466 | for a certain set of pins. The knowledge of the functions and pin groups | |
467 | and their machine-specific particulars are kept inside the pinmux driver, | |
468 | from the outside only the enumerators are known, and the driver core can: | |
469 | ||
470 | - Request the name of a function with a certain selector (>= 0) | |
471 | - A list of groups associated with a certain function | |
472 | - Request that a certain group in that list to be activated for a certain | |
473 | function | |
474 | ||
475 | As already described above, pin groups are in turn self-descriptive, so | |
476 | the core will retrieve the actual pin range in a certain group from the | |
477 | driver. | |
478 | ||
479 | - FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain | |
480 | device by the board file, device tree or similar machine setup configuration | |
481 | mechanism, similar to how regulators are connected to devices, usually by | |
482 | name. Defining a pin controller, function and group thus uniquely identify | |
483 | the set of pins to be used by a certain device. (If only one possible group | |
484 | of pins is available for the function, no group name need to be supplied - | |
485 | the core will simply select the first and only group available.) | |
486 | ||
487 | In the example case we can define that this particular machine shall | |
488 | use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function | |
489 | fi2c0 group gi2c0, on the primary pin controller, we get mappings | |
490 | like these: | |
491 | ||
492 | { | |
493 | {"map-spi0", spi0, pinctrl0, fspi0, gspi0}, | |
494 | {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0} | |
495 | } | |
496 | ||
1681f5ae SW |
497 | Every map must be assigned a state name, pin controller, device and |
498 | function. The group is not compulsory - if it is omitted the first group | |
499 | presented by the driver as applicable for the function will be selected, | |
500 | which is useful for simple cases. | |
2744e8af LW |
501 | |
502 | It is possible to map several groups to the same combination of device, | |
503 | pin controller and function. This is for cases where a certain function on | |
504 | a certain pin controller may use different sets of pins in different | |
505 | configurations. | |
506 | ||
507 | - PINS for a certain FUNCTION using a certain PIN GROUP on a certain | |
508 | PIN CONTROLLER are provided on a first-come first-serve basis, so if some | |
509 | other device mux setting or GPIO pin request has already taken your physical | |
510 | pin, you will be denied the use of it. To get (activate) a new setting, the | |
511 | old one has to be put (deactivated) first. | |
512 | ||
513 | Sometimes the documentation and hardware registers will be oriented around | |
514 | pads (or "fingers") rather than pins - these are the soldering surfaces on the | |
515 | silicon inside the package, and may or may not match the actual number of | |
516 | pins/balls underneath the capsule. Pick some enumeration that makes sense to | |
517 | you. Define enumerators only for the pins you can control if that makes sense. | |
518 | ||
519 | Assumptions: | |
520 | ||
336cdba0 | 521 | We assume that the number of possible function maps to pin groups is limited by |
2744e8af LW |
522 | the hardware. I.e. we assume that there is no system where any function can be |
523 | mapped to any pin, like in a phone exchange. So the available pins groups for | |
524 | a certain function will be limited to a few choices (say up to eight or so), | |
525 | not hundreds or any amount of choices. This is the characteristic we have found | |
526 | by inspecting available pinmux hardware, and a necessary assumption since we | |
527 | expect pinmux drivers to present *all* possible function vs pin group mappings | |
528 | to the subsystem. | |
529 | ||
530 | ||
531 | Pinmux drivers | |
532 | ============== | |
533 | ||
534 | The pinmux core takes care of preventing conflicts on pins and calling | |
535 | the pin controller driver to execute different settings. | |
536 | ||
537 | It is the responsibility of the pinmux driver to impose further restrictions | |
538 | (say for example infer electronic limitations due to load etc) to determine | |
539 | whether or not the requested function can actually be allowed, and in case it | |
540 | is possible to perform the requested mux setting, poke the hardware so that | |
541 | this happens. | |
542 | ||
543 | Pinmux drivers are required to supply a few callback functions, some are | |
544 | optional. Usually the enable() and disable() functions are implemented, | |
545 | writing values into some certain registers to activate a certain mux setting | |
546 | for a certain pin. | |
547 | ||
548 | A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4 | |
549 | into some register named MUX to select a certain function with a certain | |
550 | group of pins would work something like this: | |
551 | ||
552 | #include <linux/pinctrl/pinctrl.h> | |
553 | #include <linux/pinctrl/pinmux.h> | |
554 | ||
555 | struct foo_group { | |
556 | const char *name; | |
557 | const unsigned int *pins; | |
558 | const unsigned num_pins; | |
559 | }; | |
560 | ||
561 | static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 }; | |
562 | static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 }; | |
563 | static const unsigned i2c0_pins[] = { 24, 25 }; | |
564 | static const unsigned mmc0_1_pins[] = { 56, 57 }; | |
565 | static const unsigned mmc0_2_pins[] = { 58, 59 }; | |
566 | static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 }; | |
567 | ||
568 | static const struct foo_group foo_groups[] = { | |
569 | { | |
570 | .name = "spi0_0_grp", | |
571 | .pins = spi0_0_pins, | |
572 | .num_pins = ARRAY_SIZE(spi0_0_pins), | |
573 | }, | |
574 | { | |
575 | .name = "spi0_1_grp", | |
576 | .pins = spi0_1_pins, | |
577 | .num_pins = ARRAY_SIZE(spi0_1_pins), | |
578 | }, | |
579 | { | |
580 | .name = "i2c0_grp", | |
581 | .pins = i2c0_pins, | |
582 | .num_pins = ARRAY_SIZE(i2c0_pins), | |
583 | }, | |
584 | { | |
585 | .name = "mmc0_1_grp", | |
586 | .pins = mmc0_1_pins, | |
587 | .num_pins = ARRAY_SIZE(mmc0_1_pins), | |
588 | }, | |
589 | { | |
590 | .name = "mmc0_2_grp", | |
591 | .pins = mmc0_2_pins, | |
592 | .num_pins = ARRAY_SIZE(mmc0_2_pins), | |
593 | }, | |
594 | { | |
595 | .name = "mmc0_3_grp", | |
596 | .pins = mmc0_3_pins, | |
597 | .num_pins = ARRAY_SIZE(mmc0_3_pins), | |
598 | }, | |
599 | }; | |
600 | ||
601 | ||
602 | static int foo_list_groups(struct pinctrl_dev *pctldev, unsigned selector) | |
603 | { | |
604 | if (selector >= ARRAY_SIZE(foo_groups)) | |
605 | return -EINVAL; | |
606 | return 0; | |
607 | } | |
608 | ||
609 | static const char *foo_get_group_name(struct pinctrl_dev *pctldev, | |
610 | unsigned selector) | |
611 | { | |
612 | return foo_groups[selector].name; | |
613 | } | |
614 | ||
615 | static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, | |
616 | unsigned ** const pins, | |
617 | unsigned * const num_pins) | |
618 | { | |
619 | *pins = (unsigned *) foo_groups[selector].pins; | |
620 | *num_pins = foo_groups[selector].num_pins; | |
621 | return 0; | |
622 | } | |
623 | ||
624 | static struct pinctrl_ops foo_pctrl_ops = { | |
625 | .list_groups = foo_list_groups, | |
626 | .get_group_name = foo_get_group_name, | |
627 | .get_group_pins = foo_get_group_pins, | |
628 | }; | |
629 | ||
630 | struct foo_pmx_func { | |
631 | const char *name; | |
632 | const char * const *groups; | |
633 | const unsigned num_groups; | |
634 | }; | |
635 | ||
636 | static const char * const spi0_groups[] = { "spi0_1_grp" }; | |
637 | static const char * const i2c0_groups[] = { "i2c0_grp" }; | |
638 | static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", | |
639 | "mmc0_3_grp" }; | |
640 | ||
641 | static const struct foo_pmx_func foo_functions[] = { | |
642 | { | |
643 | .name = "spi0", | |
644 | .groups = spi0_groups, | |
645 | .num_groups = ARRAY_SIZE(spi0_groups), | |
646 | }, | |
647 | { | |
648 | .name = "i2c0", | |
649 | .groups = i2c0_groups, | |
650 | .num_groups = ARRAY_SIZE(i2c0_groups), | |
651 | }, | |
652 | { | |
653 | .name = "mmc0", | |
654 | .groups = mmc0_groups, | |
655 | .num_groups = ARRAY_SIZE(mmc0_groups), | |
656 | }, | |
657 | }; | |
658 | ||
659 | int foo_list_funcs(struct pinctrl_dev *pctldev, unsigned selector) | |
660 | { | |
661 | if (selector >= ARRAY_SIZE(foo_functions)) | |
662 | return -EINVAL; | |
663 | return 0; | |
664 | } | |
665 | ||
666 | const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector) | |
667 | { | |
336cdba0 | 668 | return foo_functions[selector].name; |
2744e8af LW |
669 | } |
670 | ||
671 | static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector, | |
672 | const char * const **groups, | |
673 | unsigned * const num_groups) | |
674 | { | |
675 | *groups = foo_functions[selector].groups; | |
676 | *num_groups = foo_functions[selector].num_groups; | |
677 | return 0; | |
678 | } | |
679 | ||
680 | int foo_enable(struct pinctrl_dev *pctldev, unsigned selector, | |
681 | unsigned group) | |
682 | { | |
336cdba0 | 683 | u8 regbit = (1 << selector + group); |
2744e8af LW |
684 | |
685 | writeb((readb(MUX)|regbit), MUX) | |
686 | return 0; | |
687 | } | |
688 | ||
336cdba0 | 689 | void foo_disable(struct pinctrl_dev *pctldev, unsigned selector, |
2744e8af LW |
690 | unsigned group) |
691 | { | |
336cdba0 | 692 | u8 regbit = (1 << selector + group); |
2744e8af LW |
693 | |
694 | writeb((readb(MUX) & ~(regbit)), MUX) | |
695 | return 0; | |
696 | } | |
697 | ||
698 | struct pinmux_ops foo_pmxops = { | |
699 | .list_functions = foo_list_funcs, | |
700 | .get_function_name = foo_get_fname, | |
701 | .get_function_groups = foo_get_groups, | |
702 | .enable = foo_enable, | |
703 | .disable = foo_disable, | |
704 | }; | |
705 | ||
706 | /* Pinmux operations are handled by some pin controller */ | |
707 | static struct pinctrl_desc foo_desc = { | |
708 | ... | |
709 | .pctlops = &foo_pctrl_ops, | |
710 | .pmxops = &foo_pmxops, | |
711 | }; | |
712 | ||
713 | In the example activating muxing 0 and 1 at the same time setting bits | |
714 | 0 and 1, uses one pin in common so they would collide. | |
715 | ||
716 | The beauty of the pinmux subsystem is that since it keeps track of all | |
717 | pins and who is using them, it will already have denied an impossible | |
718 | request like that, so the driver does not need to worry about such | |
719 | things - when it gets a selector passed in, the pinmux subsystem makes | |
720 | sure no other device or GPIO assignment is already using the selected | |
721 | pins. Thus bits 0 and 1 in the control register will never be set at the | |
722 | same time. | |
723 | ||
724 | All the above functions are mandatory to implement for a pinmux driver. | |
725 | ||
726 | ||
e93bcee0 LW |
727 | Pin control interaction with the GPIO subsystem |
728 | =============================================== | |
2744e8af | 729 | |
e93bcee0 LW |
730 | The public pinmux API contains two functions named pinctrl_request_gpio() |
731 | and pinctrl_free_gpio(). These two functions shall *ONLY* be called from | |
542e704f | 732 | gpiolib-based drivers as part of their gpio_request() and |
e93bcee0 | 733 | gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output] |
542e704f LW |
734 | shall only be called from within respective gpio_direction_[input|output] |
735 | gpiolib implementation. | |
736 | ||
737 | NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be | |
e93bcee0 LW |
738 | controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have |
739 | that driver request proper muxing and other control for its pins. | |
542e704f | 740 | |
2744e8af LW |
741 | The function list could become long, especially if you can convert every |
742 | individual pin into a GPIO pin independent of any other pins, and then try | |
743 | the approach to define every pin as a function. | |
744 | ||
745 | In this case, the function array would become 64 entries for each GPIO | |
746 | setting and then the device functions. | |
747 | ||
e93bcee0 | 748 | For this reason there are two functions a pin control driver can implement |
542e704f LW |
749 | to enable only GPIO on an individual pin: .gpio_request_enable() and |
750 | .gpio_disable_free(). | |
2744e8af LW |
751 | |
752 | This function will pass in the affected GPIO range identified by the pin | |
753 | controller core, so you know which GPIO pins are being affected by the request | |
754 | operation. | |
755 | ||
542e704f LW |
756 | If your driver needs to have an indication from the framework of whether the |
757 | GPIO pin shall be used for input or output you can implement the | |
758 | .gpio_set_direction() function. As described this shall be called from the | |
759 | gpiolib driver and the affected GPIO range, pin offset and desired direction | |
760 | will be passed along to this function. | |
761 | ||
762 | Alternatively to using these special functions, it is fully allowed to use | |
e93bcee0 | 763 | named functions for each GPIO pin, the pinctrl_request_gpio() will attempt to |
542e704f LW |
764 | obtain the function "gpioN" where "N" is the global GPIO pin number if no |
765 | special GPIO-handler is registered. | |
2744e8af LW |
766 | |
767 | ||
768 | Pinmux board/machine configuration | |
769 | ================================== | |
770 | ||
771 | Boards and machines define how a certain complete running system is put | |
772 | together, including how GPIOs and devices are muxed, how regulators are | |
773 | constrained and how the clock tree looks. Of course pinmux settings are also | |
774 | part of this. | |
775 | ||
776 | A pinmux config for a machine looks pretty much like a simple regulator | |
777 | configuration, so for the example array above we want to enable i2c and | |
778 | spi on the second function mapping: | |
779 | ||
780 | #include <linux/pinctrl/machine.h> | |
781 | ||
e93bcee0 | 782 | static const struct pinctrl_map __initdata mapping[] = { |
2744e8af | 783 | { |
806d3143 | 784 | .dev_name = "foo-spi.0", |
110e4ec5 | 785 | .name = PINCTRL_STATE_DEFAULT, |
51cd24ee | 786 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 787 | .function = "spi0", |
2744e8af LW |
788 | }, |
789 | { | |
806d3143 | 790 | .dev_name = "foo-i2c.0", |
110e4ec5 | 791 | .name = PINCTRL_STATE_DEFAULT, |
51cd24ee | 792 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 793 | .function = "i2c0", |
2744e8af LW |
794 | }, |
795 | { | |
806d3143 | 796 | .dev_name = "foo-mmc.0", |
110e4ec5 | 797 | .name = PINCTRL_STATE_DEFAULT, |
51cd24ee | 798 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 799 | .function = "mmc0", |
2744e8af LW |
800 | }, |
801 | }; | |
802 | ||
803 | The dev_name here matches to the unique device name that can be used to look | |
804 | up the device struct (just like with clockdev or regulators). The function name | |
805 | must match a function provided by the pinmux driver handling this pin range. | |
806 | ||
807 | As you can see we may have several pin controllers on the system and thus | |
808 | we need to specify which one of them that contain the functions we wish | |
9dfac4fd | 809 | to map. |
2744e8af LW |
810 | |
811 | You register this pinmux mapping to the pinmux subsystem by simply: | |
812 | ||
e93bcee0 | 813 | ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping)); |
2744e8af LW |
814 | |
815 | Since the above construct is pretty common there is a helper macro to make | |
51cd24ee | 816 | it even more compact which assumes you want to use pinctrl-foo and position |
2744e8af LW |
817 | 0 for mapping, for example: |
818 | ||
e93bcee0 | 819 | static struct pinctrl_map __initdata mapping[] = { |
46919ae6 | 820 | PIN_MAP(PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "foo-i2c.0"), |
2744e8af LW |
821 | }; |
822 | ||
823 | ||
824 | Complex mappings | |
825 | ================ | |
826 | ||
827 | As it is possible to map a function to different groups of pins an optional | |
828 | .group can be specified like this: | |
829 | ||
830 | ... | |
831 | { | |
806d3143 | 832 | .dev_name = "foo-spi.0", |
2744e8af | 833 | .name = "spi0-pos-A", |
51cd24ee | 834 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af LW |
835 | .function = "spi0", |
836 | .group = "spi0_0_grp", | |
2744e8af LW |
837 | }, |
838 | { | |
806d3143 | 839 | .dev_name = "foo-spi.0", |
2744e8af | 840 | .name = "spi0-pos-B", |
51cd24ee | 841 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af LW |
842 | .function = "spi0", |
843 | .group = "spi0_1_grp", | |
2744e8af LW |
844 | }, |
845 | ... | |
846 | ||
847 | This example mapping is used to switch between two positions for spi0 at | |
848 | runtime, as described further below under the heading "Runtime pinmuxing". | |
849 | ||
850 | Further it is possible to match several groups of pins to the same function | |
851 | for a single device, say for example in the mmc0 example above, where you can | |
852 | additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all | |
853 | three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the | |
854 | case), we define a mapping like this: | |
855 | ||
856 | ... | |
857 | { | |
806d3143 | 858 | .dev_name = "foo-mmc.0", |
f54367f9 | 859 | .name = "2bit" |
51cd24ee | 860 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 861 | .function = "mmc0", |
336cdba0 | 862 | .group = "mmc0_1_grp", |
2744e8af LW |
863 | }, |
864 | { | |
806d3143 | 865 | .dev_name = "foo-mmc.0", |
f54367f9 | 866 | .name = "4bit" |
51cd24ee | 867 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 868 | .function = "mmc0", |
336cdba0 | 869 | .group = "mmc0_1_grp", |
2744e8af LW |
870 | }, |
871 | { | |
806d3143 | 872 | .dev_name = "foo-mmc.0", |
f54367f9 | 873 | .name = "4bit" |
51cd24ee | 874 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 875 | .function = "mmc0", |
336cdba0 | 876 | .group = "mmc0_2_grp", |
2744e8af LW |
877 | }, |
878 | { | |
806d3143 | 879 | .dev_name = "foo-mmc.0", |
f54367f9 | 880 | .name = "8bit" |
51cd24ee | 881 | .ctrl_dev_name = "pinctrl-foo", |
336cdba0 | 882 | .group = "mmc0_1_grp", |
2744e8af LW |
883 | }, |
884 | { | |
806d3143 | 885 | .dev_name = "foo-mmc.0", |
f54367f9 | 886 | .name = "8bit" |
51cd24ee | 887 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 888 | .function = "mmc0", |
336cdba0 | 889 | .group = "mmc0_2_grp", |
2744e8af LW |
890 | }, |
891 | { | |
806d3143 | 892 | .dev_name = "foo-mmc.0", |
f54367f9 | 893 | .name = "8bit" |
51cd24ee | 894 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 895 | .function = "mmc0", |
336cdba0 | 896 | .group = "mmc0_3_grp", |
2744e8af LW |
897 | }, |
898 | ... | |
899 | ||
900 | The result of grabbing this mapping from the device with something like | |
901 | this (see next paragraph): | |
902 | ||
e93bcee0 | 903 | p = pinctrl_get(&device, "8bit"); |
2744e8af LW |
904 | |
905 | Will be that you activate all the three bottom records in the mapping at | |
906 | once. Since they share the same name, pin controller device, funcion and | |
907 | device, and since we allow multiple groups to match to a single device, they | |
908 | all get selected, and they all get enabled and disable simultaneously by the | |
909 | pinmux core. | |
910 | ||
911 | ||
912 | Pinmux requests from drivers | |
913 | ============================ | |
914 | ||
e93bcee0 LW |
915 | Generally it is discouraged to let individual drivers get and enable pin |
916 | control. So if possible, handle the pin control in platform code or some other | |
917 | place where you have access to all the affected struct device * pointers. In | |
918 | some cases where a driver needs to e.g. switch between different mux mappings | |
919 | at runtime this is not possible. | |
2744e8af | 920 | |
e93bcee0 LW |
921 | A driver may request a certain control state to be activated, usually just the |
922 | default state like this: | |
2744e8af | 923 | |
28a8d14c | 924 | #include <linux/pinctrl/consumer.h> |
2744e8af LW |
925 | |
926 | struct foo_state { | |
e93bcee0 | 927 | struct pinctrl *p; |
2744e8af LW |
928 | ... |
929 | }; | |
930 | ||
931 | foo_probe() | |
932 | { | |
933 | /* Allocate a state holder named "state" etc */ | |
e93bcee0 | 934 | struct pinctrl p; |
2744e8af | 935 | |
46919ae6 | 936 | p = pinctrl_get(&device, PINCTRL_STATE_DEFAULT); |
e93bcee0 LW |
937 | if IS_ERR(p) |
938 | return PTR_ERR(p); | |
939 | pinctrl_enable(p); | |
2744e8af | 940 | |
e93bcee0 | 941 | state->p = p; |
2744e8af LW |
942 | } |
943 | ||
944 | foo_remove() | |
945 | { | |
e93bcee0 LW |
946 | pinctrl_disable(state->p); |
947 | pinctrl_put(state->p); | |
2744e8af LW |
948 | } |
949 | ||
2744e8af LW |
950 | This get/enable/disable/put sequence can just as well be handled by bus drivers |
951 | if you don't want each and every driver to handle it and you know the | |
952 | arrangement on your bus. | |
953 | ||
954 | The semantics of the get/enable respective disable/put is as follows: | |
955 | ||
e93bcee0 | 956 | - pinctrl_get() is called in process context to reserve the pins affected with |
2744e8af LW |
957 | a certain mapping and set up the pinmux core and the driver. It will allocate |
958 | a struct from the kernel memory to hold the pinmux state. | |
959 | ||
e93bcee0 | 960 | - pinctrl_enable()/pinctrl_disable() is quick and can be called from fastpath |
2744e8af LW |
961 | (irq context) when you quickly want to set up/tear down the hardware muxing |
962 | when running a device driver. Usually it will just poke some values into a | |
963 | register. | |
964 | ||
e93bcee0 LW |
965 | - pinctrl_disable() is called in process context to tear down the pin requests |
966 | and release the state holder struct for the mux setting etc. | |
2744e8af | 967 | |
e93bcee0 LW |
968 | Usually the pin control core handled the get/put pair and call out to the |
969 | device drivers bookkeeping operations, like checking available functions and | |
970 | the associated pins, whereas the enable/disable pass on to the pin controller | |
2744e8af LW |
971 | driver which takes care of activating and/or deactivating the mux setting by |
972 | quickly poking some registers. | |
973 | ||
e93bcee0 | 974 | The pins are allocated for your device when you issue the pinctrl_get() call, |
2744e8af LW |
975 | after this you should be able to see this in the debugfs listing of all pins. |
976 | ||
977 | ||
e93bcee0 LW |
978 | System pin control hogging |
979 | ========================== | |
2744e8af | 980 | |
1681f5ae | 981 | Pin control map entries can be hogged by the core when the pin controller |
e93bcee0 LW |
982 | is registered. This means that the core will attempt to call pinctrl_get() and |
983 | pinctrl_enable() on it immediately after the pin control device has been | |
2744e8af LW |
984 | registered. |
985 | ||
77a59883 LW |
986 | This is enabled by simply setting the .dev_name field in the map to the name |
987 | of the pin controller itself, like this: | |
2744e8af LW |
988 | |
989 | { | |
806d3143 | 990 | .dev_name = "pinctrl-foo", |
46919ae6 | 991 | .name = PINCTRL_STATE_DEFAULT, |
51cd24ee | 992 | .ctrl_dev_name = "pinctrl-foo", |
2744e8af | 993 | .function = "power_func", |
2744e8af LW |
994 | }, |
995 | ||
996 | Since it may be common to request the core to hog a few always-applicable | |
997 | mux settings on the primary pin controller, there is a convenience macro for | |
998 | this: | |
999 | ||
46919ae6 | 1000 | PIN_MAP_SYS_HOG("pinctrl-foo", "power_func") |
2744e8af LW |
1001 | |
1002 | This gives the exact same result as the above construction. | |
1003 | ||
1004 | ||
1005 | Runtime pinmuxing | |
1006 | ================= | |
1007 | ||
1008 | It is possible to mux a certain function in and out at runtime, say to move | |
1009 | an SPI port from one set of pins to another set of pins. Say for example for | |
1010 | spi0 in the example above, we expose two different groups of pins for the same | |
1011 | function, but with different named in the mapping as described under | |
1012 | "Advanced mapping" above. So we have two mappings named "spi0-pos-A" and | |
1013 | "spi0-pos-B". | |
1014 | ||
1015 | This snippet first muxes the function in the pins defined by group A, enables | |
1016 | it, disables and releases it, and muxes it in on the pins defined by group B: | |
1017 | ||
28a8d14c LW |
1018 | #include <linux/pinctrl/consumer.h> |
1019 | ||
2744e8af LW |
1020 | foo_switch() |
1021 | { | |
e93bcee0 | 1022 | struct pinctrl *p; |
2744e8af LW |
1023 | |
1024 | /* Enable on position A */ | |
e93bcee0 LW |
1025 | p = pinctrl_get(&device, "spi0-pos-A"); |
1026 | if IS_ERR(p) | |
1027 | return PTR_ERR(p); | |
1028 | pinctrl_enable(p); | |
2744e8af LW |
1029 | |
1030 | /* This releases the pins again */ | |
e93bcee0 LW |
1031 | pinctrl_disable(p); |
1032 | pinctrl_put(p); | |
2744e8af LW |
1033 | |
1034 | /* Enable on position B */ | |
e93bcee0 LW |
1035 | p = pinctrl_get(&device, "spi0-pos-B"); |
1036 | if IS_ERR(p) | |
1037 | return PTR_ERR(p); | |
1038 | pinctrl_enable(p); | |
2744e8af LW |
1039 | ... |
1040 | } | |
1041 | ||
1042 | The above has to be done from process context. |