1PINCTRL (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 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 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 32When a PIN CONTROLLER is instantiated, it will register a descriptor to the 33pin 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 61const 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 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 88To 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 93Pins 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 96the 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 98through 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 138static const unsigned int spi0_pins[] = { 0, 8, 16, 24 }; 139static const unsigned int i2c0_pins[] = { 24, 25 }; 140 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 198Pin 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 211ret = pin_config_set("foo-dev", "FOO_GPIO_PIN", PLATFORM_X_PULL_UP); 212 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 220static int foo_pin_config_get(struct pinctrl_dev *pctldev, 221 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 231static int foo_pin_config_set(struct pinctrl_dev *pctldev, 232 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 244static int foo_pin_config_group_get (struct pinctrl_dev *pctldev, 245 unsigned selector, 246 unsigned long *config) 247{ 248 ... 249} 250 251static int foo_pin_config_group_set (struct pinctrl_dev *pctldev, 252 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 280Interaction 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, 301 .pin_base = 32, 302 .npins = 16, 303 .gc = &chip_a; 304}; 305 306static struct pinctrl_gpio_range gpio_range_b = { 307 .name = "chip b", 308 .id = 0, 309 .base = 48, 310 .pin_base = 64, 311 .npins = 8, 312 .gc = &chip_b; 313}; 314 315{ 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 323GPIO 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. 326 327The 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] 341 342When GPIO-specific functions in the pin control subsystem are called, these 343ranges will be used to look up the appropriate pin controller by inspecting 344and 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 350in 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 353the range ID value, so that the pin controller knows which range it should 354deal with. 355 356PINMUX 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 523We assume that the number of possible function maps to pin groups is limited by 524the 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{ 670 return foo_functions[selector].name; 671} 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{ 685 u8 regbit = (1 << selector + group); 686 687 writeb((readb(MUX)|regbit), MUX) 688 return 0; 689} 690 691void foo_disable(struct pinctrl_dev *pctldev, unsigned selector, 692 unsigned group) 693{ 694 u8 regbit = (1 << selector + group); 695 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 732The 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 743The 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 750For 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(). 753 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 758If 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. 768 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 784static const struct pinmux_map __initdata pmx_mapping[] = { 785 { 786 .ctrl_dev_name = "pinctrl-foo", 787 .function = "spi0", 788 .dev_name = "foo-spi.0", 789 }, 790 { 791 .ctrl_dev_name = "pinctrl-foo", 792 .function = "i2c0", 793 .dev_name = "foo-i2c.0", 794 }, 795 { 796 .ctrl_dev_name = "pinctrl-foo", 797 .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 815 ret = pinmux_register_mappings(pmx_mapping, ARRAY_SIZE(pmx_mapping)); 816 817Since the above construct is pretty common there is a helper macro to make 818it even more compact which assumes you want to use pinctrl-foo and position 8190 for mapping, for example: 820 821static struct pinmux_map __initdata pmx_mapping[] = { 822 PINMUX_MAP("I2CMAP", "pinctrl-foo", "i2c0", "foo-i2c.0"), 823}; 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", 835 .ctrl_dev_name = "pinctrl-foo", 836 .function = "spi0", 837 .group = "spi0_0_grp", 838 .dev_name = "foo-spi.0", 839}, 840{ 841 .name = "spi0-pos-B", 842 .ctrl_dev_name = "pinctrl-foo", 843 .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{ 860 .name = "2bit" 861 .ctrl_dev_name = "pinctrl-foo", 862 .function = "mmc0", 863 .group = "mmc0_1_grp", 864 .dev_name = "foo-mmc.0", 865}, 866{ 867 .name = "4bit" 868 .ctrl_dev_name = "pinctrl-foo", 869 .function = "mmc0", 870 .group = "mmc0_1_grp", 871 .dev_name = "foo-mmc.0", 872}, 873{ 874 .name = "4bit" 875 .ctrl_dev_name = "pinctrl-foo", 876 .function = "mmc0", 877 .group = "mmc0_2_grp", 878 .dev_name = "foo-mmc.0", 879}, 880{ 881 .name = "8bit" 882 .ctrl_dev_name = "pinctrl-foo", 883 .group = "mmc0_1_grp", 884 .dev_name = "foo-mmc.0", 885}, 886{ 887 .name = "8bit" 888 .ctrl_dev_name = "pinctrl-foo", 889 .function = "mmc0", 890 .group = "mmc0_2_grp", 891 .dev_name = "foo-mmc.0", 892}, 893{ 894 .name = "8bit" 895 .ctrl_dev_name = "pinctrl-foo", 896 .function = "mmc0", 897 .group = "mmc0_3_grp", 898 .dev_name = "foo-mmc.0", 899}, 900... 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{ 997 .name = "POWERMAP" 998 .ctrl_dev_name = "pinctrl-foo", 999 .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{ 1027 struct pinmux *pmx; 1028 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. 1048