1456 lines · plain
1===============================2PINCTRL (PIN CONTROL) subsystem3===============================4 5This document outlines the pin control subsystem in Linux6 7This subsystem deals with:8 9- Enumerating and naming controllable pins10 11- Multiplexing of pins, pads, fingers (etc) see below for details12 13- Configuration of pins, pads, fingers (etc), such as software-controlled14 biasing and driving mode specific pins, such as pull-up, pull-down, open drain,15 load capacitance etc.16 17Top-level interface18===================19 20Definitions:21 22- A PIN CONTROLLER is a piece of hardware, usually a set of registers, that23 can control PINs. It may be able to multiplex, bias, set load capacitance,24 set drive strength, etc. for individual pins or groups of pins.25 26- PINS are equal to pads, fingers, balls or whatever packaging input or27 output line you want to control and these are denoted by unsigned integers28 in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so29 there may be several such number spaces in a system. This pin space may30 be sparse - i.e. there may be gaps in the space with numbers where no31 pin exists.32 33When a PIN CONTROLLER is instantiated, it will register a descriptor to the34pin control framework, and this descriptor contains an array of pin descriptors35describing the pins handled by this specific pin controller.36 37Here is an example of a PGA (Pin Grid Array) chip seen from underneath::38 39 A B C D E F G H40 41 8 o o o o o o o o42 43 7 o o o o o o o o44 45 6 o o o o o o o o46 47 5 o o o o o o o o48 49 4 o o o o o o o o50 51 3 o o o o o o o o52 53 2 o o o o o o o o54 55 1 o o o o o o o o56 57To register a pin controller and name all the pins on this package we can do58this in our driver:59 60.. code-block:: c61 62 #include <linux/pinctrl/pinctrl.h>63 64 const struct pinctrl_pin_desc foo_pins[] = {65 PINCTRL_PIN(0, "A8"),66 PINCTRL_PIN(1, "B8"),67 PINCTRL_PIN(2, "C8"),68 ...69 PINCTRL_PIN(61, "F1"),70 PINCTRL_PIN(62, "G1"),71 PINCTRL_PIN(63, "H1"),72 };73 74 static struct pinctrl_desc foo_desc = {75 .name = "foo",76 .pins = foo_pins,77 .npins = ARRAY_SIZE(foo_pins),78 .owner = THIS_MODULE,79 };80 81 int __init foo_init(void)82 {83 int error;84 85 struct pinctrl_dev *pctl;86 87 error = pinctrl_register_and_init(&foo_desc, <PARENT>, NULL, &pctl);88 if (error)89 return error;90 91 return pinctrl_enable(pctl);92 }93 94To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and95selected drivers, you need to select them from your machine's Kconfig entry,96since these are so tightly integrated with the machines they are used on.97See ``arch/arm/mach-ux500/Kconfig`` for an example.98 99Pins usually have fancier names than this. You can find these in the datasheet100for your chip. Notice that the core pinctrl.h file provides a fancy macro101called ``PINCTRL_PIN()`` to create the struct entries. As you can see the pins are102enumerated from 0 in the upper left corner to 63 in the lower right corner.103This enumeration was arbitrarily chosen, in practice you need to think104through your numbering system so that it matches the layout of registers105and such things in your driver, or the code may become complicated. You must106also consider matching of offsets to the GPIO ranges that may be handled by107the pin controller.108 109For a padding with 467 pads, as opposed to actual pins, the enumeration will110be like this, walking around the edge of the chip, which seems to be industry111standard too (all these pads had names, too)::112 113 114 0 ..... 104115 466 105116 . .117 . .118 358 224119 357 .... 225120 121 122Pin groups123==========124 125Many controllers need to deal with groups of pins, so the pin controller126subsystem has a mechanism for enumerating groups of pins and retrieving the127actual enumerated pins that are part of a certain group.128 129For example, say that we have a group of pins dealing with an SPI interface130on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins131on { 24, 25 }.132 133These two groups are presented to the pin control subsystem by implementing134some generic ``pinctrl_ops`` like this:135 136.. code-block:: c137 138 #include <linux/pinctrl/pinctrl.h>139 140 static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };141 static const unsigned int i2c0_pins[] = { 24, 25 };142 143 static const struct pingroup foo_groups[] = {144 PINCTRL_PINGROUP("spi0_grp", spi0_pins, ARRAY_SIZE(spi0_pins)),145 PINCTRL_PINGROUP("i2c0_grp", i2c0_pins, ARRAY_SIZE(i2c0_pins)),146 };147 148 static int foo_get_groups_count(struct pinctrl_dev *pctldev)149 {150 return ARRAY_SIZE(foo_groups);151 }152 153 static const char *foo_get_group_name(struct pinctrl_dev *pctldev,154 unsigned int selector)155 {156 return foo_groups[selector].name;157 }158 159 static int foo_get_group_pins(struct pinctrl_dev *pctldev,160 unsigned int selector,161 const unsigned int **pins,162 unsigned int *npins)163 {164 *pins = foo_groups[selector].pins;165 *npins = foo_groups[selector].npins;166 return 0;167 }168 169 static struct pinctrl_ops foo_pctrl_ops = {170 .get_groups_count = foo_get_groups_count,171 .get_group_name = foo_get_group_name,172 .get_group_pins = foo_get_group_pins,173 };174 175 static struct pinctrl_desc foo_desc = {176 ...177 .pctlops = &foo_pctrl_ops,178 };179 180The pin control subsystem will call the ``.get_groups_count()`` function to181determine the total number of legal selectors, then it will call the other functions182to retrieve the name and pins of the group. Maintaining the data structure of183the groups is up to the driver, this is just a simple example - in practice you184may need more entries in your group structure, for example specific register185ranges associated with each group and so on.186 187 188Pin configuration189=================190 191Pins can sometimes be software-configured in various ways, mostly related192to their electronic properties when used as inputs or outputs. For example you193may be able to make an output pin high impedance (Hi-Z), or "tristate" meaning it is194effectively disconnected. You may be able to connect an input pin to VDD or GND195using a certain resistor value - pull up and pull down - so that the pin has a196stable value when nothing is driving the rail it is connected to, or when it's197unconnected.198 199Pin configuration can be programmed by adding configuration entries into the200mapping table; see section `Board/machine configuration`_ below.201 202The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP203above, is entirely defined by the pin controller driver.204 205The pin configuration driver implements callbacks for changing pin206configuration in the pin controller ops like this:207 208.. code-block:: c209 210 #include <linux/pinctrl/pinconf.h>211 #include <linux/pinctrl/pinctrl.h>212 213 #include "platform_x_pindefs.h"214 215 static int foo_pin_config_get(struct pinctrl_dev *pctldev,216 unsigned int offset,217 unsigned long *config)218 {219 struct my_conftype conf;220 221 /* ... Find setting for pin @ offset ... */222 223 *config = (unsigned long) conf;224 }225 226 static int foo_pin_config_set(struct pinctrl_dev *pctldev,227 unsigned int offset,228 unsigned long config)229 {230 struct my_conftype *conf = (struct my_conftype *) config;231 232 switch (conf) {233 case PLATFORM_X_PULL_UP:234 ...235 break;236 }237 }238 239 static int foo_pin_config_group_get(struct pinctrl_dev *pctldev,240 unsigned selector,241 unsigned long *config)242 {243 ...244 }245 246 static int foo_pin_config_group_set(struct pinctrl_dev *pctldev,247 unsigned selector,248 unsigned long config)249 {250 ...251 }252 253 static struct pinconf_ops foo_pconf_ops = {254 .pin_config_get = foo_pin_config_get,255 .pin_config_set = foo_pin_config_set,256 .pin_config_group_get = foo_pin_config_group_get,257 .pin_config_group_set = foo_pin_config_group_set,258 };259 260 /* Pin config operations are handled by some pin controller */261 static struct pinctrl_desc foo_desc = {262 ...263 .confops = &foo_pconf_ops,264 };265 266Interaction with the GPIO subsystem267===================================268 269The GPIO drivers may want to perform operations of various types on the same270physical pins that are also registered as pin controller pins.271 272First and foremost, the two subsystems can be used as completely orthogonal,273see the section named `Pin control requests from drivers`_ and274`Drivers needing both pin control and GPIOs`_ below for details. But in some275situations a cross-subsystem mapping between pins and GPIOs is needed.276 277Since the pin controller subsystem has its pinspace local to the pin controller278we need a mapping so that the pin control subsystem can figure out which pin279controller handles control of a certain GPIO pin. Since a single pin controller280may be muxing several GPIO ranges (typically SoCs that have one set of pins,281but internally several GPIO silicon blocks, each modelled as a struct282gpio_chip) any number of GPIO ranges can be added to a pin controller instance283like this:284 285.. code-block:: c286 287 #include <linux/gpio/driver.h>288 289 #include <linux/pinctrl/pinctrl.h>290 291 struct gpio_chip chip_a;292 struct gpio_chip chip_b;293 294 static struct pinctrl_gpio_range gpio_range_a = {295 .name = "chip a",296 .id = 0,297 .base = 32,298 .pin_base = 32,299 .npins = 16,300 .gc = &chip_a,301 };302 303 static struct pinctrl_gpio_range gpio_range_b = {304 .name = "chip b",305 .id = 0,306 .base = 48,307 .pin_base = 64,308 .npins = 8,309 .gc = &chip_b;310 };311 312 int __init foo_init(void)313 {314 struct pinctrl_dev *pctl;315 ...316 pinctrl_add_gpio_range(pctl, &gpio_range_a);317 pinctrl_add_gpio_range(pctl, &gpio_range_b);318 ...319 }320 321So this complex system has one pin controller handling two different322GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and323"chip b" have different ``pin_base``, which means a start pin number of the324GPIO range.325 326The GPIO range of "chip a" starts from the GPIO base of 32 and actual327pin range also starts from 32. However "chip b" has different starting328offset for the GPIO range and pin range. The GPIO range of "chip b" starts329from GPIO number 48, while the pin range of "chip b" starts from 64.330 331We can convert a gpio number to actual pin number using this ``pin_base``.332They are mapped in the global GPIO pin space at:333 334chip a:335 - GPIO range : [32 .. 47]336 - pin range : [32 .. 47]337chip b:338 - GPIO range : [48 .. 55]339 - pin range : [64 .. 71]340 341The above examples assume the mapping between the GPIOs and pins is342linear. If the mapping is sparse or haphazard, an array of arbitrary pin343numbers can be encoded in the range like this:344 345.. code-block:: c346 347 static const unsigned int range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };348 349 static struct pinctrl_gpio_range gpio_range = {350 .name = "chip",351 .id = 0,352 .base = 32,353 .pins = &range_pins,354 .npins = ARRAY_SIZE(range_pins),355 .gc = &chip,356 };357 358In this case the ``pin_base`` property will be ignored. If the name of a pin359group is known, the pins and npins elements of the above structure can be360initialised using the function ``pinctrl_get_group_pins()``, e.g. for pin361group "foo":362 363.. code-block:: c364 365 pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins);366 367When GPIO-specific functions in the pin control subsystem are called, these368ranges will be used to look up the appropriate pin controller by inspecting369and matching the pin to the pin ranges across all controllers. When a370pin controller handling the matching range is found, GPIO-specific functions371will be called on that specific pin controller.372 373For all functionalities dealing with pin biasing, pin muxing etc, the pin374controller subsystem will look up the corresponding pin number from the passed375in gpio number, and use the range's internals to retrieve a pin number. After376that, the subsystem passes it on to the pin control driver, so the driver377will get a pin number into its handled number range. Further it is also passed378the range ID value, so that the pin controller knows which range it should379deal with.380 381Calling ``pinctrl_add_gpio_range()`` from pinctrl driver is DEPRECATED. Please see382section 2.1 of ``Documentation/devicetree/bindings/gpio/gpio.txt`` on how to bind383pinctrl and gpio drivers.384 385 386PINMUX interfaces387=================388 389These calls use the pinmux_* naming prefix. No other calls should use that390prefix.391 392 393What is pinmuxing?394==================395 396PINMUX, also known as padmux, ballmux, alternate functions or mission modes397is a way for chip vendors producing some kind of electrical packages to use398a certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive399functions, depending on the application. By "application" in this context400we usually mean a way of soldering or wiring the package into an electronic401system, even though the framework makes it possible to also change the function402at runtime.403 404Here is an example of a PGA (Pin Grid Array) chip seen from underneath::405 406 A B C D E F G H407 +---+408 8 | o | o o o o o o o409 | |410 7 | o | o o o o o o o411 | |412 6 | o | o o o o o o o413 +---+---+414 5 | o | o | o o o o o o415 +---+---+ +---+416 4 o o o o o o | o | o417 | |418 3 o o o o o o | o | o419 | |420 2 o o o o o o | o | o421 +-------+-------+-------+---+---+422 1 | o o | o o | o o | o | o |423 +-------+-------+-------+---+---+424 425This is not tetris. The game to think of is chess. Not all PGA/BGA packages426are chessboard-like, big ones have "holes" in some arrangement according to427different design patterns, but we're using this as a simple example. Of the428pins you see some will be taken by things like a few VCC and GND to feed power429to the chip, and quite a few will be taken by large ports like an external430memory interface. The remaining pins will often be subject to pin multiplexing.431 432The example 8x8 PGA package above will have pin numbers 0 through 63 assigned433to its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using434pinctrl_register_pins() and a suitable data set as shown earlier.435 436In this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port437(these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as438some general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can439be used as an I2C port (these are just two pins: SCL, SDA). Needless to say,440we cannot use the SPI port and I2C port at the same time. However in the inside441of the package the silicon performing the SPI logic can alternatively be routed442out on pins { G4, G3, G2, G1 }.443 444On the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something445special - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will446consume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or447{ A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI448port on pins { G4, G3, G2, G1 } of course.449 450This way the silicon blocks present inside the chip can be multiplexed "muxed"451out on different pin ranges. Often contemporary SoC (systems on chip) will452contain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to453different pins by pinmux settings.454 455Since general-purpose I/O pins (GPIO) are typically always in shortage, it is456common to be able to use almost any pin as a GPIO pin if it is not currently457in use by some other I/O port.458 459 460Pinmux conventions461==================462 463The purpose of the pinmux functionality in the pin controller subsystem is to464abstract and provide pinmux settings to the devices you choose to instantiate465in your machine configuration. It is inspired by the clk, GPIO and regulator466subsystems, so devices will request their mux setting, but it's also possible467to request a single pin for e.g. GPIO.468 469The conventions are:470 471- FUNCTIONS can be switched in and out by a driver residing with the pin472 control subsystem in the ``drivers/pinctrl`` directory of the kernel. The473 pin control driver knows the possible functions. In the example above you can474 identify three pinmux functions, one for spi, one for i2c and one for mmc.475 476- FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array.477 In this case the array could be something like: { spi0, i2c0, mmc0 }478 for the three available functions.479 480- FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain481 function is *always* associated with a certain set of pin groups, could482 be just a single one, but could also be many. In the example above the483 function i2c is associated with the pins { A5, B5 }, enumerated as484 { 24, 25 } in the controller pin space.485 486 The Function spi is associated with pin groups { A8, A7, A6, A5 }487 and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and488 { 38, 46, 54, 62 } respectively.489 490 Group names must be unique per pin controller, no two groups on the same491 controller may have the same name.492 493- The combination of a FUNCTION and a PIN GROUP determine a certain function494 for a certain set of pins. The knowledge of the functions and pin groups495 and their machine-specific particulars are kept inside the pinmux driver,496 from the outside only the enumerators are known, and the driver core can497 request:498 499 - The name of a function with a certain selector (>= 0)500 - A list of groups associated with a certain function501 - That a certain group in that list to be activated for a certain function502 503 As already described above, pin groups are in turn self-descriptive, so504 the core will retrieve the actual pin range in a certain group from the505 driver.506 507- FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain508 device by the board file, device tree or similar machine setup configuration509 mechanism, similar to how regulators are connected to devices, usually by510 name. Defining a pin controller, function and group thus uniquely identify511 the set of pins to be used by a certain device. (If only one possible group512 of pins is available for the function, no group name need to be supplied -513 the core will simply select the first and only group available.)514 515 In the example case we can define that this particular machine shall516 use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function517 fi2c0 group gi2c0, on the primary pin controller, we get mappings518 like these:519 520 .. code-block:: c521 522 {523 {"map-spi0", spi0, pinctrl0, fspi0, gspi0},524 {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0},525 }526 527 Every map must be assigned a state name, pin controller, device and528 function. The group is not compulsory - if it is omitted the first group529 presented by the driver as applicable for the function will be selected,530 which is useful for simple cases.531 532 It is possible to map several groups to the same combination of device,533 pin controller and function. This is for cases where a certain function on534 a certain pin controller may use different sets of pins in different535 configurations.536 537- PINS for a certain FUNCTION using a certain PIN GROUP on a certain538 PIN CONTROLLER are provided on a first-come first-serve basis, so if some539 other device mux setting or GPIO pin request has already taken your physical540 pin, you will be denied the use of it. To get (activate) a new setting, the541 old one has to be put (deactivated) first.542 543Sometimes the documentation and hardware registers will be oriented around544pads (or "fingers") rather than pins - these are the soldering surfaces on the545silicon inside the package, and may or may not match the actual number of546pins/balls underneath the capsule. Pick some enumeration that makes sense to547you. Define enumerators only for the pins you can control if that makes sense.548 549Assumptions:550 551We assume that the number of possible function maps to pin groups is limited by552the hardware. I.e. we assume that there is no system where any function can be553mapped to any pin, like in a phone exchange. So the available pin groups for554a certain function will be limited to a few choices (say up to eight or so),555not hundreds or any amount of choices. This is the characteristic we have found556by inspecting available pinmux hardware, and a necessary assumption since we557expect pinmux drivers to present *all* possible function vs pin group mappings558to the subsystem.559 560 561Pinmux drivers562==============563 564The pinmux core takes care of preventing conflicts on pins and calling565the pin controller driver to execute different settings.566 567It is the responsibility of the pinmux driver to impose further restrictions568(say for example infer electronic limitations due to load, etc.) to determine569whether or not the requested function can actually be allowed, and in case it570is possible to perform the requested mux setting, poke the hardware so that571this happens.572 573Pinmux drivers are required to supply a few callback functions, some are574optional. Usually the ``.set_mux()`` function is implemented, writing values into575some certain registers to activate a certain mux setting for a certain pin.576 577A simple driver for the above example will work by setting bits 0, 1, 2, 3, 4, or 5578into some register named MUX to select a certain function with a certain579group of pins would work something like this:580 581.. code-block:: c582 583 #include <linux/pinctrl/pinctrl.h>584 #include <linux/pinctrl/pinmux.h>585 586 static const unsigned int spi0_0_pins[] = { 0, 8, 16, 24 };587 static const unsigned int spi0_1_pins[] = { 38, 46, 54, 62 };588 static const unsigned int i2c0_pins[] = { 24, 25 };589 static const unsigned int mmc0_1_pins[] = { 56, 57 };590 static const unsigned int mmc0_2_pins[] = { 58, 59 };591 static const unsigned int mmc0_3_pins[] = { 60, 61, 62, 63 };592 593 static const struct pingroup foo_groups[] = {594 PINCTRL_PINGROUP("spi0_0_grp", spi0_0_pins, ARRAY_SIZE(spi0_0_pins)),595 PINCTRL_PINGROUP("spi0_1_grp", spi0_1_pins, ARRAY_SIZE(spi0_1_pins)),596 PINCTRL_PINGROUP("i2c0_grp", i2c0_pins, ARRAY_SIZE(i2c0_pins)),597 PINCTRL_PINGROUP("mmc0_1_grp", mmc0_1_pins, ARRAY_SIZE(mmc0_1_pins)),598 PINCTRL_PINGROUP("mmc0_2_grp", mmc0_2_pins, ARRAY_SIZE(mmc0_2_pins)),599 PINCTRL_PINGROUP("mmc0_3_grp", mmc0_3_pins, ARRAY_SIZE(mmc0_3_pins)),600 };601 602 static int foo_get_groups_count(struct pinctrl_dev *pctldev)603 {604 return ARRAY_SIZE(foo_groups);605 }606 607 static const char *foo_get_group_name(struct pinctrl_dev *pctldev,608 unsigned int selector)609 {610 return foo_groups[selector].name;611 }612 613 static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned int selector,614 const unsigned int **pins,615 unsigned int *npins)616 {617 *pins = foo_groups[selector].pins;618 *npins = foo_groups[selector].npins;619 return 0;620 }621 622 static struct pinctrl_ops foo_pctrl_ops = {623 .get_groups_count = foo_get_groups_count,624 .get_group_name = foo_get_group_name,625 .get_group_pins = foo_get_group_pins,626 };627 628 static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };629 static const char * const i2c0_groups[] = { "i2c0_grp" };630 static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", "mmc0_3_grp" };631 632 static const struct pinfunction foo_functions[] = {633 PINCTRL_PINFUNCTION("spi0", spi0_groups, ARRAY_SIZE(spi0_groups)),634 PINCTRL_PINFUNCTION("i2c0", i2c0_groups, ARRAY_SIZE(i2c0_groups)),635 PINCTRL_PINFUNCTION("mmc0", mmc0_groups, ARRAY_SIZE(mmc0_groups)),636 };637 638 static int foo_get_functions_count(struct pinctrl_dev *pctldev)639 {640 return ARRAY_SIZE(foo_functions);641 }642 643 static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned int selector)644 {645 return foo_functions[selector].name;646 }647 648 static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned int selector,649 const char * const **groups,650 unsigned int * const ngroups)651 {652 *groups = foo_functions[selector].groups;653 *ngroups = foo_functions[selector].ngroups;654 return 0;655 }656 657 static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned int selector,658 unsigned int group)659 {660 u8 regbit = BIT(group);661 662 writeb((readb(MUX) | regbit), MUX);663 return 0;664 }665 666 static struct pinmux_ops foo_pmxops = {667 .get_functions_count = foo_get_functions_count,668 .get_function_name = foo_get_fname,669 .get_function_groups = foo_get_groups,670 .set_mux = foo_set_mux,671 .strict = true,672 };673 674 /* Pinmux operations are handled by some pin controller */675 static struct pinctrl_desc foo_desc = {676 ...677 .pctlops = &foo_pctrl_ops,678 .pmxops = &foo_pmxops,679 };680 681In the example activating muxing 0 and 2 at the same time setting bits6820 and 2, uses pin 24 in common so they would collide. All the same for683the muxes 1 and 5, which have pin 62 in common.684 685The beauty of the pinmux subsystem is that since it keeps track of all686pins and who is using them, it will already have denied an impossible687request like that, so the driver does not need to worry about such688things - when it gets a selector passed in, the pinmux subsystem makes689sure no other device or GPIO assignment is already using the selected690pins. Thus bits 0 and 2, or 1 and 5 in the control register will never691be set at the same time.692 693All the above functions are mandatory to implement for a pinmux driver.694 695 696Pin control interaction with the GPIO subsystem697===============================================698 699Note that the following implies that the use case is to use a certain pin700from the Linux kernel using the API in ``<linux/gpio/consumer.h>`` with gpiod_get()701and similar functions. There are cases where you may be using something702that your datasheet calls "GPIO mode", but actually is just an electrical703configuration for a certain device. See the section below named704`GPIO mode pitfalls`_ for more details on this scenario.705 706The public pinmux API contains two functions named ``pinctrl_gpio_request()``707and ``pinctrl_gpio_free()``. These two functions shall *ONLY* be called from708gpiolib-based drivers as part of their ``.request()`` and ``.free()`` semantics.709Likewise the ``pinctrl_gpio_direction_input()`` / ``pinctrl_gpio_direction_output()``710shall only be called from within respective ``.direction_input()`` /711``.direction_output()`` gpiolib implementation.712 713NOTE that platforms and individual drivers shall *NOT* request GPIO pins to be714controlled e.g. muxed in. Instead, implement a proper gpiolib driver and have715that driver request proper muxing and other control for its pins.716 717The function list could become long, especially if you can convert every718individual pin into a GPIO pin independent of any other pins, and then try719the approach to define every pin as a function.720 721In this case, the function array would become 64 entries for each GPIO722setting and then the device functions.723 724For this reason there are two functions a pin control driver can implement725to enable only GPIO on an individual pin: ``.gpio_request_enable()`` and726``.gpio_disable_free()``.727 728This function will pass in the affected GPIO range identified by the pin729controller core, so you know which GPIO pins are being affected by the request730operation.731 732If your driver needs to have an indication from the framework of whether the733GPIO pin shall be used for input or output you can implement the734``.gpio_set_direction()`` function. As described this shall be called from the735gpiolib driver and the affected GPIO range, pin offset and desired direction736will be passed along to this function.737 738Alternatively to using these special functions, it is fully allowed to use739named functions for each GPIO pin, the ``pinctrl_gpio_request()`` will attempt to740obtain the function "gpioN" where "N" is the global GPIO pin number if no741special GPIO-handler is registered.742 743 744GPIO mode pitfalls745==================746 747Due to the naming conventions used by hardware engineers, where "GPIO"748is taken to mean different things than what the kernel does, the developer749may be confused by a datasheet talking about a pin being possible to set750into "GPIO mode". It appears that what hardware engineers mean with751"GPIO mode" is not necessarily the use case that is implied in the kernel752interface ``<linux/gpio/consumer.h>``: a pin that you grab from kernel code and then753either listen for input or drive high/low to assert/deassert some754external line.755 756Rather hardware engineers think that "GPIO mode" means that you can757software-control a few electrical properties of the pin that you would758not be able to control if the pin was in some other mode, such as muxed in759for a device.760 761The GPIO portions of a pin and its relation to a certain pin controller762configuration and muxing logic can be constructed in several ways. Here763are two examples.764 765Example **(A)**::766 767 pin config768 logic regs769 | +- SPI770 Physical pins --- pad --- pinmux -+- I2C771 | +- mmc772 | +- GPIO773 pin774 multiplex775 logic regs776 777Here some electrical properties of the pin can be configured no matter778whether the pin is used for GPIO or not. If you multiplex a GPIO onto a779pin, you can also drive it high/low from "GPIO" registers.780Alternatively, the pin can be controlled by a certain peripheral, while781still applying desired pin config properties. GPIO functionality is thus782orthogonal to any other device using the pin.783 784In this arrangement the registers for the GPIO portions of the pin controller,785or the registers for the GPIO hardware module are likely to reside in a786separate memory range only intended for GPIO driving, and the register787range dealing with pin config and pin multiplexing get placed into a788different memory range and a separate section of the data sheet.789 790A flag "strict" in struct pinmux_ops is available to check and deny791simultaneous access to the same pin from GPIO and pin multiplexing792consumers on hardware of this type. The pinctrl driver should set this flag793accordingly.794 795Example **(B)**::796 797 pin config798 logic regs799 | +- SPI800 Physical pins --- pad --- pinmux -+- I2C801 | | +- mmc802 | |803 GPIO pin804 multiplex805 logic regs806 807In this arrangement, the GPIO functionality can always be enabled, such that808e.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is809pulsed out. It is likely possible to disrupt the traffic on the pin by doing810wrong things on the GPIO block, as it is never really disconnected. It is811possible that the GPIO, pin config and pin multiplex registers are placed into812the same memory range and the same section of the data sheet, although that813need not be the case.814 815In some pin controllers, although the physical pins are designed in the same816way as (B), the GPIO function still can't be enabled at the same time as the817peripheral functions. So again the "strict" flag should be set, denying818simultaneous activation by GPIO and other muxed in devices.819 820From a kernel point of view, however, these are different aspects of the821hardware and shall be put into different subsystems:822 823- Registers (or fields within registers) that control electrical824 properties of the pin such as biasing and drive strength should be825 exposed through the pinctrl subsystem, as "pin configuration" settings.826 827- Registers (or fields within registers) that control muxing of signals828 from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should829 be exposed through the pinctrl subsystem, as mux functions.830 831- Registers (or fields within registers) that control GPIO functionality832 such as setting a GPIO's output value, reading a GPIO's input value, or833 setting GPIO pin direction should be exposed through the GPIO subsystem,834 and if they also support interrupt capabilities, through the irqchip835 abstraction.836 837Depending on the exact HW register design, some functions exposed by the838GPIO subsystem may call into the pinctrl subsystem in order to839coordinate register settings across HW modules. In particular, this may840be needed for HW with separate GPIO and pin controller HW modules, where841e.g. GPIO direction is determined by a register in the pin controller HW842module rather than the GPIO HW module.843 844Electrical properties of the pin such as biasing and drive strength845may be placed at some pin-specific register in all cases or as part846of the GPIO register in case (B) especially. This doesn't mean that such847properties necessarily pertain to what the Linux kernel calls "GPIO".848 849Example: a pin is usually muxed in to be used as a UART TX line. But during850system sleep, we need to put this pin into "GPIO mode" and ground it.851 852If you make a 1-to-1 map to the GPIO subsystem for this pin, you may start853to think that you need to come up with something really complex, that the854pin shall be used for UART TX and GPIO at the same time, that you will grab855a pin control handle and set it to a certain state to enable UART TX to be856muxed in, then twist it over to GPIO mode and use gpiod_direction_output()857to drive it low during sleep, then mux it over to UART TX again when you858wake up and maybe even gpiod_get() / gpiod_put() as part of this cycle. This859all gets very complicated.860 861The solution is to not think that what the datasheet calls "GPIO mode"862has to be handled by the ``<linux/gpio/consumer.h>`` interface. Instead view this as863a certain pin config setting. Look in e.g. ``<linux/pinctrl/pinconf-generic.h>``864and you find this in the documentation:865 866 PIN_CONFIG_OUTPUT:867 this will configure the pin in output, use argument868 1 to indicate high level, argument 0 to indicate low level.869 870So it is perfectly possible to push a pin into "GPIO mode" and drive the871line low as part of the usual pin control map. So for example your UART872driver may look like this:873 874.. code-block:: c875 876 #include <linux/pinctrl/consumer.h>877 878 struct pinctrl *pinctrl;879 struct pinctrl_state *pins_default;880 struct pinctrl_state *pins_sleep;881 882 pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);883 pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);884 885 /* Normal mode */886 retval = pinctrl_select_state(pinctrl, pins_default);887 888 /* Sleep mode */889 retval = pinctrl_select_state(pinctrl, pins_sleep);890 891And your machine configuration may look like this:892 893.. code-block:: c894 895 static unsigned long uart_default_mode[] = {896 PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),897 };898 899 static unsigned long uart_sleep_mode[] = {900 PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),901 };902 903 static struct pinctrl_map pinmap[] __initdata = {904 PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",905 "u0_group", "u0"),906 PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",907 "UART_TX_PIN", uart_default_mode),908 PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",909 "u0_group", "gpio-mode"),910 PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",911 "UART_TX_PIN", uart_sleep_mode),912 };913 914 foo_init(void)915 {916 pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));917 }918 919Here the pins we want to control are in the "u0_group" and there is some920function called "u0" that can be enabled on this group of pins, and then921everything is UART business as usual. But there is also some function922named "gpio-mode" that can be mapped onto the same pins to move them into923GPIO mode.924 925This will give the desired effect without any bogus interaction with the926GPIO subsystem. It is just an electrical configuration used by that device927when going to sleep, it might imply that the pin is set into something the928datasheet calls "GPIO mode", but that is not the point: it is still used929by that UART device to control the pins that pertain to that very UART930driver, putting them into modes needed by the UART. GPIO in the Linux931kernel sense are just some 1-bit line, and is a different use case.932 933How the registers are poked to attain the push or pull, and output low934configuration and the muxing of the "u0" or "gpio-mode" group onto these935pins is a question for the driver.936 937Some datasheets will be more helpful and refer to the "GPIO mode" as938"low power mode" rather than anything to do with GPIO. This often means939the same thing electrically speaking, but in this latter case the940software engineers will usually quickly identify that this is some941specific muxing or configuration rather than anything related to the GPIO942API.943 944 945Board/machine configuration946===========================947 948Boards and machines define how a certain complete running system is put949together, including how GPIOs and devices are muxed, how regulators are950constrained and how the clock tree looks. Of course pinmux settings are also951part of this.952 953A pin controller configuration for a machine looks pretty much like a simple954regulator configuration, so for the example array above we want to enable i2c955and spi on the second function mapping:956 957.. code-block:: c958 959 #include <linux/pinctrl/machine.h>960 961 static const struct pinctrl_map mapping[] __initconst = {962 {963 .dev_name = "foo-spi.0",964 .name = PINCTRL_STATE_DEFAULT,965 .type = PIN_MAP_TYPE_MUX_GROUP,966 .ctrl_dev_name = "pinctrl-foo",967 .data.mux.function = "spi0",968 },969 {970 .dev_name = "foo-i2c.0",971 .name = PINCTRL_STATE_DEFAULT,972 .type = PIN_MAP_TYPE_MUX_GROUP,973 .ctrl_dev_name = "pinctrl-foo",974 .data.mux.function = "i2c0",975 },976 {977 .dev_name = "foo-mmc.0",978 .name = PINCTRL_STATE_DEFAULT,979 .type = PIN_MAP_TYPE_MUX_GROUP,980 .ctrl_dev_name = "pinctrl-foo",981 .data.mux.function = "mmc0",982 },983 };984 985The dev_name here matches to the unique device name that can be used to look986up the device struct (just like with clockdev or regulators). The function name987must match a function provided by the pinmux driver handling this pin range.988 989As you can see we may have several pin controllers on the system and thus990we need to specify which one of them contains the functions we wish to map.991 992You register this pinmux mapping to the pinmux subsystem by simply:993 994.. code-block:: c995 996 ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));997 998Since the above construct is pretty common there is a helper macro to make999it even more compact which assumes you want to use pinctrl-foo and position10000 for mapping, for example:1001 1002.. code-block:: c1003 1004 static struct pinctrl_map mapping[] __initdata = {1005 PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,1006 "pinctrl-foo", NULL, "i2c0"),1007 };1008 1009The mapping table may also contain pin configuration entries. It's common for1010each pin/group to have a number of configuration entries that affect it, so1011the table entries for configuration reference an array of config parameters1012and values. An example using the convenience macros is shown below:1013 1014.. code-block:: c1015 1016 static unsigned long i2c_grp_configs[] = {1017 FOO_PIN_DRIVEN,1018 FOO_PIN_PULLUP,1019 };1020 1021 static unsigned long i2c_pin_configs[] = {1022 FOO_OPEN_COLLECTOR,1023 FOO_SLEW_RATE_SLOW,1024 };1025 1026 static struct pinctrl_map mapping[] __initdata = {1027 PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,1028 "pinctrl-foo", "i2c0", "i2c0"),1029 PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,1030 "pinctrl-foo", "i2c0", i2c_grp_configs),1031 PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,1032 "pinctrl-foo", "i2c0scl", i2c_pin_configs),1033 PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,1034 "pinctrl-foo", "i2c0sda", i2c_pin_configs),1035 };1036 1037Finally, some devices expect the mapping table to contain certain specific1038named states. When running on hardware that doesn't need any pin controller1039configuration, the mapping table must still contain those named states, in1040order to explicitly indicate that the states were provided and intended to1041be empty. Table entry macro ``PIN_MAP_DUMMY_STATE()`` serves the purpose of defining1042a named state without causing any pin controller to be programmed:1043 1044.. code-block:: c1045 1046 static struct pinctrl_map mapping[] __initdata = {1047 PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),1048 };1049 1050 1051Complex mappings1052================1053 1054As it is possible to map a function to different groups of pins an optional1055.group can be specified like this:1056 1057.. code-block:: c1058 1059 ...1060 {1061 .dev_name = "foo-spi.0",1062 .name = "spi0-pos-A",1063 .type = PIN_MAP_TYPE_MUX_GROUP,1064 .ctrl_dev_name = "pinctrl-foo",1065 .function = "spi0",1066 .group = "spi0_0_grp",1067 },1068 {1069 .dev_name = "foo-spi.0",1070 .name = "spi0-pos-B",1071 .type = PIN_MAP_TYPE_MUX_GROUP,1072 .ctrl_dev_name = "pinctrl-foo",1073 .function = "spi0",1074 .group = "spi0_1_grp",1075 },1076 ...1077 1078This example mapping is used to switch between two positions for spi0 at1079runtime, as described further below under the heading `Runtime pinmuxing`_.1080 1081Further it is possible for one named state to affect the muxing of several1082groups of pins, say for example in the mmc0 example above, where you can1083additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all1084three groups for a total of 2 + 2 + 4 = 8 pins (for an 8-bit MMC bus as is the1085case), we define a mapping like this:1086 1087.. code-block:: c1088 1089 ...1090 {1091 .dev_name = "foo-mmc.0",1092 .name = "2bit"1093 .type = PIN_MAP_TYPE_MUX_GROUP,1094 .ctrl_dev_name = "pinctrl-foo",1095 .function = "mmc0",1096 .group = "mmc0_1_grp",1097 },1098 {1099 .dev_name = "foo-mmc.0",1100 .name = "4bit"1101 .type = PIN_MAP_TYPE_MUX_GROUP,1102 .ctrl_dev_name = "pinctrl-foo",1103 .function = "mmc0",1104 .group = "mmc0_1_grp",1105 },1106 {1107 .dev_name = "foo-mmc.0",1108 .name = "4bit"1109 .type = PIN_MAP_TYPE_MUX_GROUP,1110 .ctrl_dev_name = "pinctrl-foo",1111 .function = "mmc0",1112 .group = "mmc0_2_grp",1113 },1114 {1115 .dev_name = "foo-mmc.0",1116 .name = "8bit"1117 .type = PIN_MAP_TYPE_MUX_GROUP,1118 .ctrl_dev_name = "pinctrl-foo",1119 .function = "mmc0",1120 .group = "mmc0_1_grp",1121 },1122 {1123 .dev_name = "foo-mmc.0",1124 .name = "8bit"1125 .type = PIN_MAP_TYPE_MUX_GROUP,1126 .ctrl_dev_name = "pinctrl-foo",1127 .function = "mmc0",1128 .group = "mmc0_2_grp",1129 },1130 {1131 .dev_name = "foo-mmc.0",1132 .name = "8bit"1133 .type = PIN_MAP_TYPE_MUX_GROUP,1134 .ctrl_dev_name = "pinctrl-foo",1135 .function = "mmc0",1136 .group = "mmc0_3_grp",1137 },1138 ...1139 1140The result of grabbing this mapping from the device with something like1141this (see next paragraph):1142 1143.. code-block:: c1144 1145 p = devm_pinctrl_get(dev);1146 s = pinctrl_lookup_state(p, "8bit");1147 ret = pinctrl_select_state(p, s);1148 1149or more simply:1150 1151.. code-block:: c1152 1153 p = devm_pinctrl_get_select(dev, "8bit");1154 1155Will be that you activate all the three bottom records in the mapping at1156once. Since they share the same name, pin controller device, function and1157device, and since we allow multiple groups to match to a single device, they1158all get selected, and they all get enabled and disable simultaneously by the1159pinmux core.1160 1161 1162Pin control requests from drivers1163=================================1164 1165When a device driver is about to probe the device core will automatically1166attempt to issue ``pinctrl_get_select_default()`` on these devices.1167This way driver writers do not need to add any of the boilerplate code1168of the type found below. However when doing fine-grained state selection1169and not using the "default" state, you may have to do some device driver1170handling of the pinctrl handles and states.1171 1172So if you just want to put the pins for a certain device into the default1173state and be done with it, there is nothing you need to do besides1174providing the proper mapping table. The device core will take care of1175the rest.1176 1177Generally it is discouraged to let individual drivers get and enable pin1178control. So if possible, handle the pin control in platform code or some other1179place where you have access to all the affected struct device * pointers. In1180some cases where a driver needs to e.g. switch between different mux mappings1181at runtime this is not possible.1182 1183A typical case is if a driver needs to switch bias of pins from normal1184operation and going to sleep, moving from the ``PINCTRL_STATE_DEFAULT`` to1185``PINCTRL_STATE_SLEEP`` at runtime, re-biasing or even re-muxing pins to save1186current in sleep mode.1187 1188A driver may request a certain control state to be activated, usually just the1189default state like this:1190 1191.. code-block:: c1192 1193 #include <linux/pinctrl/consumer.h>1194 1195 struct foo_state {1196 struct pinctrl *p;1197 struct pinctrl_state *s;1198 ...1199 };1200 1201 foo_probe()1202 {1203 /* Allocate a state holder named "foo" etc */1204 struct foo_state *foo = ...;1205 1206 foo->p = devm_pinctrl_get(&device);1207 if (IS_ERR(foo->p)) {1208 /* FIXME: clean up "foo" here */1209 return PTR_ERR(foo->p);1210 }1211 1212 foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);1213 if (IS_ERR(foo->s)) {1214 /* FIXME: clean up "foo" here */1215 return PTR_ERR(foo->s);1216 }1217 1218 ret = pinctrl_select_state(foo->p, foo->s);1219 if (ret < 0) {1220 /* FIXME: clean up "foo" here */1221 return ret;1222 }1223 }1224 1225This get/lookup/select/put sequence can just as well be handled by bus drivers1226if you don't want each and every driver to handle it and you know the1227arrangement on your bus.1228 1229The semantics of the pinctrl APIs are:1230 1231- ``pinctrl_get()`` is called in process context to obtain a handle to all pinctrl1232 information for a given client device. It will allocate a struct from the1233 kernel memory to hold the pinmux state. All mapping table parsing or similar1234 slow operations take place within this API.1235 1236- ``devm_pinctrl_get()`` is a variant of pinctrl_get() that causes ``pinctrl_put()``1237 to be called automatically on the retrieved pointer when the associated1238 device is removed. It is recommended to use this function over plain1239 ``pinctrl_get()``.1240 1241- ``pinctrl_lookup_state()`` is called in process context to obtain a handle to a1242 specific state for a client device. This operation may be slow, too.1243 1244- ``pinctrl_select_state()`` programs pin controller hardware according to the1245 definition of the state as given by the mapping table. In theory, this is a1246 fast-path operation, since it only involved blasting some register settings1247 into hardware. However, note that some pin controllers may have their1248 registers on a slow/IRQ-based bus, so client devices should not assume they1249 can call ``pinctrl_select_state()`` from non-blocking contexts.1250 1251- ``pinctrl_put()`` frees all information associated with a pinctrl handle.1252 1253- ``devm_pinctrl_put()`` is a variant of ``pinctrl_put()`` that may be used to1254 explicitly destroy a pinctrl object returned by ``devm_pinctrl_get()``.1255 However, use of this function will be rare, due to the automatic cleanup1256 that will occur even without calling it.1257 1258 ``pinctrl_get()`` must be paired with a plain ``pinctrl_put()``.1259 ``pinctrl_get()`` may not be paired with ``devm_pinctrl_put()``.1260 ``devm_pinctrl_get()`` can optionally be paired with ``devm_pinctrl_put()``.1261 ``devm_pinctrl_get()`` may not be paired with plain ``pinctrl_put()``.1262 1263Usually the pin control core handled the get/put pair and call out to the1264device drivers bookkeeping operations, like checking available functions and1265the associated pins, whereas ``pinctrl_select_state()`` pass on to the pin controller1266driver which takes care of activating and/or deactivating the mux setting by1267quickly poking some registers.1268 1269The pins are allocated for your device when you issue the ``devm_pinctrl_get()``1270call, after this you should be able to see this in the debugfs listing of all1271pins.1272 1273NOTE: the pinctrl system will return ``-EPROBE_DEFER`` if it cannot find the1274requested pinctrl handles, for example if the pinctrl driver has not yet1275registered. Thus make sure that the error path in your driver gracefully1276cleans up and is ready to retry the probing later in the startup process.1277 1278 1279Drivers needing both pin control and GPIOs1280==========================================1281 1282Again, it is discouraged to let drivers lookup and select pin control states1283themselves, but again sometimes this is unavoidable.1284 1285So say that your driver is fetching its resources like this:1286 1287.. code-block:: c1288 1289 #include <linux/pinctrl/consumer.h>1290 #include <linux/gpio/consumer.h>1291 1292 struct pinctrl *pinctrl;1293 struct gpio_desc *gpio;1294 1295 pinctrl = devm_pinctrl_get_select_default(&dev);1296 gpio = devm_gpiod_get(&dev, "foo");1297 1298Here we first request a certain pin state and then request GPIO "foo" to be1299used. If you're using the subsystems orthogonally like this, you should1300nominally always get your pinctrl handle and select the desired pinctrl1301state BEFORE requesting the GPIO. This is a semantic convention to avoid1302situations that can be electrically unpleasant, you will certainly want to1303mux in and bias pins in a certain way before the GPIO subsystems starts to1304deal with them.1305 1306The above can be hidden: using the device core, the pinctrl core may be1307setting up the config and muxing for the pins right before the device is1308probing, nevertheless orthogonal to the GPIO subsystem.1309 1310But there are also situations where it makes sense for the GPIO subsystem1311to communicate directly with the pinctrl subsystem, using the latter as a1312back-end. This is when the GPIO driver may call out to the functions1313described in the section `Pin control interaction with the GPIO subsystem`_1314above. This only involves per-pin multiplexing, and will be completely1315hidden behind the gpiod_*() function namespace. In this case, the driver1316need not interact with the pin control subsystem at all.1317 1318If a pin control driver and a GPIO driver is dealing with the same pins1319and the use cases involve multiplexing, you MUST implement the pin controller1320as a back-end for the GPIO driver like this, unless your hardware design1321is such that the GPIO controller can override the pin controller's1322multiplexing state through hardware without the need to interact with the1323pin control system.1324 1325 1326System pin control hogging1327==========================1328 1329Pin control map entries can be hogged by the core when the pin controller1330is registered. This means that the core will attempt to call ``pinctrl_get()``,1331``pinctrl_lookup_state()`` and ``pinctrl_select_state()`` on it immediately after1332the pin control device has been registered.1333 1334This occurs for mapping table entries where the client device name is equal1335to the pin controller device name, and the state name is ``PINCTRL_STATE_DEFAULT``:1336 1337.. code-block:: c1338 1339 {1340 .dev_name = "pinctrl-foo",1341 .name = PINCTRL_STATE_DEFAULT,1342 .type = PIN_MAP_TYPE_MUX_GROUP,1343 .ctrl_dev_name = "pinctrl-foo",1344 .function = "power_func",1345 },1346 1347Since it may be common to request the core to hog a few always-applicable1348mux settings on the primary pin controller, there is a convenience macro for1349this:1350 1351.. code-block:: c1352 1353 PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,1354 "power_func")1355 1356This gives the exact same result as the above construction.1357 1358 1359Runtime pinmuxing1360=================1361 1362It is possible to mux a certain function in and out at runtime, say to move1363an SPI port from one set of pins to another set of pins. Say for example for1364spi0 in the example above, we expose two different groups of pins for the same1365function, but with different named in the mapping as described under1366"Advanced mapping" above. So that for an SPI device, we have two states named1367"pos-A" and "pos-B".1368 1369This snippet first initializes a state object for both groups (in foo_probe()),1370then muxes the function in the pins defined by group A, and finally muxes it in1371on the pins defined by group B:1372 1373.. code-block:: c1374 1375 #include <linux/pinctrl/consumer.h>1376 1377 struct pinctrl *p;1378 struct pinctrl_state *s1, *s2;1379 1380 foo_probe()1381 {1382 /* Setup */1383 p = devm_pinctrl_get(&device);1384 if (IS_ERR(p))1385 ...1386 1387 s1 = pinctrl_lookup_state(p, "pos-A");1388 if (IS_ERR(s1))1389 ...1390 1391 s2 = pinctrl_lookup_state(p, "pos-B");1392 if (IS_ERR(s2))1393 ...1394 }1395 1396 foo_switch()1397 {1398 /* Enable on position A */1399 ret = pinctrl_select_state(p, s1);1400 if (ret < 0)1401 ...1402 1403 ...1404 1405 /* Enable on position B */1406 ret = pinctrl_select_state(p, s2);1407 if (ret < 0)1408 ...1409 1410 ...1411 }1412 1413The above has to be done from process context. The reservation of the pins1414will be done when the state is activated, so in effect one specific pin1415can be used by different functions at different times on a running system.1416 1417 1418Debugfs files1419=============1420 1421These files are created in ``/sys/kernel/debug/pinctrl``:1422 1423- ``pinctrl-devices``: prints each pin controller device along with columns to1424 indicate support for pinmux and pinconf1425 1426- ``pinctrl-handles``: prints each configured pin controller handle and the1427 corresponding pinmux maps1428 1429- ``pinctrl-maps``: prints all pinctrl maps1430 1431A sub-directory is created inside of ``/sys/kernel/debug/pinctrl`` for each pin1432controller device containing these files:1433 1434- ``pins``: prints a line for each pin registered on the pin controller. The1435 pinctrl driver may add additional information such as register contents.1436 1437- ``gpio-ranges``: prints ranges that map gpio lines to pins on the controller1438 1439- ``pingroups``: prints all pin groups registered on the pin controller1440 1441- ``pinconf-pins``: prints pin config settings for each pin1442 1443- ``pinconf-groups``: prints pin config settings per pin group1444 1445- ``pinmux-functions``: prints each pin function along with the pin groups that1446 map to the pin function1447 1448- ``pinmux-pins``: iterates through all pins and prints mux owner, gpio owner1449 and if the pin is a hog1450 1451- ``pinmux-select``: write to this file to activate a pin function for a group:1452 1453 .. code-block:: sh1454 1455 echo "<group-name function-name>" > pinmux-select1456