Root/
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 | - 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. |
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 | |
32 | When a PIN CONTROLLER is instantiated, it will register a descriptor to the |
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 | |
61 | const struct pinctrl_pin_desc foo_pins[] = { |
62 | PINCTRL_PIN(0, "A8"), |
63 | PINCTRL_PIN(1, "B8"), |
64 | PINCTRL_PIN(2, "C8"), |
65 | ... |
66 | PINCTRL_PIN(61, "F1"), |
67 | PINCTRL_PIN(62, "G1"), |
68 | PINCTRL_PIN(63, "H1"), |
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 | |
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 | |
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 |
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 |
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 | |
138 | static const unsigned int spi0_pins[] = { 0, 8, 16, 24 }; |
139 | static const unsigned int i2c0_pins[] = { 24, 25 }; |
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 | |
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 | Pin configuration can be programmed either using the explicit APIs described |
210 | immediately below, or by adding configuration entries into the mapping table; |
211 | see section "Board/machine configuration" below. |
212 | |
213 | For example, a platform may do the following to pull up a pin to VDD: |
214 | |
215 | #include <linux/pinctrl/consumer.h> |
216 | |
217 | ret = pin_config_set("foo-dev", "FOO_GPIO_PIN", PLATFORM_X_PULL_UP); |
218 | |
219 | The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP |
220 | above, is entirely defined by the pin controller driver. |
221 | |
222 | The pin configuration driver implements callbacks for changing pin |
223 | configuration in the pin controller ops like this: |
224 | |
225 | #include <linux/pinctrl/pinctrl.h> |
226 | #include <linux/pinctrl/pinconf.h> |
227 | #include "platform_x_pindefs.h" |
228 | |
229 | static int foo_pin_config_get(struct pinctrl_dev *pctldev, |
230 | unsigned offset, |
231 | unsigned long *config) |
232 | { |
233 | struct my_conftype conf; |
234 | |
235 | ... Find setting for pin @ offset ... |
236 | |
237 | *config = (unsigned long) conf; |
238 | } |
239 | |
240 | static int foo_pin_config_set(struct pinctrl_dev *pctldev, |
241 | unsigned offset, |
242 | unsigned long config) |
243 | { |
244 | struct my_conftype *conf = (struct my_conftype *) config; |
245 | |
246 | switch (conf) { |
247 | case PLATFORM_X_PULL_UP: |
248 | ... |
249 | } |
250 | } |
251 | } |
252 | |
253 | static int foo_pin_config_group_get (struct pinctrl_dev *pctldev, |
254 | unsigned selector, |
255 | unsigned long *config) |
256 | { |
257 | ... |
258 | } |
259 | |
260 | static int foo_pin_config_group_set (struct pinctrl_dev *pctldev, |
261 | unsigned selector, |
262 | unsigned long config) |
263 | { |
264 | ... |
265 | } |
266 | |
267 | static struct pinconf_ops foo_pconf_ops = { |
268 | .pin_config_get = foo_pin_config_get, |
269 | .pin_config_set = foo_pin_config_set, |
270 | .pin_config_group_get = foo_pin_config_group_get, |
271 | .pin_config_group_set = foo_pin_config_group_set, |
272 | }; |
273 | |
274 | /* Pin config operations are handled by some pin controller */ |
275 | static struct pinctrl_desc foo_desc = { |
276 | ... |
277 | .confops = &foo_pconf_ops, |
278 | }; |
279 | |
280 | Since some controllers have special logic for handling entire groups of pins |
281 | they can exploit the special whole-group pin control function. The |
282 | pin_config_group_set() callback is allowed to return the error code -EAGAIN, |
283 | for groups it does not want to handle, or if it just wants to do some |
284 | group-level handling and then fall through to iterate over all pins, in which |
285 | case each individual pin will be treated by separate pin_config_set() calls as |
286 | well. |
287 | |
288 | |
289 | Interaction with the GPIO subsystem |
290 | =================================== |
291 | |
292 | The GPIO drivers may want to perform operations of various types on the same |
293 | physical pins that are also registered as pin controller pins. |
294 | |
295 | Since the pin controller subsystem have its pinspace local to the pin |
296 | controller we need a mapping so that the pin control subsystem can figure out |
297 | which pin controller handles control of a certain GPIO pin. Since a single |
298 | pin controller may be muxing several GPIO ranges (typically SoCs that have |
299 | one set of pins but internally several GPIO silicon blocks, each modeled as |
300 | a struct gpio_chip) any number of GPIO ranges can be added to a pin controller |
301 | instance like this: |
302 | |
303 | struct gpio_chip chip_a; |
304 | struct gpio_chip chip_b; |
305 | |
306 | static struct pinctrl_gpio_range gpio_range_a = { |
307 | .name = "chip a", |
308 | .id = 0, |
309 | .base = 32, |
310 | .pin_base = 32, |
311 | .npins = 16, |
312 | .gc = &chip_a; |
313 | }; |
314 | |
315 | static struct pinctrl_gpio_range gpio_range_b = { |
316 | .name = "chip b", |
317 | .id = 0, |
318 | .base = 48, |
319 | .pin_base = 64, |
320 | .npins = 8, |
321 | .gc = &chip_b; |
322 | }; |
323 | |
324 | { |
325 | struct pinctrl_dev *pctl; |
326 | ... |
327 | pinctrl_add_gpio_range(pctl, &gpio_range_a); |
328 | pinctrl_add_gpio_range(pctl, &gpio_range_b); |
329 | } |
330 | |
331 | So this complex system has one pin controller handling two different |
332 | GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and |
333 | "chip b" have different .pin_base, which means a start pin number of the |
334 | GPIO range. |
335 | |
336 | The GPIO range of "chip a" starts from the GPIO base of 32 and actual |
337 | pin range also starts from 32. However "chip b" has different starting |
338 | offset for the GPIO range and pin range. The GPIO range of "chip b" starts |
339 | from GPIO number 48, while the pin range of "chip b" starts from 64. |
340 | |
341 | We can convert a gpio number to actual pin number using this "pin_base". |
342 | They are mapped in the global GPIO pin space at: |
343 | |
344 | chip a: |
345 | - GPIO range : [32 .. 47] |
346 | - pin range : [32 .. 47] |
347 | chip b: |
348 | - GPIO range : [48 .. 55] |
349 | - pin range : [64 .. 71] |
350 | |
351 | When GPIO-specific functions in the pin control subsystem are called, these |
352 | ranges will be used to look up the appropriate pin controller by inspecting |
353 | and matching the pin to the pin ranges across all controllers. When a |
354 | pin controller handling the matching range is found, GPIO-specific functions |
355 | will be called on that specific pin controller. |
356 | |
357 | For all functionalities dealing with pin biasing, pin muxing etc, the pin |
358 | controller subsystem will subtract the range's .base offset from the passed |
359 | in gpio number, and add the ranges's .pin_base offset to retrive a pin number. |
360 | After that, the subsystem passes it on to the pin control driver, so the driver |
361 | will get an pin number into its handled number range. Further it is also passed |
362 | the range ID value, so that the pin controller knows which range it should |
363 | deal with. |
364 | |
365 | PINMUX interfaces |
366 | ================= |
367 | |
368 | These calls use the pinmux_* naming prefix. No other calls should use that |
369 | prefix. |
370 | |
371 | |
372 | What is pinmuxing? |
373 | ================== |
374 | |
375 | PINMUX, also known as padmux, ballmux, alternate functions or mission modes |
376 | is a way for chip vendors producing some kind of electrical packages to use |
377 | a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive |
378 | functions, depending on the application. By "application" in this context |
379 | we usually mean a way of soldering or wiring the package into an electronic |
380 | system, even though the framework makes it possible to also change the function |
381 | at runtime. |
382 | |
383 | Here is an example of a PGA (Pin Grid Array) chip seen from underneath: |
384 | |
385 | A B C D E F G H |
386 | +---+ |
387 | 8 | o | o o o o o o o |
388 | | | |
389 | 7 | o | o o o o o o o |
390 | | | |
391 | 6 | o | o o o o o o o |
392 | +---+---+ |
393 | 5 | o | o | o o o o o o |
394 | +---+---+ +---+ |
395 | 4 o o o o o o | o | o |
396 | | | |
397 | 3 o o o o o o | o | o |
398 | | | |
399 | 2 o o o o o o | o | o |
400 | +-------+-------+-------+---+---+ |
401 | 1 | o o | o o | o o | o | o | |
402 | +-------+-------+-------+---+---+ |
403 | |
404 | This is not tetris. The game to think of is chess. Not all PGA/BGA packages |
405 | are chessboard-like, big ones have "holes" in some arrangement according to |
406 | different design patterns, but we're using this as a simple example. Of the |
407 | pins you see some will be taken by things like a few VCC and GND to feed power |
408 | to the chip, and quite a few will be taken by large ports like an external |
409 | memory interface. The remaining pins will often be subject to pin multiplexing. |
410 | |
411 | The example 8x8 PGA package above will have pin numbers 0 thru 63 assigned to |
412 | its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using |
413 | pinctrl_register_pins() and a suitable data set as shown earlier. |
414 | |
415 | In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port |
416 | (these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as |
417 | some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can |
418 | be used as an I2C port (these are just two pins: SCL, SDA). Needless to say, |
419 | we cannot use the SPI port and I2C port at the same time. However in the inside |
420 | of the package the silicon performing the SPI logic can alternatively be routed |
421 | out on pins { G4, G3, G2, G1 }. |
422 | |
423 | On the botton row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something |
424 | special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will |
425 | consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or |
426 | { A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI |
427 | port on pins { G4, G3, G2, G1 } of course. |
428 | |
429 | This way the silicon blocks present inside the chip can be multiplexed "muxed" |
430 | out on different pin ranges. Often contemporary SoC (systems on chip) will |
431 | contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to |
432 | different pins by pinmux settings. |
433 | |
434 | Since general-purpose I/O pins (GPIO) are typically always in shortage, it is |
435 | common to be able to use almost any pin as a GPIO pin if it is not currently |
436 | in use by some other I/O port. |
437 | |
438 | |
439 | Pinmux conventions |
440 | ================== |
441 | |
442 | The purpose of the pinmux functionality in the pin controller subsystem is to |
443 | abstract and provide pinmux settings to the devices you choose to instantiate |
444 | in your machine configuration. It is inspired by the clk, GPIO and regulator |
445 | subsystems, so devices will request their mux setting, but it's also possible |
446 | to request a single pin for e.g. GPIO. |
447 | |
448 | Definitions: |
449 | |
450 | - FUNCTIONS can be switched in and out by a driver residing with the pin |
451 | control subsystem in the drivers/pinctrl/* directory of the kernel. The |
452 | pin control driver knows the possible functions. In the example above you can |
453 | identify three pinmux functions, one for spi, one for i2c and one for mmc. |
454 | |
455 | - FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array. |
456 | In this case the array could be something like: { spi0, i2c0, mmc0 } |
457 | for the three available functions. |
458 | |
459 | - FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain |
460 | function is *always* associated with a certain set of pin groups, could |
461 | be just a single one, but could also be many. In the example above the |
462 | function i2c is associated with the pins { A5, B5 }, enumerated as |
463 | { 24, 25 } in the controller pin space. |
464 | |
465 | The Function spi is associated with pin groups { A8, A7, A6, A5 } |
466 | and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and |
467 | { 38, 46, 54, 62 } respectively. |
468 | |
469 | Group names must be unique per pin controller, no two groups on the same |
470 | controller may have the same name. |
471 | |
472 | - The combination of a FUNCTION and a PIN GROUP determine a certain function |
473 | for a certain set of pins. The knowledge of the functions and pin groups |
474 | and their machine-specific particulars are kept inside the pinmux driver, |
475 | from the outside only the enumerators are known, and the driver core can: |
476 | |
477 | - Request the name of a function with a certain selector (>= 0) |
478 | - A list of groups associated with a certain function |
479 | - Request that a certain group in that list to be activated for a certain |
480 | function |
481 | |
482 | As already described above, pin groups are in turn self-descriptive, so |
483 | the core will retrieve the actual pin range in a certain group from the |
484 | driver. |
485 | |
486 | - FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain |
487 | device by the board file, device tree or similar machine setup configuration |
488 | mechanism, similar to how regulators are connected to devices, usually by |
489 | name. Defining a pin controller, function and group thus uniquely identify |
490 | the set of pins to be used by a certain device. (If only one possible group |
491 | of pins is available for the function, no group name need to be supplied - |
492 | the core will simply select the first and only group available.) |
493 | |
494 | In the example case we can define that this particular machine shall |
495 | use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function |
496 | fi2c0 group gi2c0, on the primary pin controller, we get mappings |
497 | like these: |
498 | |
499 | { |
500 | {"map-spi0", spi0, pinctrl0, fspi0, gspi0}, |
501 | {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0} |
502 | } |
503 | |
504 | Every map must be assigned a state name, pin controller, device and |
505 | function. The group is not compulsory - if it is omitted the first group |
506 | presented by the driver as applicable for the function will be selected, |
507 | which is useful for simple cases. |
508 | |
509 | It is possible to map several groups to the same combination of device, |
510 | pin controller and function. This is for cases where a certain function on |
511 | a certain pin controller may use different sets of pins in different |
512 | configurations. |
513 | |
514 | - PINS for a certain FUNCTION using a certain PIN GROUP on a certain |
515 | PIN CONTROLLER are provided on a first-come first-serve basis, so if some |
516 | other device mux setting or GPIO pin request has already taken your physical |
517 | pin, you will be denied the use of it. To get (activate) a new setting, the |
518 | old one has to be put (deactivated) first. |
519 | |
520 | Sometimes the documentation and hardware registers will be oriented around |
521 | pads (or "fingers") rather than pins - these are the soldering surfaces on the |
522 | silicon inside the package, and may or may not match the actual number of |
523 | pins/balls underneath the capsule. Pick some enumeration that makes sense to |
524 | you. Define enumerators only for the pins you can control if that makes sense. |
525 | |
526 | Assumptions: |
527 | |
528 | We assume that the number of possible function maps to pin groups is limited by |
529 | the hardware. I.e. we assume that there is no system where any function can be |
530 | mapped to any pin, like in a phone exchange. So the available pins groups for |
531 | a certain function will be limited to a few choices (say up to eight or so), |
532 | not hundreds or any amount of choices. This is the characteristic we have found |
533 | by inspecting available pinmux hardware, and a necessary assumption since we |
534 | expect pinmux drivers to present *all* possible function vs pin group mappings |
535 | to the subsystem. |
536 | |
537 | |
538 | Pinmux drivers |
539 | ============== |
540 | |
541 | The pinmux core takes care of preventing conflicts on pins and calling |
542 | the pin controller driver to execute different settings. |
543 | |
544 | It is the responsibility of the pinmux driver to impose further restrictions |
545 | (say for example infer electronic limitations due to load etc) to determine |
546 | whether or not the requested function can actually be allowed, and in case it |
547 | is possible to perform the requested mux setting, poke the hardware so that |
548 | this happens. |
549 | |
550 | Pinmux drivers are required to supply a few callback functions, some are |
551 | optional. Usually the enable() and disable() functions are implemented, |
552 | writing values into some certain registers to activate a certain mux setting |
553 | for a certain pin. |
554 | |
555 | A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4 |
556 | into some register named MUX to select a certain function with a certain |
557 | group of pins would work something like this: |
558 | |
559 | #include <linux/pinctrl/pinctrl.h> |
560 | #include <linux/pinctrl/pinmux.h> |
561 | |
562 | struct foo_group { |
563 | const char *name; |
564 | const unsigned int *pins; |
565 | const unsigned num_pins; |
566 | }; |
567 | |
568 | static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 }; |
569 | static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 }; |
570 | static const unsigned i2c0_pins[] = { 24, 25 }; |
571 | static const unsigned mmc0_1_pins[] = { 56, 57 }; |
572 | static const unsigned mmc0_2_pins[] = { 58, 59 }; |
573 | static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 }; |
574 | |
575 | static const struct foo_group foo_groups[] = { |
576 | { |
577 | .name = "spi0_0_grp", |
578 | .pins = spi0_0_pins, |
579 | .num_pins = ARRAY_SIZE(spi0_0_pins), |
580 | }, |
581 | { |
582 | .name = "spi0_1_grp", |
583 | .pins = spi0_1_pins, |
584 | .num_pins = ARRAY_SIZE(spi0_1_pins), |
585 | }, |
586 | { |
587 | .name = "i2c0_grp", |
588 | .pins = i2c0_pins, |
589 | .num_pins = ARRAY_SIZE(i2c0_pins), |
590 | }, |
591 | { |
592 | .name = "mmc0_1_grp", |
593 | .pins = mmc0_1_pins, |
594 | .num_pins = ARRAY_SIZE(mmc0_1_pins), |
595 | }, |
596 | { |
597 | .name = "mmc0_2_grp", |
598 | .pins = mmc0_2_pins, |
599 | .num_pins = ARRAY_SIZE(mmc0_2_pins), |
600 | }, |
601 | { |
602 | .name = "mmc0_3_grp", |
603 | .pins = mmc0_3_pins, |
604 | .num_pins = ARRAY_SIZE(mmc0_3_pins), |
605 | }, |
606 | }; |
607 | |
608 | |
609 | static int foo_list_groups(struct pinctrl_dev *pctldev, unsigned selector) |
610 | { |
611 | if (selector >= ARRAY_SIZE(foo_groups)) |
612 | return -EINVAL; |
613 | return 0; |
614 | } |
615 | |
616 | static const char *foo_get_group_name(struct pinctrl_dev *pctldev, |
617 | unsigned selector) |
618 | { |
619 | return foo_groups[selector].name; |
620 | } |
621 | |
622 | static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector, |
623 | unsigned ** const pins, |
624 | unsigned * const num_pins) |
625 | { |
626 | *pins = (unsigned *) foo_groups[selector].pins; |
627 | *num_pins = foo_groups[selector].num_pins; |
628 | return 0; |
629 | } |
630 | |
631 | static struct pinctrl_ops foo_pctrl_ops = { |
632 | .list_groups = foo_list_groups, |
633 | .get_group_name = foo_get_group_name, |
634 | .get_group_pins = foo_get_group_pins, |
635 | }; |
636 | |
637 | struct foo_pmx_func { |
638 | const char *name; |
639 | const char * const *groups; |
640 | const unsigned num_groups; |
641 | }; |
642 | |
643 | static const char * const spi0_groups[] = { "spi0_1_grp" }; |
644 | static const char * const i2c0_groups[] = { "i2c0_grp" }; |
645 | static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", |
646 | "mmc0_3_grp" }; |
647 | |
648 | static const struct foo_pmx_func foo_functions[] = { |
649 | { |
650 | .name = "spi0", |
651 | .groups = spi0_groups, |
652 | .num_groups = ARRAY_SIZE(spi0_groups), |
653 | }, |
654 | { |
655 | .name = "i2c0", |
656 | .groups = i2c0_groups, |
657 | .num_groups = ARRAY_SIZE(i2c0_groups), |
658 | }, |
659 | { |
660 | .name = "mmc0", |
661 | .groups = mmc0_groups, |
662 | .num_groups = ARRAY_SIZE(mmc0_groups), |
663 | }, |
664 | }; |
665 | |
666 | int foo_list_funcs(struct pinctrl_dev *pctldev, unsigned selector) |
667 | { |
668 | if (selector >= ARRAY_SIZE(foo_functions)) |
669 | return -EINVAL; |
670 | return 0; |
671 | } |
672 | |
673 | const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector) |
674 | { |
675 | return foo_functions[selector].name; |
676 | } |
677 | |
678 | static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector, |
679 | const char * const **groups, |
680 | unsigned * const num_groups) |
681 | { |
682 | *groups = foo_functions[selector].groups; |
683 | *num_groups = foo_functions[selector].num_groups; |
684 | return 0; |
685 | } |
686 | |
687 | int foo_enable(struct pinctrl_dev *pctldev, unsigned selector, |
688 | unsigned group) |
689 | { |
690 | u8 regbit = (1 << selector + group); |
691 | |
692 | writeb((readb(MUX)|regbit), MUX) |
693 | return 0; |
694 | } |
695 | |
696 | void foo_disable(struct pinctrl_dev *pctldev, unsigned selector, |
697 | unsigned group) |
698 | { |
699 | u8 regbit = (1 << selector + group); |
700 | |
701 | writeb((readb(MUX) & ~(regbit)), MUX) |
702 | return 0; |
703 | } |
704 | |
705 | struct pinmux_ops foo_pmxops = { |
706 | .list_functions = foo_list_funcs, |
707 | .get_function_name = foo_get_fname, |
708 | .get_function_groups = foo_get_groups, |
709 | .enable = foo_enable, |
710 | .disable = foo_disable, |
711 | }; |
712 | |
713 | /* Pinmux operations are handled by some pin controller */ |
714 | static struct pinctrl_desc foo_desc = { |
715 | ... |
716 | .pctlops = &foo_pctrl_ops, |
717 | .pmxops = &foo_pmxops, |
718 | }; |
719 | |
720 | In the example activating muxing 0 and 1 at the same time setting bits |
721 | 0 and 1, uses one pin in common so they would collide. |
722 | |
723 | The beauty of the pinmux subsystem is that since it keeps track of all |
724 | pins and who is using them, it will already have denied an impossible |
725 | request like that, so the driver does not need to worry about such |
726 | things - when it gets a selector passed in, the pinmux subsystem makes |
727 | sure no other device or GPIO assignment is already using the selected |
728 | pins. Thus bits 0 and 1 in the control register will never be set at the |
729 | same time. |
730 | |
731 | All the above functions are mandatory to implement for a pinmux driver. |
732 | |
733 | |
734 | Pin control interaction with the GPIO subsystem |
735 | =============================================== |
736 | |
737 | The public pinmux API contains two functions named pinctrl_request_gpio() |
738 | and pinctrl_free_gpio(). These two functions shall *ONLY* be called from |
739 | gpiolib-based drivers as part of their gpio_request() and |
740 | gpio_free() semantics. Likewise the pinctrl_gpio_direction_[input|output] |
741 | shall only be called from within respective gpio_direction_[input|output] |
742 | gpiolib implementation. |
743 | |
744 | NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be |
745 | controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have |
746 | that driver request proper muxing and other control for its pins. |
747 | |
748 | The function list could become long, especially if you can convert every |
749 | individual pin into a GPIO pin independent of any other pins, and then try |
750 | the approach to define every pin as a function. |
751 | |
752 | In this case, the function array would become 64 entries for each GPIO |
753 | setting and then the device functions. |
754 | |
755 | For this reason there are two functions a pin control driver can implement |
756 | to enable only GPIO on an individual pin: .gpio_request_enable() and |
757 | .gpio_disable_free(). |
758 | |
759 | This function will pass in the affected GPIO range identified by the pin |
760 | controller core, so you know which GPIO pins are being affected by the request |
761 | operation. |
762 | |
763 | If your driver needs to have an indication from the framework of whether the |
764 | GPIO pin shall be used for input or output you can implement the |
765 | .gpio_set_direction() function. As described this shall be called from the |
766 | gpiolib driver and the affected GPIO range, pin offset and desired direction |
767 | will be passed along to this function. |
768 | |
769 | Alternatively to using these special functions, it is fully allowed to use |
770 | named functions for each GPIO pin, the pinctrl_request_gpio() will attempt to |
771 | obtain the function "gpioN" where "N" is the global GPIO pin number if no |
772 | special GPIO-handler is registered. |
773 | |
774 | |
775 | Board/machine configuration |
776 | ================================== |
777 | |
778 | Boards and machines define how a certain complete running system is put |
779 | together, including how GPIOs and devices are muxed, how regulators are |
780 | constrained and how the clock tree looks. Of course pinmux settings are also |
781 | part of this. |
782 | |
783 | A pin controller configuration for a machine looks pretty much like a simple |
784 | regulator configuration, so for the example array above we want to enable i2c |
785 | and spi on the second function mapping: |
786 | |
787 | #include <linux/pinctrl/machine.h> |
788 | |
789 | static const struct pinctrl_map __initdata mapping[] = { |
790 | { |
791 | .dev_name = "foo-spi.0", |
792 | .name = PINCTRL_STATE_DEFAULT, |
793 | .type = PIN_MAP_TYPE_MUX_GROUP, |
794 | .ctrl_dev_name = "pinctrl-foo", |
795 | .data.mux.function = "spi0", |
796 | }, |
797 | { |
798 | .dev_name = "foo-i2c.0", |
799 | .name = PINCTRL_STATE_DEFAULT, |
800 | .type = PIN_MAP_TYPE_MUX_GROUP, |
801 | .ctrl_dev_name = "pinctrl-foo", |
802 | .data.mux.function = "i2c0", |
803 | }, |
804 | { |
805 | .dev_name = "foo-mmc.0", |
806 | .name = PINCTRL_STATE_DEFAULT, |
807 | .type = PIN_MAP_TYPE_MUX_GROUP, |
808 | .ctrl_dev_name = "pinctrl-foo", |
809 | .data.mux.function = "mmc0", |
810 | }, |
811 | }; |
812 | |
813 | The dev_name here matches to the unique device name that can be used to look |
814 | up the device struct (just like with clockdev or regulators). The function name |
815 | must match a function provided by the pinmux driver handling this pin range. |
816 | |
817 | As you can see we may have several pin controllers on the system and thus |
818 | we need to specify which one of them that contain the functions we wish |
819 | to map. |
820 | |
821 | You register this pinmux mapping to the pinmux subsystem by simply: |
822 | |
823 | ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping)); |
824 | |
825 | Since the above construct is pretty common there is a helper macro to make |
826 | it even more compact which assumes you want to use pinctrl-foo and position |
827 | 0 for mapping, for example: |
828 | |
829 | static struct pinctrl_map __initdata mapping[] = { |
830 | PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"), |
831 | }; |
832 | |
833 | The mapping table may also contain pin configuration entries. It's common for |
834 | each pin/group to have a number of configuration entries that affect it, so |
835 | the table entries for configuration reference an array of config parameters |
836 | and values. An example using the convenience macros is shown below: |
837 | |
838 | static unsigned long i2c_grp_configs[] = { |
839 | FOO_PIN_DRIVEN, |
840 | FOO_PIN_PULLUP, |
841 | }; |
842 | |
843 | static unsigned long i2c_pin_configs[] = { |
844 | FOO_OPEN_COLLECTOR, |
845 | FOO_SLEW_RATE_SLOW, |
846 | }; |
847 | |
848 | static struct pinctrl_map __initdata mapping[] = { |
849 | PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "i2c0"), |
850 | PIN_MAP_MUX_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", i2c_grp_configs), |
851 | PIN_MAP_MUX_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0scl", i2c_pin_configs), |
852 | PIN_MAP_MUX_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0sda", i2c_pin_configs), |
853 | }; |
854 | |
855 | Finally, some devices expect the mapping table to contain certain specific |
856 | named states. When running on hardware that doesn't need any pin controller |
857 | configuration, the mapping table must still contain those named states, in |
858 | order to explicitly indicate that the states were provided and intended to |
859 | be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining |
860 | a named state without causing any pin controller to be programmed: |
861 | |
862 | static struct pinctrl_map __initdata mapping[] = { |
863 | PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT), |
864 | }; |
865 | |
866 | |
867 | Complex mappings |
868 | ================ |
869 | |
870 | As it is possible to map a function to different groups of pins an optional |
871 | .group can be specified like this: |
872 | |
873 | ... |
874 | { |
875 | .dev_name = "foo-spi.0", |
876 | .name = "spi0-pos-A", |
877 | .type = PIN_MAP_TYPE_MUX_GROUP, |
878 | .ctrl_dev_name = "pinctrl-foo", |
879 | .function = "spi0", |
880 | .group = "spi0_0_grp", |
881 | }, |
882 | { |
883 | .dev_name = "foo-spi.0", |
884 | .name = "spi0-pos-B", |
885 | .type = PIN_MAP_TYPE_MUX_GROUP, |
886 | .ctrl_dev_name = "pinctrl-foo", |
887 | .function = "spi0", |
888 | .group = "spi0_1_grp", |
889 | }, |
890 | ... |
891 | |
892 | This example mapping is used to switch between two positions for spi0 at |
893 | runtime, as described further below under the heading "Runtime pinmuxing". |
894 | |
895 | Further it is possible for one named state to affect the muxing of several |
896 | groups of pins, say for example in the mmc0 example above, where you can |
897 | additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all |
898 | three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the |
899 | case), we define a mapping like this: |
900 | |
901 | ... |
902 | { |
903 | .dev_name = "foo-mmc.0", |
904 | .name = "2bit" |
905 | .type = PIN_MAP_TYPE_MUX_GROUP, |
906 | .ctrl_dev_name = "pinctrl-foo", |
907 | .function = "mmc0", |
908 | .group = "mmc0_1_grp", |
909 | }, |
910 | { |
911 | .dev_name = "foo-mmc.0", |
912 | .name = "4bit" |
913 | .type = PIN_MAP_TYPE_MUX_GROUP, |
914 | .ctrl_dev_name = "pinctrl-foo", |
915 | .function = "mmc0", |
916 | .group = "mmc0_1_grp", |
917 | }, |
918 | { |
919 | .dev_name = "foo-mmc.0", |
920 | .name = "4bit" |
921 | .type = PIN_MAP_TYPE_MUX_GROUP, |
922 | .ctrl_dev_name = "pinctrl-foo", |
923 | .function = "mmc0", |
924 | .group = "mmc0_2_grp", |
925 | }, |
926 | { |
927 | .dev_name = "foo-mmc.0", |
928 | .name = "8bit" |
929 | .type = PIN_MAP_TYPE_MUX_GROUP, |
930 | .ctrl_dev_name = "pinctrl-foo", |
931 | .function = "mmc0", |
932 | .group = "mmc0_1_grp", |
933 | }, |
934 | { |
935 | .dev_name = "foo-mmc.0", |
936 | .name = "8bit" |
937 | .type = PIN_MAP_TYPE_MUX_GROUP, |
938 | .ctrl_dev_name = "pinctrl-foo", |
939 | .function = "mmc0", |
940 | .group = "mmc0_2_grp", |
941 | }, |
942 | { |
943 | .dev_name = "foo-mmc.0", |
944 | .name = "8bit" |
945 | .type = PIN_MAP_TYPE_MUX_GROUP, |
946 | .ctrl_dev_name = "pinctrl-foo", |
947 | .function = "mmc0", |
948 | .group = "mmc0_3_grp", |
949 | }, |
950 | ... |
951 | |
952 | The result of grabbing this mapping from the device with something like |
953 | this (see next paragraph): |
954 | |
955 | p = pinctrl_get(dev); |
956 | s = pinctrl_lookup_state(p, "8bit"); |
957 | ret = pinctrl_select_state(p, s); |
958 | |
959 | or more simply: |
960 | |
961 | p = pinctrl_get_select(dev, "8bit"); |
962 | |
963 | Will be that you activate all the three bottom records in the mapping at |
964 | once. Since they share the same name, pin controller device, function and |
965 | device, and since we allow multiple groups to match to a single device, they |
966 | all get selected, and they all get enabled and disable simultaneously by the |
967 | pinmux core. |
968 | |
969 | |
970 | Pinmux requests from drivers |
971 | ============================ |
972 | |
973 | Generally it is discouraged to let individual drivers get and enable pin |
974 | control. So if possible, handle the pin control in platform code or some other |
975 | place where you have access to all the affected struct device * pointers. In |
976 | some cases where a driver needs to e.g. switch between different mux mappings |
977 | at runtime this is not possible. |
978 | |
979 | A driver may request a certain control state to be activated, usually just the |
980 | default state like this: |
981 | |
982 | #include <linux/pinctrl/consumer.h> |
983 | |
984 | struct foo_state { |
985 | struct pinctrl *p; |
986 | struct pinctrl_state *s; |
987 | ... |
988 | }; |
989 | |
990 | foo_probe() |
991 | { |
992 | /* Allocate a state holder named "foo" etc */ |
993 | struct foo_state *foo = ...; |
994 | |
995 | foo->p = pinctrl_get(&device); |
996 | if (IS_ERR(foo->p)) { |
997 | /* FIXME: clean up "foo" here */ |
998 | return PTR_ERR(foo->p); |
999 | } |
1000 | |
1001 | foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT); |
1002 | if (IS_ERR(foo->s)) { |
1003 | pinctrl_put(foo->p); |
1004 | /* FIXME: clean up "foo" here */ |
1005 | return PTR_ERR(s); |
1006 | } |
1007 | |
1008 | ret = pinctrl_select_state(foo->s); |
1009 | if (ret < 0) { |
1010 | pinctrl_put(foo->p); |
1011 | /* FIXME: clean up "foo" here */ |
1012 | return ret; |
1013 | } |
1014 | } |
1015 | |
1016 | foo_remove() |
1017 | { |
1018 | pinctrl_put(state->p); |
1019 | } |
1020 | |
1021 | This get/lookup/select/put sequence can just as well be handled by bus drivers |
1022 | if you don't want each and every driver to handle it and you know the |
1023 | arrangement on your bus. |
1024 | |
1025 | The semantics of the pinctrl APIs are: |
1026 | |
1027 | - pinctrl_get() is called in process context to obtain a handle to all pinctrl |
1028 | information for a given client device. It will allocate a struct from the |
1029 | kernel memory to hold the pinmux state. All mapping table parsing or similar |
1030 | slow operations take place within this API. |
1031 | |
1032 | - pinctrl_lookup_state() is called in process context to obtain a handle to a |
1033 | specific state for a the client device. This operation may be slow too. |
1034 | |
1035 | - pinctrl_select_state() programs pin controller hardware according to the |
1036 | definition of the state as given by the mapping table. In theory this is a |
1037 | fast-path operation, since it only involved blasting some register settings |
1038 | into hardware. However, note that some pin controllers may have their |
1039 | registers on a slow/IRQ-based bus, so client devices should not assume they |
1040 | can call pinctrl_select_state() from non-blocking contexts. |
1041 | |
1042 | - pinctrl_put() frees all information associated with a pinctrl handle. |
1043 | |
1044 | Usually the pin control core handled the get/put pair and call out to the |
1045 | device drivers bookkeeping operations, like checking available functions and |
1046 | the associated pins, whereas the enable/disable pass on to the pin controller |
1047 | driver which takes care of activating and/or deactivating the mux setting by |
1048 | quickly poking some registers. |
1049 | |
1050 | The pins are allocated for your device when you issue the pinctrl_get() call, |
1051 | after this you should be able to see this in the debugfs listing of all pins. |
1052 | |
1053 | |
1054 | System pin control hogging |
1055 | ========================== |
1056 | |
1057 | Pin control map entries can be hogged by the core when the pin controller |
1058 | is registered. This means that the core will attempt to call pinctrl_get(), |
1059 | lookup_state() and select_state() on it immediately after the pin control |
1060 | device has been registered. |
1061 | |
1062 | This occurs for mapping table entries where the client device name is equal |
1063 | to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT. |
1064 | |
1065 | { |
1066 | .dev_name = "pinctrl-foo", |
1067 | .name = PINCTRL_STATE_DEFAULT, |
1068 | .type = PIN_MAP_TYPE_MUX_GROUP, |
1069 | .ctrl_dev_name = "pinctrl-foo", |
1070 | .function = "power_func", |
1071 | }, |
1072 | |
1073 | Since it may be common to request the core to hog a few always-applicable |
1074 | mux settings on the primary pin controller, there is a convenience macro for |
1075 | this: |
1076 | |
1077 | PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, "power_func") |
1078 | |
1079 | This gives the exact same result as the above construction. |
1080 | |
1081 | |
1082 | Runtime pinmuxing |
1083 | ================= |
1084 | |
1085 | It is possible to mux a certain function in and out at runtime, say to move |
1086 | an SPI port from one set of pins to another set of pins. Say for example for |
1087 | spi0 in the example above, we expose two different groups of pins for the same |
1088 | function, but with different named in the mapping as described under |
1089 | "Advanced mapping" above. So that for an SPI device, we have two states named |
1090 | "pos-A" and "pos-B". |
1091 | |
1092 | This snippet first muxes the function in the pins defined by group A, enables |
1093 | it, disables and releases it, and muxes it in on the pins defined by group B: |
1094 | |
1095 | #include <linux/pinctrl/consumer.h> |
1096 | |
1097 | foo_switch() |
1098 | { |
1099 | struct pinctrl *p; |
1100 | struct pinctrl_state *s1, *s2; |
1101 | |
1102 | /* Setup */ |
1103 | p = pinctrl_get(&device); |
1104 | if (IS_ERR(p)) |
1105 | ... |
1106 | |
1107 | s1 = pinctrl_lookup_state(foo->p, "pos-A"); |
1108 | if (IS_ERR(s1)) |
1109 | ... |
1110 | |
1111 | s2 = pinctrl_lookup_state(foo->p, "pos-B"); |
1112 | if (IS_ERR(s2)) |
1113 | ... |
1114 | |
1115 | /* Enable on position A */ |
1116 | ret = pinctrl_select_state(s1); |
1117 | if (ret < 0) |
1118 | ... |
1119 | |
1120 | ... |
1121 | |
1122 | /* Enable on position B */ |
1123 | ret = pinctrl_select_state(s2); |
1124 | if (ret < 0) |
1125 | ... |
1126 | |
1127 | ... |
1128 | |
1129 | pinctrl_put(p); |
1130 | } |
1131 | |
1132 | The above has to be done from process context. |
1133 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9