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