blob: 150fd3833d0bfa114e39ce8d8d6687425aace459 [file] [log] [blame]
Linus Walleij2744e8a2011-05-02 20:50:54 +02001PINCTRL (PIN CONTROL) subsystem
2This document outlines the pin control subsystem in Linux
3
4This subsystem deals with:
5
6- Enumerating and naming controllable pins
7
8- Multiplexing of pins, pads, fingers (etc) see below for details
9
Linus Walleijae6b4d82011-10-19 18:14:33 +020010- 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.
Linus Walleij2744e8a2011-05-02 20:50:54 +020013
14Top-level interface
15===================
16
17Definition 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
23Definition 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
Linus Walleij336cdba02011-11-10 09:27:41 +010032When a PIN CONTROLLER is instantiated, it will register a descriptor to the
Linus Walleij2744e8a2011-05-02 20:50:54 +020033pin control framework, and this descriptor contains an array of pin descriptors
34describing the pins handled by this specific pin controller.
35
36Here 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
56To register a pin controller and name all the pins on this package we can do
57this in our driver:
58
59#include <linux/pinctrl/pinctrl.h>
60
Linus Walleij336cdba02011-11-10 09:27:41 +010061const struct pinctrl_pin_desc foo_pins[] = {
62 PINCTRL_PIN(0, "A8"),
63 PINCTRL_PIN(1, "B8"),
64 PINCTRL_PIN(2, "C8"),
Linus Walleij2744e8a2011-05-02 20:50:54 +020065 ...
Linus Walleij336cdba02011-11-10 09:27:41 +010066 PINCTRL_PIN(61, "F1"),
67 PINCTRL_PIN(62, "G1"),
68 PINCTRL_PIN(63, "H1"),
Linus Walleij2744e8a2011-05-02 20:50:54 +020069};
70
71static 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
79int __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
Linus Walleijae6b4d82011-10-19 18:14:33 +020088To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and
89selected drivers, you need to select them from your machine's Kconfig entry,
90since these are so tightly integrated with the machines they are used on.
91See for example arch/arm/mach-u300/Kconfig for an example.
92
Linus Walleij2744e8a2011-05-02 20:50:54 +020093Pins usually have fancier names than this. You can find these in the dataheet
94for your chip. Notice that the core pinctrl.h file provides a fancy macro
95called PINCTRL_PIN() to create the struct entries. As you can see I enumerated
Linus Walleij336cdba02011-11-10 09:27:41 +010096the pins from 0 in the upper left corner to 63 in the lower right corner.
97This enumeration was arbitrarily chosen, in practice you need to think
Linus Walleij2744e8a2011-05-02 20:50:54 +020098through your numbering system so that it matches the layout of registers
99and such things in your driver, or the code may become complicated. You must
100also consider matching of offsets to the GPIO ranges that may be handled by
101the pin controller.
102
103For a padring with 467 pads, as opposed to actual pins, I used an enumeration
104like this, walking around the edge of the chip, which seems to be industry
105standard 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
116Pin groups
117==========
118
119Many controllers need to deal with groups of pins, so the pin controller
120subsystem has a mechanism for enumerating groups of pins and retrieving the
121actual enumerated pins that are part of a certain group.
122
123For example, say that we have a group of pins dealing with an SPI interface
124on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
125on { 24, 25 }.
126
127These two groups are presented to the pin control subsystem by implementing
128some generic pinctrl_ops like this:
129
130#include <linux/pinctrl/pinctrl.h>
131
132struct foo_group {
133 const char *name;
134 const unsigned int *pins;
135 const unsigned num_pins;
136};
137
Linus Walleij336cdba02011-11-10 09:27:41 +0100138static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
139static const unsigned int i2c0_pins[] = { 24, 25 };
Linus Walleij2744e8a2011-05-02 20:50:54 +0200140
141static 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
155static 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
162static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
163 unsigned selector)
164{
165 return foo_groups[selector].name;
166}
167
168static 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
177static 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
184static struct pinctrl_desc foo_desc = {
185 ...
186 .pctlops = &foo_pctrl_ops,
187};
188
189The pin control subsystem will call the .list_groups() function repeatedly
190beginning on 0 until it returns non-zero to determine legal selectors, then
191it will call the other functions to retrieve the name and pins of the group.
192Maintaining the data structure of the groups is up to the driver, this is
193just a simple example - in practice you may need more entries in your group
194structure, for example specific register ranges associated with each group
195and so on.
196
197
Linus Walleijae6b4d82011-10-19 18:14:33 +0200198Pin configuration
199=================
200
201Pins can sometimes be software-configured in an various ways, mostly related
202to their electronic properties when used as inputs or outputs. For example you
203may be able to make an output pin high impedance, or "tristate" meaning it is
204effectively disconnected. You may be able to connect an input pin to VDD or GND
205using a certain resistor value - pull up and pull down - so that the pin has a
206stable value when nothing is driving the rail it is connected to, or when it's
207unconnected.
208
209For example, a platform may do this:
210
Stephen Warren43699de2011-12-15 16:57:17 -0700211ret = pin_config_set("foo-dev", "FOO_GPIO_PIN", PLATFORM_X_PULL_UP);
Linus Walleijae6b4d82011-10-19 18:14:33 +0200212
213To pull up a pin to VDD. The pin configuration driver implements callbacks for
214changing pin configuration in the pin controller ops like this:
215
216#include <linux/pinctrl/pinctrl.h>
217#include <linux/pinctrl/pinconf.h>
218#include "platform_x_pindefs.h"
219
Dong Aishenge6337c32011-12-20 17:51:59 +0800220static int foo_pin_config_get(struct pinctrl_dev *pctldev,
Linus Walleijae6b4d82011-10-19 18:14:33 +0200221 unsigned offset,
222 unsigned long *config)
223{
224 struct my_conftype conf;
225
226 ... Find setting for pin @ offset ...
227
228 *config = (unsigned long) conf;
229}
230
Dong Aishenge6337c32011-12-20 17:51:59 +0800231static int foo_pin_config_set(struct pinctrl_dev *pctldev,
Linus Walleijae6b4d82011-10-19 18:14:33 +0200232 unsigned offset,
233 unsigned long config)
234{
235 struct my_conftype *conf = (struct my_conftype *) config;
236
237 switch (conf) {
238 case PLATFORM_X_PULL_UP:
239 ...
240 }
241 }
242}
243
Dong Aishenge6337c32011-12-20 17:51:59 +0800244static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
Linus Walleijae6b4d82011-10-19 18:14:33 +0200245 unsigned selector,
246 unsigned long *config)
247{
248 ...
249}
250
Dong Aishenge6337c32011-12-20 17:51:59 +0800251static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
Linus Walleijae6b4d82011-10-19 18:14:33 +0200252 unsigned selector,
253 unsigned long config)
254{
255 ...
256}
257
258static struct pinconf_ops foo_pconf_ops = {
259 .pin_config_get = foo_pin_config_get,
260 .pin_config_set = foo_pin_config_set,
261 .pin_config_group_get = foo_pin_config_group_get,
262 .pin_config_group_set = foo_pin_config_group_set,
263};
264
265/* Pin config operations are handled by some pin controller */
266static struct pinctrl_desc foo_desc = {
267 ...
268 .confops = &foo_pconf_ops,
269};
270
271Since some controllers have special logic for handling entire groups of pins
272they can exploit the special whole-group pin control function. The
273pin_config_group_set() callback is allowed to return the error code -EAGAIN,
274for groups it does not want to handle, or if it just wants to do some
275group-level handling and then fall through to iterate over all pins, in which
276case each individual pin will be treated by separate pin_config_set() calls as
277well.
278
279
Linus Walleij2744e8a2011-05-02 20:50:54 +0200280Interaction with the GPIO subsystem
281===================================
282
283The GPIO drivers may want to perform operations of various types on the same
284physical pins that are also registered as pin controller pins.
285
286Since the pin controller subsystem have its pinspace local to the pin
287controller we need a mapping so that the pin control subsystem can figure out
288which pin controller handles control of a certain GPIO pin. Since a single
289pin controller may be muxing several GPIO ranges (typically SoCs that have
290one set of pins but internally several GPIO silicon blocks, each modeled as
291a struct gpio_chip) any number of GPIO ranges can be added to a pin controller
292instance like this:
293
294struct gpio_chip chip_a;
295struct gpio_chip chip_b;
296
297static struct pinctrl_gpio_range gpio_range_a = {
298 .name = "chip a",
299 .id = 0,
300 .base = 32,
Chanho Park3c739ad2011-11-11 18:47:58 +0900301 .pin_base = 32,
Linus Walleij2744e8a2011-05-02 20:50:54 +0200302 .npins = 16,
303 .gc = &chip_a;
304};
305
Chanho Park3c739ad2011-11-11 18:47:58 +0900306static struct pinctrl_gpio_range gpio_range_b = {
Linus Walleij2744e8a2011-05-02 20:50:54 +0200307 .name = "chip b",
308 .id = 0,
309 .base = 48,
Chanho Park3c739ad2011-11-11 18:47:58 +0900310 .pin_base = 64,
Linus Walleij2744e8a2011-05-02 20:50:54 +0200311 .npins = 8,
312 .gc = &chip_b;
313};
314
Linus Walleij2744e8a2011-05-02 20:50:54 +0200315{
316 struct pinctrl_dev *pctl;
317 ...
318 pinctrl_add_gpio_range(pctl, &gpio_range_a);
319 pinctrl_add_gpio_range(pctl, &gpio_range_b);
320}
321
322So this complex system has one pin controller handling two different
Chanho Park3c739ad2011-11-11 18:47:58 +0900323GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
324"chip b" have different .pin_base, which means a start pin number of the
325GPIO range.
Linus Walleij2744e8a2011-05-02 20:50:54 +0200326
Chanho Park3c739ad2011-11-11 18:47:58 +0900327The GPIO range of "chip a" starts from the GPIO base of 32 and actual
328pin range also starts from 32. However "chip b" has different starting
329offset for the GPIO range and pin range. The GPIO range of "chip b" starts
330from GPIO number 48, while the pin range of "chip b" starts from 64.
331
332We can convert a gpio number to actual pin number using this "pin_base".
333They are mapped in the global GPIO pin space at:
334
335chip a:
336 - GPIO range : [32 .. 47]
337 - pin range : [32 .. 47]
338chip b:
339 - GPIO range : [48 .. 55]
340 - pin range : [64 .. 71]
Linus Walleij2744e8a2011-05-02 20:50:54 +0200341
342When GPIO-specific functions in the pin control subsystem are called, these
Linus Walleij336cdba02011-11-10 09:27:41 +0100343ranges will be used to look up the appropriate pin controller by inspecting
Linus Walleij2744e8a2011-05-02 20:50:54 +0200344and matching the pin to the pin ranges across all controllers. When a
345pin controller handling the matching range is found, GPIO-specific functions
346will be called on that specific pin controller.
347
348For all functionalities dealing with pin biasing, pin muxing etc, the pin
349controller subsystem will subtract the range's .base offset from the passed
Chanho Park3c739ad2011-11-11 18:47:58 +0900350in gpio number, and add the ranges's .pin_base offset to retrive a pin number.
351After that, the subsystem passes it on to the pin control driver, so the driver
352will get an pin number into its handled number range. Further it is also passed
Linus Walleij2744e8a2011-05-02 20:50:54 +0200353the range ID value, so that the pin controller knows which range it should
354deal with.
355
Linus Walleij2744e8a2011-05-02 20:50:54 +0200356PINMUX interfaces
357=================
358
359These calls use the pinmux_* naming prefix. No other calls should use that
360prefix.
361
362
363What is pinmuxing?
364==================
365
366PINMUX, also known as padmux, ballmux, alternate functions or mission modes
367is a way for chip vendors producing some kind of electrical packages to use
368a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive
369functions, depending on the application. By "application" in this context
370we usually mean a way of soldering or wiring the package into an electronic
371system, even though the framework makes it possible to also change the function
372at runtime.
373
374Here is an example of a PGA (Pin Grid Array) chip seen from underneath:
375
376 A B C D E F G H
377 +---+
378 8 | o | o o o o o o o
379 | |
380 7 | o | o o o o o o o
381 | |
382 6 | o | o o o o o o o
383 +---+---+
384 5 | o | o | o o o o o o
385 +---+---+ +---+
386 4 o o o o o o | o | o
387 | |
388 3 o o o o o o | o | o
389 | |
390 2 o o o o o o | o | o
391 +-------+-------+-------+---+---+
392 1 | o o | o o | o o | o | o |
393 +-------+-------+-------+---+---+
394
395This is not tetris. The game to think of is chess. Not all PGA/BGA packages
396are chessboard-like, big ones have "holes" in some arrangement according to
397different design patterns, but we're using this as a simple example. Of the
398pins you see some will be taken by things like a few VCC and GND to feed power
399to the chip, and quite a few will be taken by large ports like an external
400memory interface. The remaining pins will often be subject to pin multiplexing.
401
402The example 8x8 PGA package above will have pin numbers 0 thru 63 assigned to
403its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using
404pinctrl_register_pins() and a suitable data set as shown earlier.
405
406In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port
407(these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as
408some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can
409be used as an I2C port (these are just two pins: SCL, SDA). Needless to say,
410we cannot use the SPI port and I2C port at the same time. However in the inside
411of the package the silicon performing the SPI logic can alternatively be routed
412out on pins { G4, G3, G2, G1 }.
413
414On the botton row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something
415special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will
416consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or
417{ A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI
418port on pins { G4, G3, G2, G1 } of course.
419
420This way the silicon blocks present inside the chip can be multiplexed "muxed"
421out on different pin ranges. Often contemporary SoC (systems on chip) will
422contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to
423different pins by pinmux settings.
424
425Since general-purpose I/O pins (GPIO) are typically always in shortage, it is
426common to be able to use almost any pin as a GPIO pin if it is not currently
427in use by some other I/O port.
428
429
430Pinmux conventions
431==================
432
433The purpose of the pinmux functionality in the pin controller subsystem is to
434abstract and provide pinmux settings to the devices you choose to instantiate
435in your machine configuration. It is inspired by the clk, GPIO and regulator
436subsystems, so devices will request their mux setting, but it's also possible
437to request a single pin for e.g. GPIO.
438
439Definitions:
440
441- FUNCTIONS can be switched in and out by a driver residing with the pin
442 control subsystem in the drivers/pinctrl/* directory of the kernel. The
443 pin control driver knows the possible functions. In the example above you can
444 identify three pinmux functions, one for spi, one for i2c and one for mmc.
445
446- FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.
447 In this case the array could be something like: { spi0, i2c0, mmc0 }
448 for the three available functions.
449
450- FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain
451 function is *always* associated with a certain set of pin groups, could
452 be just a single one, but could also be many. In the example above the
453 function i2c is associated with the pins { A5, B5 }, enumerated as
454 { 24, 25 } in the controller pin space.
455
456 The Function spi is associated with pin groups { A8, A7, A6, A5 }
457 and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and
458 { 38, 46, 54, 62 } respectively.
459
460 Group names must be unique per pin controller, no two groups on the same
461 controller may have the same name.
462
463- The combination of a FUNCTION and a PIN GROUP determine a certain function
464 for a certain set of pins. The knowledge of the functions and pin groups
465 and their machine-specific particulars are kept inside the pinmux driver,
466 from the outside only the enumerators are known, and the driver core can:
467
468 - Request the name of a function with a certain selector (>= 0)
469 - A list of groups associated with a certain function
470 - Request that a certain group in that list to be activated for a certain
471 function
472
473 As already described above, pin groups are in turn self-descriptive, so
474 the core will retrieve the actual pin range in a certain group from the
475 driver.
476
477- FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain
478 device by the board file, device tree or similar machine setup configuration
479 mechanism, similar to how regulators are connected to devices, usually by
480 name. Defining a pin controller, function and group thus uniquely identify
481 the set of pins to be used by a certain device. (If only one possible group
482 of pins is available for the function, no group name need to be supplied -
483 the core will simply select the first and only group available.)
484
485 In the example case we can define that this particular machine shall
486 use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function
487 fi2c0 group gi2c0, on the primary pin controller, we get mappings
488 like these:
489
490 {
491 {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
492 {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
493 }
494
495 Every map must be assigned a symbolic name, pin controller and function.
496 The group is not compulsory - if it is omitted the first group presented by
497 the driver as applicable for the function will be selected, which is
498 useful for simple cases.
499
500 The device name is present in map entries tied to specific devices. Maps
501 without device names are referred to as SYSTEM pinmuxes, such as can be taken
502 by the machine implementation on boot and not tied to any specific device.
503
504 It is possible to map several groups to the same combination of device,
505 pin controller and function. This is for cases where a certain function on
506 a certain pin controller may use different sets of pins in different
507 configurations.
508
509- PINS for a certain FUNCTION using a certain PIN GROUP on a certain
510 PIN CONTROLLER are provided on a first-come first-serve basis, so if some
511 other device mux setting or GPIO pin request has already taken your physical
512 pin, you will be denied the use of it. To get (activate) a new setting, the
513 old one has to be put (deactivated) first.
514
515Sometimes the documentation and hardware registers will be oriented around
516pads (or "fingers") rather than pins - these are the soldering surfaces on the
517silicon inside the package, and may or may not match the actual number of
518pins/balls underneath the capsule. Pick some enumeration that makes sense to
519you. Define enumerators only for the pins you can control if that makes sense.
520
521Assumptions:
522
Linus Walleij336cdba02011-11-10 09:27:41 +0100523We assume that the number of possible function maps to pin groups is limited by
Linus Walleij2744e8a2011-05-02 20:50:54 +0200524the hardware. I.e. we assume that there is no system where any function can be
525mapped to any pin, like in a phone exchange. So the available pins groups for
526a certain function will be limited to a few choices (say up to eight or so),
527not hundreds or any amount of choices. This is the characteristic we have found
528by inspecting available pinmux hardware, and a necessary assumption since we
529expect pinmux drivers to present *all* possible function vs pin group mappings
530to the subsystem.
531
532
533Pinmux drivers
534==============
535
536The pinmux core takes care of preventing conflicts on pins and calling
537the pin controller driver to execute different settings.
538
539It is the responsibility of the pinmux driver to impose further restrictions
540(say for example infer electronic limitations due to load etc) to determine
541whether or not the requested function can actually be allowed, and in case it
542is possible to perform the requested mux setting, poke the hardware so that
543this happens.
544
545Pinmux drivers are required to supply a few callback functions, some are
546optional. Usually the enable() and disable() functions are implemented,
547writing values into some certain registers to activate a certain mux setting
548for a certain pin.
549
550A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
551into some register named MUX to select a certain function with a certain
552group of pins would work something like this:
553
554#include <linux/pinctrl/pinctrl.h>
555#include <linux/pinctrl/pinmux.h>
556
557struct foo_group {
558 const char *name;
559 const unsigned int *pins;
560 const unsigned num_pins;
561};
562
563static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
564static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
565static const unsigned i2c0_pins[] = { 24, 25 };
566static const unsigned mmc0_1_pins[] = { 56, 57 };
567static const unsigned mmc0_2_pins[] = { 58, 59 };
568static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
569
570static const struct foo_group foo_groups[] = {
571 {
572 .name = "spi0_0_grp",
573 .pins = spi0_0_pins,
574 .num_pins = ARRAY_SIZE(spi0_0_pins),
575 },
576 {
577 .name = "spi0_1_grp",
578 .pins = spi0_1_pins,
579 .num_pins = ARRAY_SIZE(spi0_1_pins),
580 },
581 {
582 .name = "i2c0_grp",
583 .pins = i2c0_pins,
584 .num_pins = ARRAY_SIZE(i2c0_pins),
585 },
586 {
587 .name = "mmc0_1_grp",
588 .pins = mmc0_1_pins,
589 .num_pins = ARRAY_SIZE(mmc0_1_pins),
590 },
591 {
592 .name = "mmc0_2_grp",
593 .pins = mmc0_2_pins,
594 .num_pins = ARRAY_SIZE(mmc0_2_pins),
595 },
596 {
597 .name = "mmc0_3_grp",
598 .pins = mmc0_3_pins,
599 .num_pins = ARRAY_SIZE(mmc0_3_pins),
600 },
601};
602
603
604static int foo_list_groups(struct pinctrl_dev *pctldev, unsigned selector)
605{
606 if (selector >= ARRAY_SIZE(foo_groups))
607 return -EINVAL;
608 return 0;
609}
610
611static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
612 unsigned selector)
613{
614 return foo_groups[selector].name;
615}
616
617static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
618 unsigned ** const pins,
619 unsigned * const num_pins)
620{
621 *pins = (unsigned *) foo_groups[selector].pins;
622 *num_pins = foo_groups[selector].num_pins;
623 return 0;
624}
625
626static struct pinctrl_ops foo_pctrl_ops = {
627 .list_groups = foo_list_groups,
628 .get_group_name = foo_get_group_name,
629 .get_group_pins = foo_get_group_pins,
630};
631
632struct foo_pmx_func {
633 const char *name;
634 const char * const *groups;
635 const unsigned num_groups;
636};
637
638static const char * const spi0_groups[] = { "spi0_1_grp" };
639static const char * const i2c0_groups[] = { "i2c0_grp" };
640static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
641 "mmc0_3_grp" };
642
643static const struct foo_pmx_func foo_functions[] = {
644 {
645 .name = "spi0",
646 .groups = spi0_groups,
647 .num_groups = ARRAY_SIZE(spi0_groups),
648 },
649 {
650 .name = "i2c0",
651 .groups = i2c0_groups,
652 .num_groups = ARRAY_SIZE(i2c0_groups),
653 },
654 {
655 .name = "mmc0",
656 .groups = mmc0_groups,
657 .num_groups = ARRAY_SIZE(mmc0_groups),
658 },
659};
660
661int foo_list_funcs(struct pinctrl_dev *pctldev, unsigned selector)
662{
663 if (selector >= ARRAY_SIZE(foo_functions))
664 return -EINVAL;
665 return 0;
666}
667
668const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
669{
Linus Walleij336cdba02011-11-10 09:27:41 +0100670 return foo_functions[selector].name;
Linus Walleij2744e8a2011-05-02 20:50:54 +0200671}
672
673static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
674 const char * const **groups,
675 unsigned * const num_groups)
676{
677 *groups = foo_functions[selector].groups;
678 *num_groups = foo_functions[selector].num_groups;
679 return 0;
680}
681
682int foo_enable(struct pinctrl_dev *pctldev, unsigned selector,
683 unsigned group)
684{
Linus Walleij336cdba02011-11-10 09:27:41 +0100685 u8 regbit = (1 << selector + group);
Linus Walleij2744e8a2011-05-02 20:50:54 +0200686
687 writeb((readb(MUX)|regbit), MUX)
688 return 0;
689}
690
Linus Walleij336cdba02011-11-10 09:27:41 +0100691void foo_disable(struct pinctrl_dev *pctldev, unsigned selector,
Linus Walleij2744e8a2011-05-02 20:50:54 +0200692 unsigned group)
693{
Linus Walleij336cdba02011-11-10 09:27:41 +0100694 u8 regbit = (1 << selector + group);
Linus Walleij2744e8a2011-05-02 20:50:54 +0200695
696 writeb((readb(MUX) & ~(regbit)), MUX)
697 return 0;
698}
699
700struct pinmux_ops foo_pmxops = {
701 .list_functions = foo_list_funcs,
702 .get_function_name = foo_get_fname,
703 .get_function_groups = foo_get_groups,
704 .enable = foo_enable,
705 .disable = foo_disable,
706};
707
708/* Pinmux operations are handled by some pin controller */
709static struct pinctrl_desc foo_desc = {
710 ...
711 .pctlops = &foo_pctrl_ops,
712 .pmxops = &foo_pmxops,
713};
714
715In the example activating muxing 0 and 1 at the same time setting bits
7160 and 1, uses one pin in common so they would collide.
717
718The beauty of the pinmux subsystem is that since it keeps track of all
719pins and who is using them, it will already have denied an impossible
720request like that, so the driver does not need to worry about such
721things - when it gets a selector passed in, the pinmux subsystem makes
722sure no other device or GPIO assignment is already using the selected
723pins. Thus bits 0 and 1 in the control register will never be set at the
724same time.
725
726All the above functions are mandatory to implement for a pinmux driver.
727
728
729Pinmux interaction with the GPIO subsystem
730==========================================
731
Linus Walleij542e7042011-11-14 10:06:22 +0100732The public pinmux API contains two functions named pinmux_request_gpio()
733and pinmux_free_gpio(). These two functions shall *ONLY* be called from
734gpiolib-based drivers as part of their gpio_request() and
735gpio_free() semantics. Likewise the pinmux_gpio_direction_[input|output]
736shall only be called from within respective gpio_direction_[input|output]
737gpiolib implementation.
738
739NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be
740muxed in. Instead, implement a proper gpiolib driver and have that driver
741request proper muxing for its pins.
742
Linus Walleij2744e8a2011-05-02 20:50:54 +0200743The function list could become long, especially if you can convert every
744individual pin into a GPIO pin independent of any other pins, and then try
745the approach to define every pin as a function.
746
747In this case, the function array would become 64 entries for each GPIO
748setting and then the device functions.
749
Linus Walleij542e7042011-11-14 10:06:22 +0100750For this reason there are two functions a pinmux driver can implement
751to enable only GPIO on an individual pin: .gpio_request_enable() and
752.gpio_disable_free().
Linus Walleij2744e8a2011-05-02 20:50:54 +0200753
754This function will pass in the affected GPIO range identified by the pin
755controller core, so you know which GPIO pins are being affected by the request
756operation.
757
Linus Walleij542e7042011-11-14 10:06:22 +0100758If your driver needs to have an indication from the framework of whether the
759GPIO pin shall be used for input or output you can implement the
760.gpio_set_direction() function. As described this shall be called from the
761gpiolib driver and the affected GPIO range, pin offset and desired direction
762will be passed along to this function.
763
764Alternatively to using these special functions, it is fully allowed to use
765named functions for each GPIO pin, the pinmux_request_gpio() will attempt to
766obtain the function "gpioN" where "N" is the global GPIO pin number if no
767special GPIO-handler is registered.
Linus Walleij2744e8a2011-05-02 20:50:54 +0200768
769
770Pinmux board/machine configuration
771==================================
772
773Boards and machines define how a certain complete running system is put
774together, including how GPIOs and devices are muxed, how regulators are
775constrained and how the clock tree looks. Of course pinmux settings are also
776part of this.
777
778A pinmux config for a machine looks pretty much like a simple regulator
779configuration, so for the example array above we want to enable i2c and
780spi on the second function mapping:
781
782#include <linux/pinctrl/machine.h>
783
Linus Walleij97607d12011-11-29 12:52:39 +0100784static const struct pinmux_map __initdata pmx_mapping[] = {
Linus Walleij2744e8a2011-05-02 20:50:54 +0200785 {
Stephen Warren51cd24e2011-12-09 16:59:05 -0700786 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200787 .function = "spi0",
788 .dev_name = "foo-spi.0",
789 },
790 {
Stephen Warren51cd24e2011-12-09 16:59:05 -0700791 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200792 .function = "i2c0",
793 .dev_name = "foo-i2c.0",
794 },
795 {
Stephen Warren51cd24e2011-12-09 16:59:05 -0700796 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200797 .function = "mmc0",
798 .dev_name = "foo-mmc.0",
799 },
800};
801
802The dev_name here matches to the unique device name that can be used to look
803up the device struct (just like with clockdev or regulators). The function name
804must match a function provided by the pinmux driver handling this pin range.
805
806As you can see we may have several pin controllers on the system and thus
807we need to specify which one of them that contain the functions we wish
808to map. The map can also use struct device * directly, so there is no
809inherent need to use strings to specify .dev_name or .ctrl_dev_name, these
810are for the situation where you do not have a handle to the struct device *,
811for example if they are not yet instantiated or cumbersome to obtain.
812
813You register this pinmux mapping to the pinmux subsystem by simply:
814
Linus Walleij336cdba02011-11-10 09:27:41 +0100815 ret = pinmux_register_mappings(pmx_mapping, ARRAY_SIZE(pmx_mapping));
Linus Walleij2744e8a2011-05-02 20:50:54 +0200816
817Since the above construct is pretty common there is a helper macro to make
Stephen Warren51cd24e2011-12-09 16:59:05 -0700818it even more compact which assumes you want to use pinctrl-foo and position
Linus Walleij2744e8a2011-05-02 20:50:54 +02008190 for mapping, for example:
820
Linus Walleij97607d12011-11-29 12:52:39 +0100821static struct pinmux_map __initdata pmx_mapping[] = {
Dong Aishenge6337c32011-12-20 17:51:59 +0800822 PINMUX_MAP("I2CMAP", "pinctrl-foo", "i2c0", "foo-i2c.0"),
Linus Walleij2744e8a2011-05-02 20:50:54 +0200823};
824
825
826Complex mappings
827================
828
829As it is possible to map a function to different groups of pins an optional
830.group can be specified like this:
831
832...
833{
834 .name = "spi0-pos-A",
Stephen Warren51cd24e2011-12-09 16:59:05 -0700835 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200836 .function = "spi0",
837 .group = "spi0_0_grp",
838 .dev_name = "foo-spi.0",
839},
840{
841 .name = "spi0-pos-B",
Stephen Warren51cd24e2011-12-09 16:59:05 -0700842 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200843 .function = "spi0",
844 .group = "spi0_1_grp",
845 .dev_name = "foo-spi.0",
846},
847...
848
849This example mapping is used to switch between two positions for spi0 at
850runtime, as described further below under the heading "Runtime pinmuxing".
851
852Further it is possible to match several groups of pins to the same function
853for a single device, say for example in the mmc0 example above, where you can
854additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all
855three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
856case), we define a mapping like this:
857
858...
859{
Uwe Kleine-Königf54367f2012-01-19 22:35:05 +0100860 .name = "2bit"
Stephen Warren51cd24e2011-12-09 16:59:05 -0700861 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200862 .function = "mmc0",
Linus Walleij336cdba02011-11-10 09:27:41 +0100863 .group = "mmc0_1_grp",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200864 .dev_name = "foo-mmc.0",
865},
866{
Uwe Kleine-Königf54367f2012-01-19 22:35:05 +0100867 .name = "4bit"
Stephen Warren51cd24e2011-12-09 16:59:05 -0700868 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200869 .function = "mmc0",
870 .group = "mmc0_1_grp",
871 .dev_name = "foo-mmc.0",
872},
873{
Uwe Kleine-Königf54367f2012-01-19 22:35:05 +0100874 .name = "4bit"
Stephen Warren51cd24e2011-12-09 16:59:05 -0700875 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200876 .function = "mmc0",
Linus Walleij336cdba02011-11-10 09:27:41 +0100877 .group = "mmc0_2_grp",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200878 .dev_name = "foo-mmc.0",
879},
880{
Uwe Kleine-Königf54367f2012-01-19 22:35:05 +0100881 .name = "8bit"
Stephen Warren51cd24e2011-12-09 16:59:05 -0700882 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200883 .group = "mmc0_1_grp",
884 .dev_name = "foo-mmc.0",
885},
886{
Uwe Kleine-Königf54367f2012-01-19 22:35:05 +0100887 .name = "8bit"
Stephen Warren51cd24e2011-12-09 16:59:05 -0700888 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200889 .function = "mmc0",
890 .group = "mmc0_2_grp",
891 .dev_name = "foo-mmc.0",
892},
Linus Walleij336cdba02011-11-10 09:27:41 +0100893{
Uwe Kleine-Königf54367f2012-01-19 22:35:05 +0100894 .name = "8bit"
Stephen Warren51cd24e2011-12-09 16:59:05 -0700895 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij336cdba02011-11-10 09:27:41 +0100896 .function = "mmc0",
897 .group = "mmc0_3_grp",
898 .dev_name = "foo-mmc.0",
899},
Linus Walleij2744e8a2011-05-02 20:50:54 +0200900...
901
902The result of grabbing this mapping from the device with something like
903this (see next paragraph):
904
905 pmx = pinmux_get(&device, "8bit");
906
907Will be that you activate all the three bottom records in the mapping at
908once. Since they share the same name, pin controller device, funcion and
909device, and since we allow multiple groups to match to a single device, they
910all get selected, and they all get enabled and disable simultaneously by the
911pinmux core.
912
913
914Pinmux requests from drivers
915============================
916
917Generally it is discouraged to let individual drivers get and enable pinmuxes.
918So if possible, handle the pinmuxes in platform code or some other place where
919you have access to all the affected struct device * pointers. In some cases
920where a driver needs to switch between different mux mappings at runtime
921this is not possible.
922
923A driver may request a certain mux to be activated, usually just the default
924mux like this:
925
926#include <linux/pinctrl/pinmux.h>
927
928struct foo_state {
929 struct pinmux *pmx;
930 ...
931};
932
933foo_probe()
934{
935 /* Allocate a state holder named "state" etc */
936 struct pinmux pmx;
937
938 pmx = pinmux_get(&device, NULL);
939 if IS_ERR(pmx)
940 return PTR_ERR(pmx);
941 pinmux_enable(pmx);
942
943 state->pmx = pmx;
944}
945
946foo_remove()
947{
948 pinmux_disable(state->pmx);
949 pinmux_put(state->pmx);
950}
951
952If you want to grab a specific mux mapping and not just the first one found for
953this device you can specify a specific mapping name, for example in the above
954example the second i2c0 setting: pinmux_get(&device, "spi0-pos-B");
955
956This get/enable/disable/put sequence can just as well be handled by bus drivers
957if you don't want each and every driver to handle it and you know the
958arrangement on your bus.
959
960The semantics of the get/enable respective disable/put is as follows:
961
962- pinmux_get() is called in process context to reserve the pins affected with
963 a certain mapping and set up the pinmux core and the driver. It will allocate
964 a struct from the kernel memory to hold the pinmux state.
965
966- pinmux_enable()/pinmux_disable() is quick and can be called from fastpath
967 (irq context) when you quickly want to set up/tear down the hardware muxing
968 when running a device driver. Usually it will just poke some values into a
969 register.
970
971- pinmux_disable() is called in process context to tear down the pin requests
972 and release the state holder struct for the mux setting.
973
974Usually the pinmux core handled the get/put pair and call out to the device
975drivers bookkeeping operations, like checking available functions and the
976associated pins, whereas the enable/disable pass on to the pin controller
977driver which takes care of activating and/or deactivating the mux setting by
978quickly poking some registers.
979
980The pins are allocated for your device when you issue the pinmux_get() call,
981after this you should be able to see this in the debugfs listing of all pins.
982
983
984System pinmux hogging
985=====================
986
987A system pinmux map entry, i.e. a pinmux setting that does not have a device
988associated with it, can be hogged by the core when the pin controller is
989registered. This means that the core will attempt to call pinmux_get() and
990pinmux_enable() on it immediately after the pin control device has been
991registered.
992
993This is enabled by simply setting the .hog_on_boot field in the map to true,
994like this:
995
996{
Uwe Kleine-Königf54367f2012-01-19 22:35:05 +0100997 .name = "POWERMAP"
Stephen Warren51cd24e2011-12-09 16:59:05 -0700998 .ctrl_dev_name = "pinctrl-foo",
Linus Walleij2744e8a2011-05-02 20:50:54 +0200999 .function = "power_func",
1000 .hog_on_boot = true,
1001},
1002
1003Since it may be common to request the core to hog a few always-applicable
1004mux settings on the primary pin controller, there is a convenience macro for
1005this:
1006
1007PINMUX_MAP_PRIMARY_SYS_HOG("POWERMAP", "power_func")
1008
1009This gives the exact same result as the above construction.
1010
1011
1012Runtime pinmuxing
1013=================
1014
1015It is possible to mux a certain function in and out at runtime, say to move
1016an SPI port from one set of pins to another set of pins. Say for example for
1017spi0 in the example above, we expose two different groups of pins for the same
1018function, but with different named in the mapping as described under
1019"Advanced mapping" above. So we have two mappings named "spi0-pos-A" and
1020"spi0-pos-B".
1021
1022This snippet first muxes the function in the pins defined by group A, enables
1023it, disables and releases it, and muxes it in on the pins defined by group B:
1024
1025foo_switch()
1026{
Tony Lindgrende849ee2012-01-20 08:17:33 -08001027 struct pinmux *pmx;
Linus Walleij2744e8a2011-05-02 20:50:54 +02001028
1029 /* Enable on position A */
1030 pmx = pinmux_get(&device, "spi0-pos-A");
1031 if IS_ERR(pmx)
1032 return PTR_ERR(pmx);
1033 pinmux_enable(pmx);
1034
1035 /* This releases the pins again */
1036 pinmux_disable(pmx);
1037 pinmux_put(pmx);
1038
1039 /* Enable on position B */
1040 pmx = pinmux_get(&device, "spi0-pos-B");
1041 if IS_ERR(pmx)
1042 return PTR_ERR(pmx);
1043 pinmux_enable(pmx);
1044 ...
1045}
1046
1047The above has to be done from process context.