15513b411SDrew Fustini=============================== 25513b411SDrew FustiniPINCTRL (PIN CONTROL) subsystem 35513b411SDrew Fustini=============================== 45513b411SDrew Fustini 55513b411SDrew FustiniThis document outlines the pin control subsystem in Linux 65513b411SDrew Fustini 75513b411SDrew FustiniThis subsystem deals with: 85513b411SDrew Fustini 95513b411SDrew Fustini- Enumerating and naming controllable pins 105513b411SDrew Fustini 115513b411SDrew Fustini- Multiplexing of pins, pads, fingers (etc) see below for details 125513b411SDrew Fustini 135513b411SDrew Fustini- Configuration of pins, pads, fingers (etc), such as software-controlled 14af6f64c6SAndy Shevchenko biasing and driving mode specific pins, such as pull-up, pull-down, open drain, 155513b411SDrew Fustini load capacitance etc. 165513b411SDrew Fustini 175513b411SDrew FustiniTop-level interface 185513b411SDrew Fustini=================== 195513b411SDrew Fustini 2088f8ac47SBagas SanjayaDefinitions: 215513b411SDrew Fustini 2288f8ac47SBagas Sanjaya- A PIN CONTROLLER is a piece of hardware, usually a set of registers, that 235513b411SDrew Fustini can control PINs. It may be able to multiplex, bias, set load capacitance, 245513b411SDrew Fustini set drive strength, etc. for individual pins or groups of pins. 255513b411SDrew Fustini 265513b411SDrew Fustini- PINS are equal to pads, fingers, balls or whatever packaging input or 275513b411SDrew Fustini output line you want to control and these are denoted by unsigned integers 285513b411SDrew Fustini in the range 0..maxpin. This numberspace is local to each PIN CONTROLLER, so 295513b411SDrew Fustini there may be several such number spaces in a system. This pin space may 305513b411SDrew Fustini be sparse - i.e. there may be gaps in the space with numbers where no 315513b411SDrew Fustini pin exists. 325513b411SDrew Fustini 335513b411SDrew FustiniWhen a PIN CONTROLLER is instantiated, it will register a descriptor to the 345513b411SDrew Fustinipin control framework, and this descriptor contains an array of pin descriptors 355513b411SDrew Fustinidescribing the pins handled by this specific pin controller. 365513b411SDrew Fustini 375513b411SDrew FustiniHere is an example of a PGA (Pin Grid Array) chip seen from underneath:: 385513b411SDrew Fustini 395513b411SDrew Fustini A B C D E F G H 405513b411SDrew Fustini 415513b411SDrew Fustini 8 o o o o o o o o 425513b411SDrew Fustini 435513b411SDrew Fustini 7 o o o o o o o o 445513b411SDrew Fustini 455513b411SDrew Fustini 6 o o o o o o o o 465513b411SDrew Fustini 475513b411SDrew Fustini 5 o o o o o o o o 485513b411SDrew Fustini 495513b411SDrew Fustini 4 o o o o o o o o 505513b411SDrew Fustini 515513b411SDrew Fustini 3 o o o o o o o o 525513b411SDrew Fustini 535513b411SDrew Fustini 2 o o o o o o o o 545513b411SDrew Fustini 555513b411SDrew Fustini 1 o o o o o o o o 565513b411SDrew Fustini 575513b411SDrew FustiniTo register a pin controller and name all the pins on this package we can do 58af6f64c6SAndy Shevchenkothis in our driver: 59af6f64c6SAndy Shevchenko 60af6f64c6SAndy Shevchenko.. code-block:: c 615513b411SDrew Fustini 625513b411SDrew Fustini #include <linux/pinctrl/pinctrl.h> 635513b411SDrew Fustini 645513b411SDrew Fustini const struct pinctrl_pin_desc foo_pins[] = { 655513b411SDrew Fustini PINCTRL_PIN(0, "A8"), 665513b411SDrew Fustini PINCTRL_PIN(1, "B8"), 675513b411SDrew Fustini PINCTRL_PIN(2, "C8"), 685513b411SDrew Fustini ... 695513b411SDrew Fustini PINCTRL_PIN(61, "F1"), 705513b411SDrew Fustini PINCTRL_PIN(62, "G1"), 715513b411SDrew Fustini PINCTRL_PIN(63, "H1"), 725513b411SDrew Fustini }; 735513b411SDrew Fustini 745513b411SDrew Fustini static struct pinctrl_desc foo_desc = { 755513b411SDrew Fustini .name = "foo", 765513b411SDrew Fustini .pins = foo_pins, 775513b411SDrew Fustini .npins = ARRAY_SIZE(foo_pins), 785513b411SDrew Fustini .owner = THIS_MODULE, 795513b411SDrew Fustini }; 805513b411SDrew Fustini 81af6f64c6SAndy Shevchenko int __init foo_init(void) 825513b411SDrew Fustini { 835513b411SDrew Fustini int error; 845513b411SDrew Fustini 855513b411SDrew Fustini struct pinctrl_dev *pctl; 865513b411SDrew Fustini 87af6f64c6SAndy Shevchenko error = pinctrl_register_and_init(&foo_desc, <PARENT>, NULL, &pctl); 885513b411SDrew Fustini if (error) 895513b411SDrew Fustini return error; 905513b411SDrew Fustini 915513b411SDrew Fustini return pinctrl_enable(pctl); 925513b411SDrew Fustini } 935513b411SDrew Fustini 945513b411SDrew FustiniTo enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and 955513b411SDrew Fustiniselected drivers, you need to select them from your machine's Kconfig entry, 965513b411SDrew Fustinisince these are so tightly integrated with the machines they are used on. 9788f8ac47SBagas SanjayaSee ``arch/arm/mach-ux500/Kconfig`` for an example. 985513b411SDrew Fustini 995513b411SDrew FustiniPins usually have fancier names than this. You can find these in the datasheet 1005513b411SDrew Fustinifor your chip. Notice that the core pinctrl.h file provides a fancy macro 10188f8ac47SBagas Sanjayacalled ``PINCTRL_PIN()`` to create the struct entries. As you can see the pins are 10288f8ac47SBagas Sanjayaenumerated from 0 in the upper left corner to 63 in the lower right corner. 1035513b411SDrew FustiniThis enumeration was arbitrarily chosen, in practice you need to think 1045513b411SDrew Fustinithrough your numbering system so that it matches the layout of registers 1055513b411SDrew Fustiniand such things in your driver, or the code may become complicated. You must 1065513b411SDrew Fustinialso consider matching of offsets to the GPIO ranges that may be handled by 1075513b411SDrew Fustinithe pin controller. 1085513b411SDrew Fustini 10988f8ac47SBagas SanjayaFor a padding with 467 pads, as opposed to actual pins, the enumeration will 11088f8ac47SBagas Sanjayabe like this, walking around the edge of the chip, which seems to be industry 1115513b411SDrew Fustinistandard too (all these pads had names, too):: 1125513b411SDrew Fustini 1135513b411SDrew Fustini 1145513b411SDrew Fustini 0 ..... 104 1155513b411SDrew Fustini 466 105 1165513b411SDrew Fustini . . 1175513b411SDrew Fustini . . 1185513b411SDrew Fustini 358 224 1195513b411SDrew Fustini 357 .... 225 1205513b411SDrew Fustini 1215513b411SDrew Fustini 1225513b411SDrew FustiniPin groups 1235513b411SDrew Fustini========== 1245513b411SDrew Fustini 1255513b411SDrew FustiniMany controllers need to deal with groups of pins, so the pin controller 1265513b411SDrew Fustinisubsystem has a mechanism for enumerating groups of pins and retrieving the 1275513b411SDrew Fustiniactual enumerated pins that are part of a certain group. 1285513b411SDrew Fustini 1295513b411SDrew FustiniFor example, say that we have a group of pins dealing with an SPI interface 1305513b411SDrew Fustinion { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins 1315513b411SDrew Fustinion { 24, 25 }. 1325513b411SDrew Fustini 1335513b411SDrew FustiniThese two groups are presented to the pin control subsystem by implementing 13488f8ac47SBagas Sanjayasome generic ``pinctrl_ops`` like this: 135af6f64c6SAndy Shevchenko 136af6f64c6SAndy Shevchenko.. code-block:: c 1375513b411SDrew Fustini 1385513b411SDrew Fustini #include <linux/pinctrl/pinctrl.h> 1395513b411SDrew Fustini 1405513b411SDrew Fustini static const unsigned int spi0_pins[] = { 0, 8, 16, 24 }; 1415513b411SDrew Fustini static const unsigned int i2c0_pins[] = { 24, 25 }; 1425513b411SDrew Fustini 143af6f64c6SAndy Shevchenko static const struct pingroup foo_groups[] = { 144af6f64c6SAndy Shevchenko PINCTRL_PINGROUP("spi0_grp", spi0_pins, ARRAY_SIZE(spi0_pins)), 145af6f64c6SAndy Shevchenko PINCTRL_PINGROUP("i2c0_grp", i2c0_pins, ARRAY_SIZE(i2c0_pins)), 1465513b411SDrew Fustini }; 1475513b411SDrew Fustini 1485513b411SDrew Fustini static int foo_get_groups_count(struct pinctrl_dev *pctldev) 1495513b411SDrew Fustini { 1505513b411SDrew Fustini return ARRAY_SIZE(foo_groups); 1515513b411SDrew Fustini } 1525513b411SDrew Fustini 1535513b411SDrew Fustini static const char *foo_get_group_name(struct pinctrl_dev *pctldev, 154af6f64c6SAndy Shevchenko unsigned int selector) 1555513b411SDrew Fustini { 1565513b411SDrew Fustini return foo_groups[selector].name; 1575513b411SDrew Fustini } 1585513b411SDrew Fustini 159af6f64c6SAndy Shevchenko static int foo_get_group_pins(struct pinctrl_dev *pctldev, 160af6f64c6SAndy Shevchenko unsigned int selector, 161af6f64c6SAndy Shevchenko const unsigned int **pins, 162af6f64c6SAndy Shevchenko unsigned int *npins) 1635513b411SDrew Fustini { 164af6f64c6SAndy Shevchenko *pins = foo_groups[selector].pins; 165af6f64c6SAndy Shevchenko *npins = foo_groups[selector].npins; 1665513b411SDrew Fustini return 0; 1675513b411SDrew Fustini } 1685513b411SDrew Fustini 1695513b411SDrew Fustini static struct pinctrl_ops foo_pctrl_ops = { 1705513b411SDrew Fustini .get_groups_count = foo_get_groups_count, 1715513b411SDrew Fustini .get_group_name = foo_get_group_name, 1725513b411SDrew Fustini .get_group_pins = foo_get_group_pins, 1735513b411SDrew Fustini }; 1745513b411SDrew Fustini 1755513b411SDrew Fustini static struct pinctrl_desc foo_desc = { 1765513b411SDrew Fustini ... 1775513b411SDrew Fustini .pctlops = &foo_pctrl_ops, 1785513b411SDrew Fustini }; 1795513b411SDrew Fustini 18088f8ac47SBagas SanjayaThe pin control subsystem will call the ``.get_groups_count()`` function to 1815513b411SDrew Fustinidetermine the total number of legal selectors, then it will call the other functions 1825513b411SDrew Fustinito retrieve the name and pins of the group. Maintaining the data structure of 1835513b411SDrew Fustinithe groups is up to the driver, this is just a simple example - in practice you 1845513b411SDrew Fustinimay need more entries in your group structure, for example specific register 1855513b411SDrew Fustiniranges associated with each group and so on. 1865513b411SDrew Fustini 1875513b411SDrew Fustini 1885513b411SDrew FustiniPin configuration 1895513b411SDrew Fustini================= 1905513b411SDrew Fustini 1915513b411SDrew FustiniPins can sometimes be software-configured in various ways, mostly related 1925513b411SDrew Fustinito their electronic properties when used as inputs or outputs. For example you 193af6f64c6SAndy Shevchenkomay be able to make an output pin high impedance (Hi-Z), or "tristate" meaning it is 1945513b411SDrew Fustinieffectively disconnected. You may be able to connect an input pin to VDD or GND 1955513b411SDrew Fustiniusing a certain resistor value - pull up and pull down - so that the pin has a 1965513b411SDrew Fustinistable value when nothing is driving the rail it is connected to, or when it's 1975513b411SDrew Fustiniunconnected. 1985513b411SDrew Fustini 1995513b411SDrew FustiniPin configuration can be programmed by adding configuration entries into the 200af6f64c6SAndy Shevchenkomapping table; see section `Board/machine configuration`_ below. 2015513b411SDrew Fustini 2025513b411SDrew FustiniThe format and meaning of the configuration parameter, PLATFORM_X_PULL_UP 2035513b411SDrew Fustiniabove, is entirely defined by the pin controller driver. 2045513b411SDrew Fustini 2055513b411SDrew FustiniThe pin configuration driver implements callbacks for changing pin 206af6f64c6SAndy Shevchenkoconfiguration in the pin controller ops like this: 2075513b411SDrew Fustini 208af6f64c6SAndy Shevchenko.. code-block:: c 209af6f64c6SAndy Shevchenko 2105513b411SDrew Fustini #include <linux/pinctrl/pinconf.h> 211af6f64c6SAndy Shevchenko #include <linux/pinctrl/pinctrl.h> 212af6f64c6SAndy Shevchenko 2135513b411SDrew Fustini #include "platform_x_pindefs.h" 2145513b411SDrew Fustini 2155513b411SDrew Fustini static int foo_pin_config_get(struct pinctrl_dev *pctldev, 216af6f64c6SAndy Shevchenko unsigned int offset, 2175513b411SDrew Fustini unsigned long *config) 2185513b411SDrew Fustini { 2195513b411SDrew Fustini struct my_conftype conf; 2205513b411SDrew Fustini 221af6f64c6SAndy Shevchenko /* ... Find setting for pin @ offset ... */ 2225513b411SDrew Fustini 2235513b411SDrew Fustini *config = (unsigned long) conf; 2245513b411SDrew Fustini } 2255513b411SDrew Fustini 2265513b411SDrew Fustini static int foo_pin_config_set(struct pinctrl_dev *pctldev, 227af6f64c6SAndy Shevchenko unsigned int offset, 2285513b411SDrew Fustini unsigned long config) 2295513b411SDrew Fustini { 2305513b411SDrew Fustini struct my_conftype *conf = (struct my_conftype *) config; 2315513b411SDrew Fustini 2325513b411SDrew Fustini switch (conf) { 2335513b411SDrew Fustini case PLATFORM_X_PULL_UP: 2345513b411SDrew Fustini ... 235af6f64c6SAndy Shevchenko break; 2365513b411SDrew Fustini } 2375513b411SDrew Fustini } 2385513b411SDrew Fustini 2395513b411SDrew Fustini static int foo_pin_config_group_get(struct pinctrl_dev *pctldev, 2405513b411SDrew Fustini unsigned selector, 2415513b411SDrew Fustini unsigned long *config) 2425513b411SDrew Fustini { 2435513b411SDrew Fustini ... 2445513b411SDrew Fustini } 2455513b411SDrew Fustini 2465513b411SDrew Fustini static int foo_pin_config_group_set(struct pinctrl_dev *pctldev, 2475513b411SDrew Fustini unsigned selector, 2485513b411SDrew Fustini unsigned long config) 2495513b411SDrew Fustini { 2505513b411SDrew Fustini ... 2515513b411SDrew Fustini } 2525513b411SDrew Fustini 2535513b411SDrew Fustini static struct pinconf_ops foo_pconf_ops = { 2545513b411SDrew Fustini .pin_config_get = foo_pin_config_get, 2555513b411SDrew Fustini .pin_config_set = foo_pin_config_set, 2565513b411SDrew Fustini .pin_config_group_get = foo_pin_config_group_get, 2575513b411SDrew Fustini .pin_config_group_set = foo_pin_config_group_set, 2585513b411SDrew Fustini }; 2595513b411SDrew Fustini 2605513b411SDrew Fustini /* Pin config operations are handled by some pin controller */ 2615513b411SDrew Fustini static struct pinctrl_desc foo_desc = { 2625513b411SDrew Fustini ... 2635513b411SDrew Fustini .confops = &foo_pconf_ops, 2645513b411SDrew Fustini }; 2655513b411SDrew Fustini 2665513b411SDrew FustiniInteraction with the GPIO subsystem 2675513b411SDrew Fustini=================================== 2685513b411SDrew Fustini 2695513b411SDrew FustiniThe GPIO drivers may want to perform operations of various types on the same 2705513b411SDrew Fustiniphysical pins that are also registered as pin controller pins. 2715513b411SDrew Fustini 2725513b411SDrew FustiniFirst and foremost, the two subsystems can be used as completely orthogonal, 273af6f64c6SAndy Shevchenkosee the section named `Pin control requests from drivers`_ and 274af6f64c6SAndy Shevchenko`Drivers needing both pin control and GPIOs`_ below for details. But in some 2755513b411SDrew Fustinisituations a cross-subsystem mapping between pins and GPIOs is needed. 2765513b411SDrew Fustini 2775513b411SDrew FustiniSince the pin controller subsystem has its pinspace local to the pin controller 2785513b411SDrew Fustiniwe need a mapping so that the pin control subsystem can figure out which pin 2795513b411SDrew Fustinicontroller handles control of a certain GPIO pin. Since a single pin controller 2805513b411SDrew Fustinimay be muxing several GPIO ranges (typically SoCs that have one set of pins, 2815513b411SDrew Fustinibut internally several GPIO silicon blocks, each modelled as a struct 2825513b411SDrew Fustinigpio_chip) any number of GPIO ranges can be added to a pin controller instance 283af6f64c6SAndy Shevchenkolike this: 284af6f64c6SAndy Shevchenko 285af6f64c6SAndy Shevchenko.. code-block:: c 286af6f64c6SAndy Shevchenko 287af6f64c6SAndy Shevchenko #include <linux/gpio/driver.h> 288af6f64c6SAndy Shevchenko 289af6f64c6SAndy Shevchenko #include <linux/pinctrl/pinctrl.h> 2905513b411SDrew Fustini 2915513b411SDrew Fustini struct gpio_chip chip_a; 2925513b411SDrew Fustini struct gpio_chip chip_b; 2935513b411SDrew Fustini 2945513b411SDrew Fustini static struct pinctrl_gpio_range gpio_range_a = { 2955513b411SDrew Fustini .name = "chip a", 2965513b411SDrew Fustini .id = 0, 2975513b411SDrew Fustini .base = 32, 2985513b411SDrew Fustini .pin_base = 32, 2995513b411SDrew Fustini .npins = 16, 300af6f64c6SAndy Shevchenko .gc = &chip_a, 3015513b411SDrew Fustini }; 3025513b411SDrew Fustini 3035513b411SDrew Fustini static struct pinctrl_gpio_range gpio_range_b = { 3045513b411SDrew Fustini .name = "chip b", 3055513b411SDrew Fustini .id = 0, 3065513b411SDrew Fustini .base = 48, 3075513b411SDrew Fustini .pin_base = 64, 3085513b411SDrew Fustini .npins = 8, 3095513b411SDrew Fustini .gc = &chip_b; 3105513b411SDrew Fustini }; 3115513b411SDrew Fustini 312af6f64c6SAndy Shevchenko int __init foo_init(void) 3135513b411SDrew Fustini { 3145513b411SDrew Fustini struct pinctrl_dev *pctl; 3155513b411SDrew Fustini ... 3165513b411SDrew Fustini pinctrl_add_gpio_range(pctl, &gpio_range_a); 3175513b411SDrew Fustini pinctrl_add_gpio_range(pctl, &gpio_range_b); 318af6f64c6SAndy Shevchenko ... 3195513b411SDrew Fustini } 3205513b411SDrew Fustini 3215513b411SDrew FustiniSo this complex system has one pin controller handling two different 3225513b411SDrew FustiniGPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and 32388f8ac47SBagas Sanjaya"chip b" have different ``pin_base``, which means a start pin number of the 3245513b411SDrew FustiniGPIO range. 3255513b411SDrew Fustini 3265513b411SDrew FustiniThe GPIO range of "chip a" starts from the GPIO base of 32 and actual 3275513b411SDrew Fustinipin range also starts from 32. However "chip b" has different starting 3285513b411SDrew Fustinioffset for the GPIO range and pin range. The GPIO range of "chip b" starts 3295513b411SDrew Fustinifrom GPIO number 48, while the pin range of "chip b" starts from 64. 3305513b411SDrew Fustini 33188f8ac47SBagas SanjayaWe can convert a gpio number to actual pin number using this ``pin_base``. 3325513b411SDrew FustiniThey are mapped in the global GPIO pin space at: 3335513b411SDrew Fustini 3345513b411SDrew Fustinichip a: 3355513b411SDrew Fustini - GPIO range : [32 .. 47] 3365513b411SDrew Fustini - pin range : [32 .. 47] 3375513b411SDrew Fustinichip b: 3385513b411SDrew Fustini - GPIO range : [48 .. 55] 3395513b411SDrew Fustini - pin range : [64 .. 71] 3405513b411SDrew Fustini 3415513b411SDrew FustiniThe above examples assume the mapping between the GPIOs and pins is 3425513b411SDrew Fustinilinear. If the mapping is sparse or haphazard, an array of arbitrary pin 343af6f64c6SAndy Shevchenkonumbers can be encoded in the range like this: 3445513b411SDrew Fustini 345af6f64c6SAndy Shevchenko.. code-block:: c 346af6f64c6SAndy Shevchenko 347af6f64c6SAndy Shevchenko static const unsigned int range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 }; 3485513b411SDrew Fustini 3495513b411SDrew Fustini static struct pinctrl_gpio_range gpio_range = { 3505513b411SDrew Fustini .name = "chip", 3515513b411SDrew Fustini .id = 0, 3525513b411SDrew Fustini .base = 32, 3535513b411SDrew Fustini .pins = &range_pins, 3545513b411SDrew Fustini .npins = ARRAY_SIZE(range_pins), 355af6f64c6SAndy Shevchenko .gc = &chip, 3565513b411SDrew Fustini }; 3575513b411SDrew Fustini 35888f8ac47SBagas SanjayaIn this case the ``pin_base`` property will be ignored. If the name of a pin 3595513b411SDrew Fustinigroup is known, the pins and npins elements of the above structure can be 36088f8ac47SBagas Sanjayainitialised using the function ``pinctrl_get_group_pins()``, e.g. for pin 361af6f64c6SAndy Shevchenkogroup "foo": 3625513b411SDrew Fustini 363af6f64c6SAndy Shevchenko.. code-block:: c 364af6f64c6SAndy Shevchenko 365af6f64c6SAndy Shevchenko pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins); 3665513b411SDrew Fustini 3675513b411SDrew FustiniWhen GPIO-specific functions in the pin control subsystem are called, these 3685513b411SDrew Fustiniranges will be used to look up the appropriate pin controller by inspecting 3695513b411SDrew Fustiniand matching the pin to the pin ranges across all controllers. When a 3705513b411SDrew Fustinipin controller handling the matching range is found, GPIO-specific functions 3715513b411SDrew Fustiniwill be called on that specific pin controller. 3725513b411SDrew Fustini 3735513b411SDrew FustiniFor all functionalities dealing with pin biasing, pin muxing etc, the pin 3745513b411SDrew Fustinicontroller subsystem will look up the corresponding pin number from the passed 3755513b411SDrew Fustiniin gpio number, and use the range's internals to retrieve a pin number. After 3765513b411SDrew Fustinithat, the subsystem passes it on to the pin control driver, so the driver 3775513b411SDrew Fustiniwill get a pin number into its handled number range. Further it is also passed 3785513b411SDrew Fustinithe range ID value, so that the pin controller knows which range it should 3795513b411SDrew Fustinideal with. 3805513b411SDrew Fustini 38188f8ac47SBagas SanjayaCalling ``pinctrl_add_gpio_range()`` from pinctrl driver is DEPRECATED. Please see 38288f8ac47SBagas Sanjayasection 2.1 of ``Documentation/devicetree/bindings/gpio/gpio.txt`` on how to bind 3835513b411SDrew Fustinipinctrl and gpio drivers. 3845513b411SDrew Fustini 3855513b411SDrew Fustini 3865513b411SDrew FustiniPINMUX interfaces 3875513b411SDrew Fustini================= 3885513b411SDrew Fustini 3895513b411SDrew FustiniThese calls use the pinmux_* naming prefix. No other calls should use that 3905513b411SDrew Fustiniprefix. 3915513b411SDrew Fustini 3925513b411SDrew Fustini 3935513b411SDrew FustiniWhat is pinmuxing? 3945513b411SDrew Fustini================== 3955513b411SDrew Fustini 3965513b411SDrew FustiniPINMUX, also known as padmux, ballmux, alternate functions or mission modes 3975513b411SDrew Fustiniis a way for chip vendors producing some kind of electrical packages to use 3985513b411SDrew Fustinia certain physical pin (ball, pad, finger, etc) for multiple mutually exclusive 3995513b411SDrew Fustinifunctions, depending on the application. By "application" in this context 4005513b411SDrew Fustiniwe usually mean a way of soldering or wiring the package into an electronic 4015513b411SDrew Fustinisystem, even though the framework makes it possible to also change the function 4025513b411SDrew Fustiniat runtime. 4035513b411SDrew Fustini 4045513b411SDrew FustiniHere is an example of a PGA (Pin Grid Array) chip seen from underneath:: 4055513b411SDrew Fustini 4065513b411SDrew Fustini A B C D E F G H 4075513b411SDrew Fustini +---+ 4085513b411SDrew Fustini 8 | o | o o o o o o o 4095513b411SDrew Fustini | | 4105513b411SDrew Fustini 7 | o | o o o o o o o 4115513b411SDrew Fustini | | 4125513b411SDrew Fustini 6 | o | o o o o o o o 4135513b411SDrew Fustini +---+---+ 4145513b411SDrew Fustini 5 | o | o | o o o o o o 4155513b411SDrew Fustini +---+---+ +---+ 4165513b411SDrew Fustini 4 o o o o o o | o | o 4175513b411SDrew Fustini | | 4185513b411SDrew Fustini 3 o o o o o o | o | o 4195513b411SDrew Fustini | | 4205513b411SDrew Fustini 2 o o o o o o | o | o 4215513b411SDrew Fustini +-------+-------+-------+---+---+ 4225513b411SDrew Fustini 1 | o o | o o | o o | o | o | 4235513b411SDrew Fustini +-------+-------+-------+---+---+ 4245513b411SDrew Fustini 4255513b411SDrew FustiniThis is not tetris. The game to think of is chess. Not all PGA/BGA packages 4265513b411SDrew Fustiniare chessboard-like, big ones have "holes" in some arrangement according to 4275513b411SDrew Fustinidifferent design patterns, but we're using this as a simple example. Of the 4285513b411SDrew Fustinipins you see some will be taken by things like a few VCC and GND to feed power 4295513b411SDrew Fustinito the chip, and quite a few will be taken by large ports like an external 4305513b411SDrew Fustinimemory interface. The remaining pins will often be subject to pin multiplexing. 4315513b411SDrew Fustini 4325513b411SDrew FustiniThe example 8x8 PGA package above will have pin numbers 0 through 63 assigned 4335513b411SDrew Fustinito its physical pins. It will name the pins { A1, A2, A3 ... H6, H7, H8 } using 4345513b411SDrew Fustinipinctrl_register_pins() and a suitable data set as shown earlier. 4355513b411SDrew Fustini 4365513b411SDrew FustiniIn this 8x8 BGA package the pins { A8, A7, A6, A5 } can be used as an SPI port 4375513b411SDrew Fustini(these are four pins: CLK, RXD, TXD, FRM). In that case, pin B5 can be used as 4385513b411SDrew Fustinisome general-purpose GPIO pin. However, in another setting, pins { A5, B5 } can 4395513b411SDrew Fustinibe used as an I2C port (these are just two pins: SCL, SDA). Needless to say, 4405513b411SDrew Fustiniwe cannot use the SPI port and I2C port at the same time. However in the inside 4415513b411SDrew Fustiniof the package the silicon performing the SPI logic can alternatively be routed 4425513b411SDrew Fustiniout on pins { G4, G3, G2, G1 }. 4435513b411SDrew Fustini 4445513b411SDrew FustiniOn the bottom row at { A1, B1, C1, D1, E1, F1, G1, H1 } we have something 4455513b411SDrew Fustinispecial - it's an external MMC bus that can be 2, 4 or 8 bits wide, and it will 4465513b411SDrew Fustiniconsume 2, 4 or 8 pins respectively, so either { A1, B1 } are taken or 4475513b411SDrew Fustini{ A1, B1, C1, D1 } or all of them. If we use all 8 bits, we cannot use the SPI 4485513b411SDrew Fustiniport on pins { G4, G3, G2, G1 } of course. 4495513b411SDrew Fustini 4505513b411SDrew FustiniThis way the silicon blocks present inside the chip can be multiplexed "muxed" 4515513b411SDrew Fustiniout on different pin ranges. Often contemporary SoC (systems on chip) will 4525513b411SDrew Fustinicontain several I2C, SPI, SDIO/MMC, etc silicon blocks that can be routed to 4535513b411SDrew Fustinidifferent pins by pinmux settings. 4545513b411SDrew Fustini 4555513b411SDrew FustiniSince general-purpose I/O pins (GPIO) are typically always in shortage, it is 4565513b411SDrew Fustinicommon to be able to use almost any pin as a GPIO pin if it is not currently 4575513b411SDrew Fustiniin use by some other I/O port. 4585513b411SDrew Fustini 4595513b411SDrew Fustini 4605513b411SDrew FustiniPinmux conventions 4615513b411SDrew Fustini================== 4625513b411SDrew Fustini 4635513b411SDrew FustiniThe purpose of the pinmux functionality in the pin controller subsystem is to 4645513b411SDrew Fustiniabstract and provide pinmux settings to the devices you choose to instantiate 4655513b411SDrew Fustiniin your machine configuration. It is inspired by the clk, GPIO and regulator 4665513b411SDrew Fustinisubsystems, so devices will request their mux setting, but it's also possible 4675513b411SDrew Fustinito request a single pin for e.g. GPIO. 4685513b411SDrew Fustini 46988f8ac47SBagas SanjayaThe conventions are: 4705513b411SDrew Fustini 4715513b411SDrew Fustini- FUNCTIONS can be switched in and out by a driver residing with the pin 47288f8ac47SBagas Sanjaya control subsystem in the ``drivers/pinctrl`` directory of the kernel. The 4735513b411SDrew Fustini pin control driver knows the possible functions. In the example above you can 4745513b411SDrew Fustini identify three pinmux functions, one for spi, one for i2c and one for mmc. 4755513b411SDrew Fustini 4765513b411SDrew Fustini- FUNCTIONS are assumed to be enumerable from zero in a one-dimensional array. 4775513b411SDrew Fustini In this case the array could be something like: { spi0, i2c0, mmc0 } 4785513b411SDrew Fustini for the three available functions. 4795513b411SDrew Fustini 4805513b411SDrew Fustini- FUNCTIONS have PIN GROUPS as defined on the generic level - so a certain 4815513b411SDrew Fustini function is *always* associated with a certain set of pin groups, could 4825513b411SDrew Fustini be just a single one, but could also be many. In the example above the 4835513b411SDrew Fustini function i2c is associated with the pins { A5, B5 }, enumerated as 4845513b411SDrew Fustini { 24, 25 } in the controller pin space. 4855513b411SDrew Fustini 4865513b411SDrew Fustini The Function spi is associated with pin groups { A8, A7, A6, A5 } 4875513b411SDrew Fustini and { G4, G3, G2, G1 }, which are enumerated as { 0, 8, 16, 24 } and 4885513b411SDrew Fustini { 38, 46, 54, 62 } respectively. 4895513b411SDrew Fustini 4905513b411SDrew Fustini Group names must be unique per pin controller, no two groups on the same 4915513b411SDrew Fustini controller may have the same name. 4925513b411SDrew Fustini 4935513b411SDrew Fustini- The combination of a FUNCTION and a PIN GROUP determine a certain function 4945513b411SDrew Fustini for a certain set of pins. The knowledge of the functions and pin groups 4955513b411SDrew Fustini and their machine-specific particulars are kept inside the pinmux driver, 4965513b411SDrew Fustini from the outside only the enumerators are known, and the driver core can 4975513b411SDrew Fustini request: 4985513b411SDrew Fustini 4995513b411SDrew Fustini - The name of a function with a certain selector (>= 0) 5005513b411SDrew Fustini - A list of groups associated with a certain function 5015513b411SDrew Fustini - That a certain group in that list to be activated for a certain function 5025513b411SDrew Fustini 5035513b411SDrew Fustini As already described above, pin groups are in turn self-descriptive, so 5045513b411SDrew Fustini the core will retrieve the actual pin range in a certain group from the 5055513b411SDrew Fustini driver. 5065513b411SDrew Fustini 5075513b411SDrew Fustini- FUNCTIONS and GROUPS on a certain PIN CONTROLLER are MAPPED to a certain 5085513b411SDrew Fustini device by the board file, device tree or similar machine setup configuration 5095513b411SDrew Fustini mechanism, similar to how regulators are connected to devices, usually by 5105513b411SDrew Fustini name. Defining a pin controller, function and group thus uniquely identify 5115513b411SDrew Fustini the set of pins to be used by a certain device. (If only one possible group 5125513b411SDrew Fustini of pins is available for the function, no group name need to be supplied - 5135513b411SDrew Fustini the core will simply select the first and only group available.) 5145513b411SDrew Fustini 5155513b411SDrew Fustini In the example case we can define that this particular machine shall 5165513b411SDrew Fustini use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function 5175513b411SDrew Fustini fi2c0 group gi2c0, on the primary pin controller, we get mappings 518af6f64c6SAndy Shevchenko like these: 519af6f64c6SAndy Shevchenko 520af6f64c6SAndy Shevchenko .. code-block:: c 5215513b411SDrew Fustini 5225513b411SDrew Fustini { 5235513b411SDrew Fustini {"map-spi0", spi0, pinctrl0, fspi0, gspi0}, 524af6f64c6SAndy Shevchenko {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}, 5255513b411SDrew Fustini } 5265513b411SDrew Fustini 5275513b411SDrew Fustini Every map must be assigned a state name, pin controller, device and 5285513b411SDrew Fustini function. The group is not compulsory - if it is omitted the first group 5295513b411SDrew Fustini presented by the driver as applicable for the function will be selected, 5305513b411SDrew Fustini which is useful for simple cases. 5315513b411SDrew Fustini 5325513b411SDrew Fustini It is possible to map several groups to the same combination of device, 5335513b411SDrew Fustini pin controller and function. This is for cases where a certain function on 5345513b411SDrew Fustini a certain pin controller may use different sets of pins in different 5355513b411SDrew Fustini configurations. 5365513b411SDrew Fustini 5375513b411SDrew Fustini- PINS for a certain FUNCTION using a certain PIN GROUP on a certain 5385513b411SDrew Fustini PIN CONTROLLER are provided on a first-come first-serve basis, so if some 5395513b411SDrew Fustini other device mux setting or GPIO pin request has already taken your physical 5405513b411SDrew Fustini pin, you will be denied the use of it. To get (activate) a new setting, the 5415513b411SDrew Fustini old one has to be put (deactivated) first. 5425513b411SDrew Fustini 5435513b411SDrew FustiniSometimes the documentation and hardware registers will be oriented around 5445513b411SDrew Fustinipads (or "fingers") rather than pins - these are the soldering surfaces on the 5455513b411SDrew Fustinisilicon inside the package, and may or may not match the actual number of 5465513b411SDrew Fustinipins/balls underneath the capsule. Pick some enumeration that makes sense to 5475513b411SDrew Fustiniyou. Define enumerators only for the pins you can control if that makes sense. 5485513b411SDrew Fustini 5495513b411SDrew FustiniAssumptions: 5505513b411SDrew Fustini 5515513b411SDrew FustiniWe assume that the number of possible function maps to pin groups is limited by 5525513b411SDrew Fustinithe hardware. I.e. we assume that there is no system where any function can be 5535513b411SDrew Fustinimapped to any pin, like in a phone exchange. So the available pin groups for 5545513b411SDrew Fustinia certain function will be limited to a few choices (say up to eight or so), 5555513b411SDrew Fustininot hundreds or any amount of choices. This is the characteristic we have found 5565513b411SDrew Fustiniby inspecting available pinmux hardware, and a necessary assumption since we 5575513b411SDrew Fustiniexpect pinmux drivers to present *all* possible function vs pin group mappings 5585513b411SDrew Fustinito the subsystem. 5595513b411SDrew Fustini 5605513b411SDrew Fustini 5615513b411SDrew FustiniPinmux drivers 5625513b411SDrew Fustini============== 5635513b411SDrew Fustini 5645513b411SDrew FustiniThe pinmux core takes care of preventing conflicts on pins and calling 5655513b411SDrew Fustinithe pin controller driver to execute different settings. 5665513b411SDrew Fustini 5675513b411SDrew FustiniIt is the responsibility of the pinmux driver to impose further restrictions 5685513b411SDrew Fustini(say for example infer electronic limitations due to load, etc.) to determine 5695513b411SDrew Fustiniwhether or not the requested function can actually be allowed, and in case it 5705513b411SDrew Fustiniis possible to perform the requested mux setting, poke the hardware so that 5715513b411SDrew Fustinithis happens. 5725513b411SDrew Fustini 5735513b411SDrew FustiniPinmux drivers are required to supply a few callback functions, some are 57488f8ac47SBagas Sanjayaoptional. Usually the ``.set_mux()`` function is implemented, writing values into 5755513b411SDrew Fustinisome certain registers to activate a certain mux setting for a certain pin. 5765513b411SDrew Fustini 577af6f64c6SAndy ShevchenkoA simple driver for the above example will work by setting bits 0, 1, 2, 3, 4, or 5 5785513b411SDrew Fustiniinto some register named MUX to select a certain function with a certain 579af6f64c6SAndy Shevchenkogroup of pins would work something like this: 580af6f64c6SAndy Shevchenko 581af6f64c6SAndy Shevchenko.. code-block:: c 5825513b411SDrew Fustini 5835513b411SDrew Fustini #include <linux/pinctrl/pinctrl.h> 5845513b411SDrew Fustini #include <linux/pinctrl/pinmux.h> 5855513b411SDrew Fustini 586af6f64c6SAndy Shevchenko static const unsigned int spi0_0_pins[] = { 0, 8, 16, 24 }; 587af6f64c6SAndy Shevchenko static const unsigned int spi0_1_pins[] = { 38, 46, 54, 62 }; 588af6f64c6SAndy Shevchenko static const unsigned int i2c0_pins[] = { 24, 25 }; 589af6f64c6SAndy Shevchenko static const unsigned int mmc0_1_pins[] = { 56, 57 }; 590af6f64c6SAndy Shevchenko static const unsigned int mmc0_2_pins[] = { 58, 59 }; 591af6f64c6SAndy Shevchenko static const unsigned int mmc0_3_pins[] = { 60, 61, 62, 63 }; 592af6f64c6SAndy Shevchenko 593af6f64c6SAndy Shevchenko static const struct pingroup foo_groups[] = { 594af6f64c6SAndy Shevchenko PINCTRL_PINGROUP("spi0_0_grp", spi0_0_pins, ARRAY_SIZE(spi0_0_pins)), 595af6f64c6SAndy Shevchenko PINCTRL_PINGROUP("spi0_1_grp", spi0_1_pins, ARRAY_SIZE(spi0_1_pins)), 596af6f64c6SAndy Shevchenko PINCTRL_PINGROUP("i2c0_grp", i2c0_pins, ARRAY_SIZE(i2c0_pins)), 597af6f64c6SAndy Shevchenko PINCTRL_PINGROUP("mmc0_1_grp", mmc0_1_pins, ARRAY_SIZE(mmc0_1_pins)), 598af6f64c6SAndy Shevchenko PINCTRL_PINGROUP("mmc0_2_grp", mmc0_2_pins, ARRAY_SIZE(mmc0_2_pins)), 599af6f64c6SAndy Shevchenko PINCTRL_PINGROUP("mmc0_3_grp", mmc0_3_pins, ARRAY_SIZE(mmc0_3_pins)), 6005513b411SDrew Fustini }; 6015513b411SDrew Fustini 6025513b411SDrew Fustini static int foo_get_groups_count(struct pinctrl_dev *pctldev) 6035513b411SDrew Fustini { 6045513b411SDrew Fustini return ARRAY_SIZE(foo_groups); 6055513b411SDrew Fustini } 6065513b411SDrew Fustini 6075513b411SDrew Fustini static const char *foo_get_group_name(struct pinctrl_dev *pctldev, 608af6f64c6SAndy Shevchenko unsigned int selector) 6095513b411SDrew Fustini { 6105513b411SDrew Fustini return foo_groups[selector].name; 6115513b411SDrew Fustini } 6125513b411SDrew Fustini 613af6f64c6SAndy Shevchenko static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned int selector, 614af6f64c6SAndy Shevchenko const unsigned int **pins, 615af6f64c6SAndy Shevchenko unsigned int *npins) 6165513b411SDrew Fustini { 617af6f64c6SAndy Shevchenko *pins = foo_groups[selector].pins; 618af6f64c6SAndy Shevchenko *npins = foo_groups[selector].npins; 6195513b411SDrew Fustini return 0; 6205513b411SDrew Fustini } 6215513b411SDrew Fustini 6225513b411SDrew Fustini static struct pinctrl_ops foo_pctrl_ops = { 6235513b411SDrew Fustini .get_groups_count = foo_get_groups_count, 6245513b411SDrew Fustini .get_group_name = foo_get_group_name, 6255513b411SDrew Fustini .get_group_pins = foo_get_group_pins, 6265513b411SDrew Fustini }; 6275513b411SDrew Fustini 6285513b411SDrew Fustini static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" }; 6295513b411SDrew Fustini static const char * const i2c0_groups[] = { "i2c0_grp" }; 630af6f64c6SAndy Shevchenko static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp", "mmc0_3_grp" }; 6315513b411SDrew Fustini 632af6f64c6SAndy Shevchenko static const struct pinfunction foo_functions[] = { 633af6f64c6SAndy Shevchenko PINCTRL_PINFUNCTION("spi0", spi0_groups, ARRAY_SIZE(spi0_groups)), 634af6f64c6SAndy Shevchenko PINCTRL_PINFUNCTION("i2c0", i2c0_groups, ARRAY_SIZE(i2c0_groups)), 635af6f64c6SAndy Shevchenko PINCTRL_PINFUNCTION("mmc0", mmc0_groups, ARRAY_SIZE(mmc0_groups)), 6365513b411SDrew Fustini }; 6375513b411SDrew Fustini 6385513b411SDrew Fustini static int foo_get_functions_count(struct pinctrl_dev *pctldev) 6395513b411SDrew Fustini { 6405513b411SDrew Fustini return ARRAY_SIZE(foo_functions); 6415513b411SDrew Fustini } 6425513b411SDrew Fustini 643af6f64c6SAndy Shevchenko static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned int selector) 6445513b411SDrew Fustini { 6455513b411SDrew Fustini return foo_functions[selector].name; 6465513b411SDrew Fustini } 6475513b411SDrew Fustini 648af6f64c6SAndy Shevchenko static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned int selector, 6495513b411SDrew Fustini const char * const **groups, 650af6f64c6SAndy Shevchenko unsigned int * const ngroups) 6515513b411SDrew Fustini { 6525513b411SDrew Fustini *groups = foo_functions[selector].groups; 653af6f64c6SAndy Shevchenko *ngroups = foo_functions[selector].ngroups; 6545513b411SDrew Fustini return 0; 6555513b411SDrew Fustini } 6565513b411SDrew Fustini 657af6f64c6SAndy Shevchenko static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned int selector, 658af6f64c6SAndy Shevchenko unsigned int group) 6595513b411SDrew Fustini { 660af6f64c6SAndy Shevchenko u8 regbit = BIT(group); 6615513b411SDrew Fustini 6625513b411SDrew Fustini writeb((readb(MUX) | regbit), MUX); 6635513b411SDrew Fustini return 0; 6645513b411SDrew Fustini } 6655513b411SDrew Fustini 6665513b411SDrew Fustini static struct pinmux_ops foo_pmxops = { 6675513b411SDrew Fustini .get_functions_count = foo_get_functions_count, 6685513b411SDrew Fustini .get_function_name = foo_get_fname, 6695513b411SDrew Fustini .get_function_groups = foo_get_groups, 6705513b411SDrew Fustini .set_mux = foo_set_mux, 6715513b411SDrew Fustini .strict = true, 6725513b411SDrew Fustini }; 6735513b411SDrew Fustini 6745513b411SDrew Fustini /* Pinmux operations are handled by some pin controller */ 6755513b411SDrew Fustini static struct pinctrl_desc foo_desc = { 6765513b411SDrew Fustini ... 6775513b411SDrew Fustini .pctlops = &foo_pctrl_ops, 6785513b411SDrew Fustini .pmxops = &foo_pmxops, 6795513b411SDrew Fustini }; 6805513b411SDrew Fustini 681af6f64c6SAndy ShevchenkoIn the example activating muxing 0 and 2 at the same time setting bits 682af6f64c6SAndy Shevchenko0 and 2, uses pin 24 in common so they would collide. All the same for 683af6f64c6SAndy Shevchenkothe muxes 1 and 5, which have pin 62 in common. 6845513b411SDrew Fustini 6855513b411SDrew FustiniThe beauty of the pinmux subsystem is that since it keeps track of all 6865513b411SDrew Fustinipins and who is using them, it will already have denied an impossible 6875513b411SDrew Fustinirequest like that, so the driver does not need to worry about such 6885513b411SDrew Fustinithings - when it gets a selector passed in, the pinmux subsystem makes 6895513b411SDrew Fustinisure no other device or GPIO assignment is already using the selected 690af6f64c6SAndy Shevchenkopins. Thus bits 0 and 2, or 1 and 5 in the control register will never 691af6f64c6SAndy Shevchenkobe set at the same time. 6925513b411SDrew Fustini 6935513b411SDrew FustiniAll the above functions are mandatory to implement for a pinmux driver. 6945513b411SDrew Fustini 6955513b411SDrew Fustini 6965513b411SDrew FustiniPin control interaction with the GPIO subsystem 6975513b411SDrew Fustini=============================================== 6985513b411SDrew Fustini 6995513b411SDrew FustiniNote that the following implies that the use case is to use a certain pin 70088f8ac47SBagas Sanjayafrom the Linux kernel using the API in ``<linux/gpio/consumer.h>`` with gpiod_get() 7015513b411SDrew Fustiniand similar functions. There are cases where you may be using something 7025513b411SDrew Fustinithat your datasheet calls "GPIO mode", but actually is just an electrical 7035513b411SDrew Fustiniconfiguration for a certain device. See the section below named 704af6f64c6SAndy Shevchenko`GPIO mode pitfalls`_ for more details on this scenario. 7055513b411SDrew Fustini 70688f8ac47SBagas SanjayaThe public pinmux API contains two functions named ``pinctrl_gpio_request()`` 70788f8ac47SBagas Sanjayaand ``pinctrl_gpio_free()``. These two functions shall *ONLY* be called from 70888f8ac47SBagas Sanjayagpiolib-based drivers as part of their ``.request()`` and ``.free()`` semantics. 70988f8ac47SBagas SanjayaLikewise the ``pinctrl_gpio_direction_input()`` / ``pinctrl_gpio_direction_output()`` 71088f8ac47SBagas Sanjayashall only be called from within respective ``.direction_input()`` / 71188f8ac47SBagas Sanjaya``.direction_output()`` gpiolib implementation. 7125513b411SDrew Fustini 7135513b411SDrew FustiniNOTE that platforms and individual drivers shall *NOT* request GPIO pins to be 7145513b411SDrew Fustinicontrolled e.g. muxed in. Instead, implement a proper gpiolib driver and have 7155513b411SDrew Fustinithat driver request proper muxing and other control for its pins. 7165513b411SDrew Fustini 7175513b411SDrew FustiniThe function list could become long, especially if you can convert every 7185513b411SDrew Fustiniindividual pin into a GPIO pin independent of any other pins, and then try 7195513b411SDrew Fustinithe approach to define every pin as a function. 7205513b411SDrew Fustini 7215513b411SDrew FustiniIn this case, the function array would become 64 entries for each GPIO 7225513b411SDrew Fustinisetting and then the device functions. 7235513b411SDrew Fustini 7245513b411SDrew FustiniFor this reason there are two functions a pin control driver can implement 72588f8ac47SBagas Sanjayato enable only GPIO on an individual pin: ``.gpio_request_enable()`` and 72688f8ac47SBagas Sanjaya``.gpio_disable_free()``. 7275513b411SDrew Fustini 7285513b411SDrew FustiniThis function will pass in the affected GPIO range identified by the pin 7295513b411SDrew Fustinicontroller core, so you know which GPIO pins are being affected by the request 7305513b411SDrew Fustinioperation. 7315513b411SDrew Fustini 7325513b411SDrew FustiniIf your driver needs to have an indication from the framework of whether the 7335513b411SDrew FustiniGPIO pin shall be used for input or output you can implement the 73488f8ac47SBagas Sanjaya``.gpio_set_direction()`` function. As described this shall be called from the 7355513b411SDrew Fustinigpiolib driver and the affected GPIO range, pin offset and desired direction 7365513b411SDrew Fustiniwill be passed along to this function. 7375513b411SDrew Fustini 7385513b411SDrew FustiniAlternatively to using these special functions, it is fully allowed to use 73988f8ac47SBagas Sanjayanamed functions for each GPIO pin, the ``pinctrl_gpio_request()`` will attempt to 7405513b411SDrew Fustiniobtain the function "gpioN" where "N" is the global GPIO pin number if no 7415513b411SDrew Fustinispecial GPIO-handler is registered. 7425513b411SDrew Fustini 7435513b411SDrew Fustini 7445513b411SDrew FustiniGPIO mode pitfalls 7455513b411SDrew Fustini================== 7465513b411SDrew Fustini 7475513b411SDrew FustiniDue to the naming conventions used by hardware engineers, where "GPIO" 7485513b411SDrew Fustiniis taken to mean different things than what the kernel does, the developer 7495513b411SDrew Fustinimay be confused by a datasheet talking about a pin being possible to set 7505513b411SDrew Fustiniinto "GPIO mode". It appears that what hardware engineers mean with 7515513b411SDrew Fustini"GPIO mode" is not necessarily the use case that is implied in the kernel 75288f8ac47SBagas Sanjayainterface ``<linux/gpio/consumer.h>``: a pin that you grab from kernel code and then 7535513b411SDrew Fustinieither listen for input or drive high/low to assert/deassert some 7545513b411SDrew Fustiniexternal line. 7555513b411SDrew Fustini 7565513b411SDrew FustiniRather hardware engineers think that "GPIO mode" means that you can 7575513b411SDrew Fustinisoftware-control a few electrical properties of the pin that you would 7585513b411SDrew Fustininot be able to control if the pin was in some other mode, such as muxed in 7595513b411SDrew Fustinifor a device. 7605513b411SDrew Fustini 7615513b411SDrew FustiniThe GPIO portions of a pin and its relation to a certain pin controller 7625513b411SDrew Fustiniconfiguration and muxing logic can be constructed in several ways. Here 763af6f64c6SAndy Shevchenkoare two examples. 7645513b411SDrew Fustini 765af6f64c6SAndy ShevchenkoExample **(A)**:: 766af6f64c6SAndy Shevchenko 7675513b411SDrew Fustini pin config 7685513b411SDrew Fustini logic regs 7695513b411SDrew Fustini | +- SPI 7705513b411SDrew Fustini Physical pins --- pad --- pinmux -+- I2C 7715513b411SDrew Fustini | +- mmc 7725513b411SDrew Fustini | +- GPIO 7735513b411SDrew Fustini pin 7745513b411SDrew Fustini multiplex 7755513b411SDrew Fustini logic regs 7765513b411SDrew Fustini 7775513b411SDrew FustiniHere some electrical properties of the pin can be configured no matter 7785513b411SDrew Fustiniwhether the pin is used for GPIO or not. If you multiplex a GPIO onto a 7795513b411SDrew Fustinipin, you can also drive it high/low from "GPIO" registers. 7805513b411SDrew FustiniAlternatively, the pin can be controlled by a certain peripheral, while 7815513b411SDrew Fustinistill applying desired pin config properties. GPIO functionality is thus 7825513b411SDrew Fustiniorthogonal to any other device using the pin. 7835513b411SDrew Fustini 7845513b411SDrew FustiniIn this arrangement the registers for the GPIO portions of the pin controller, 7855513b411SDrew Fustinior the registers for the GPIO hardware module are likely to reside in a 7865513b411SDrew Fustiniseparate memory range only intended for GPIO driving, and the register 7875513b411SDrew Fustinirange dealing with pin config and pin multiplexing get placed into a 7885513b411SDrew Fustinidifferent memory range and a separate section of the data sheet. 7895513b411SDrew Fustini 7905513b411SDrew FustiniA flag "strict" in struct pinmux_ops is available to check and deny 7915513b411SDrew Fustinisimultaneous access to the same pin from GPIO and pin multiplexing 7925513b411SDrew Fustiniconsumers on hardware of this type. The pinctrl driver should set this flag 7935513b411SDrew Fustiniaccordingly. 7945513b411SDrew Fustini 795af6f64c6SAndy ShevchenkoExample **(B)**:: 7965513b411SDrew Fustini 7975513b411SDrew Fustini pin config 7985513b411SDrew Fustini logic regs 7995513b411SDrew Fustini | +- SPI 8005513b411SDrew Fustini Physical pins --- pad --- pinmux -+- I2C 8015513b411SDrew Fustini | | +- mmc 8025513b411SDrew Fustini | | 8035513b411SDrew Fustini GPIO pin 8045513b411SDrew Fustini multiplex 8055513b411SDrew Fustini logic regs 8065513b411SDrew Fustini 8075513b411SDrew FustiniIn this arrangement, the GPIO functionality can always be enabled, such that 8085513b411SDrew Fustinie.g. a GPIO input can be used to "spy" on the SPI/I2C/MMC signal while it is 8095513b411SDrew Fustinipulsed out. It is likely possible to disrupt the traffic on the pin by doing 8105513b411SDrew Fustiniwrong things on the GPIO block, as it is never really disconnected. It is 8115513b411SDrew Fustinipossible that the GPIO, pin config and pin multiplex registers are placed into 8125513b411SDrew Fustinithe same memory range and the same section of the data sheet, although that 8135513b411SDrew Fustinineed not be the case. 8145513b411SDrew Fustini 8155513b411SDrew FustiniIn some pin controllers, although the physical pins are designed in the same 8165513b411SDrew Fustiniway as (B), the GPIO function still can't be enabled at the same time as the 8175513b411SDrew Fustiniperipheral functions. So again the "strict" flag should be set, denying 8185513b411SDrew Fustinisimultaneous activation by GPIO and other muxed in devices. 8195513b411SDrew Fustini 8205513b411SDrew FustiniFrom a kernel point of view, however, these are different aspects of the 8215513b411SDrew Fustinihardware and shall be put into different subsystems: 8225513b411SDrew Fustini 8235513b411SDrew Fustini- Registers (or fields within registers) that control electrical 8245513b411SDrew Fustini properties of the pin such as biasing and drive strength should be 8255513b411SDrew Fustini exposed through the pinctrl subsystem, as "pin configuration" settings. 8265513b411SDrew Fustini 8275513b411SDrew Fustini- Registers (or fields within registers) that control muxing of signals 8285513b411SDrew Fustini from various other HW blocks (e.g. I2C, MMC, or GPIO) onto pins should 8295513b411SDrew Fustini be exposed through the pinctrl subsystem, as mux functions. 8305513b411SDrew Fustini 8315513b411SDrew Fustini- Registers (or fields within registers) that control GPIO functionality 8325513b411SDrew Fustini such as setting a GPIO's output value, reading a GPIO's input value, or 8335513b411SDrew Fustini setting GPIO pin direction should be exposed through the GPIO subsystem, 8345513b411SDrew Fustini and if they also support interrupt capabilities, through the irqchip 8355513b411SDrew Fustini abstraction. 8365513b411SDrew Fustini 8375513b411SDrew FustiniDepending on the exact HW register design, some functions exposed by the 8385513b411SDrew FustiniGPIO subsystem may call into the pinctrl subsystem in order to 8397852fe3aSRandy Dunlapcoordinate register settings across HW modules. In particular, this may 8405513b411SDrew Fustinibe needed for HW with separate GPIO and pin controller HW modules, where 8415513b411SDrew Fustinie.g. GPIO direction is determined by a register in the pin controller HW 8425513b411SDrew Fustinimodule rather than the GPIO HW module. 8435513b411SDrew Fustini 8445513b411SDrew FustiniElectrical properties of the pin such as biasing and drive strength 8455513b411SDrew Fustinimay be placed at some pin-specific register in all cases or as part 8465513b411SDrew Fustiniof the GPIO register in case (B) especially. This doesn't mean that such 8475513b411SDrew Fustiniproperties necessarily pertain to what the Linux kernel calls "GPIO". 8485513b411SDrew Fustini 8495513b411SDrew FustiniExample: a pin is usually muxed in to be used as a UART TX line. But during 8505513b411SDrew Fustinisystem sleep, we need to put this pin into "GPIO mode" and ground it. 8515513b411SDrew Fustini 8525513b411SDrew FustiniIf you make a 1-to-1 map to the GPIO subsystem for this pin, you may start 8535513b411SDrew Fustinito think that you need to come up with something really complex, that the 8545513b411SDrew Fustinipin shall be used for UART TX and GPIO at the same time, that you will grab 8555513b411SDrew Fustinia pin control handle and set it to a certain state to enable UART TX to be 856af6f64c6SAndy Shevchenkomuxed in, then twist it over to GPIO mode and use gpiod_direction_output() 8575513b411SDrew Fustinito drive it low during sleep, then mux it over to UART TX again when you 858af6f64c6SAndy Shevchenkowake up and maybe even gpiod_get() / gpiod_put() as part of this cycle. This 8595513b411SDrew Fustiniall gets very complicated. 8605513b411SDrew Fustini 8615513b411SDrew FustiniThe solution is to not think that what the datasheet calls "GPIO mode" 86288f8ac47SBagas Sanjayahas to be handled by the ``<linux/gpio/consumer.h>`` interface. Instead view this as 86388f8ac47SBagas Sanjayaa certain pin config setting. Look in e.g. ``<linux/pinctrl/pinconf-generic.h>`` 8645513b411SDrew Fustiniand you find this in the documentation: 8655513b411SDrew Fustini 8665513b411SDrew Fustini PIN_CONFIG_OUTPUT: 8675513b411SDrew Fustini this will configure the pin in output, use argument 8685513b411SDrew Fustini 1 to indicate high level, argument 0 to indicate low level. 8695513b411SDrew Fustini 8705513b411SDrew FustiniSo it is perfectly possible to push a pin into "GPIO mode" and drive the 8715513b411SDrew Fustiniline low as part of the usual pin control map. So for example your UART 872af6f64c6SAndy Shevchenkodriver may look like this: 873af6f64c6SAndy Shevchenko 874af6f64c6SAndy Shevchenko.. code-block:: c 8755513b411SDrew Fustini 8765513b411SDrew Fustini #include <linux/pinctrl/consumer.h> 8775513b411SDrew Fustini 8785513b411SDrew Fustini struct pinctrl *pinctrl; 8795513b411SDrew Fustini struct pinctrl_state *pins_default; 8805513b411SDrew Fustini struct pinctrl_state *pins_sleep; 8815513b411SDrew Fustini 8825513b411SDrew Fustini pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT); 8835513b411SDrew Fustini pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP); 8845513b411SDrew Fustini 8855513b411SDrew Fustini /* Normal mode */ 8865513b411SDrew Fustini retval = pinctrl_select_state(pinctrl, pins_default); 887af6f64c6SAndy Shevchenko 8885513b411SDrew Fustini /* Sleep mode */ 8895513b411SDrew Fustini retval = pinctrl_select_state(pinctrl, pins_sleep); 8905513b411SDrew Fustini 8915513b411SDrew FustiniAnd your machine configuration may look like this: 8925513b411SDrew Fustini 893af6f64c6SAndy Shevchenko.. code-block:: c 8945513b411SDrew Fustini 8955513b411SDrew Fustini static unsigned long uart_default_mode[] = { 8965513b411SDrew Fustini PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0), 8975513b411SDrew Fustini }; 8985513b411SDrew Fustini 8995513b411SDrew Fustini static unsigned long uart_sleep_mode[] = { 9005513b411SDrew Fustini PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0), 9015513b411SDrew Fustini }; 9025513b411SDrew Fustini 9035513b411SDrew Fustini static struct pinctrl_map pinmap[] __initdata = { 9045513b411SDrew Fustini PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", 9055513b411SDrew Fustini "u0_group", "u0"), 9065513b411SDrew Fustini PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo", 9075513b411SDrew Fustini "UART_TX_PIN", uart_default_mode), 9085513b411SDrew Fustini PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", 9095513b411SDrew Fustini "u0_group", "gpio-mode"), 9105513b411SDrew Fustini PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo", 9115513b411SDrew Fustini "UART_TX_PIN", uart_sleep_mode), 9125513b411SDrew Fustini }; 9135513b411SDrew Fustini 914af6f64c6SAndy Shevchenko foo_init(void) 915af6f64c6SAndy Shevchenko { 9165513b411SDrew Fustini pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap)); 9175513b411SDrew Fustini } 9185513b411SDrew Fustini 9195513b411SDrew FustiniHere the pins we want to control are in the "u0_group" and there is some 9205513b411SDrew Fustinifunction called "u0" that can be enabled on this group of pins, and then 9215513b411SDrew Fustinieverything is UART business as usual. But there is also some function 9225513b411SDrew Fustininamed "gpio-mode" that can be mapped onto the same pins to move them into 9235513b411SDrew FustiniGPIO mode. 9245513b411SDrew Fustini 9255513b411SDrew FustiniThis will give the desired effect without any bogus interaction with the 9265513b411SDrew FustiniGPIO subsystem. It is just an electrical configuration used by that device 9275513b411SDrew Fustiniwhen going to sleep, it might imply that the pin is set into something the 9285513b411SDrew Fustinidatasheet calls "GPIO mode", but that is not the point: it is still used 9295513b411SDrew Fustiniby that UART device to control the pins that pertain to that very UART 9305513b411SDrew Fustinidriver, putting them into modes needed by the UART. GPIO in the Linux 9315513b411SDrew Fustinikernel sense are just some 1-bit line, and is a different use case. 9325513b411SDrew Fustini 9335513b411SDrew FustiniHow the registers are poked to attain the push or pull, and output low 9345513b411SDrew Fustiniconfiguration and the muxing of the "u0" or "gpio-mode" group onto these 9355513b411SDrew Fustinipins is a question for the driver. 9365513b411SDrew Fustini 9375513b411SDrew FustiniSome datasheets will be more helpful and refer to the "GPIO mode" as 9385513b411SDrew Fustini"low power mode" rather than anything to do with GPIO. This often means 9395513b411SDrew Fustinithe same thing electrically speaking, but in this latter case the 9405513b411SDrew Fustinisoftware engineers will usually quickly identify that this is some 9415513b411SDrew Fustinispecific muxing or configuration rather than anything related to the GPIO 9425513b411SDrew FustiniAPI. 9435513b411SDrew Fustini 9445513b411SDrew Fustini 9455513b411SDrew FustiniBoard/machine configuration 9465513b411SDrew Fustini=========================== 9475513b411SDrew Fustini 9485513b411SDrew FustiniBoards and machines define how a certain complete running system is put 9495513b411SDrew Fustinitogether, including how GPIOs and devices are muxed, how regulators are 9505513b411SDrew Fustiniconstrained and how the clock tree looks. Of course pinmux settings are also 9515513b411SDrew Fustinipart of this. 9525513b411SDrew Fustini 9535513b411SDrew FustiniA pin controller configuration for a machine looks pretty much like a simple 9545513b411SDrew Fustiniregulator configuration, so for the example array above we want to enable i2c 955af6f64c6SAndy Shevchenkoand spi on the second function mapping: 956af6f64c6SAndy Shevchenko 957af6f64c6SAndy Shevchenko.. code-block:: c 9585513b411SDrew Fustini 9595513b411SDrew Fustini #include <linux/pinctrl/machine.h> 9605513b411SDrew Fustini 9615513b411SDrew Fustini static const struct pinctrl_map mapping[] __initconst = { 9625513b411SDrew Fustini { 9635513b411SDrew Fustini .dev_name = "foo-spi.0", 9645513b411SDrew Fustini .name = PINCTRL_STATE_DEFAULT, 9655513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 9665513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 9675513b411SDrew Fustini .data.mux.function = "spi0", 9685513b411SDrew Fustini }, 9695513b411SDrew Fustini { 9705513b411SDrew Fustini .dev_name = "foo-i2c.0", 9715513b411SDrew Fustini .name = PINCTRL_STATE_DEFAULT, 9725513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 9735513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 9745513b411SDrew Fustini .data.mux.function = "i2c0", 9755513b411SDrew Fustini }, 9765513b411SDrew Fustini { 9775513b411SDrew Fustini .dev_name = "foo-mmc.0", 9785513b411SDrew Fustini .name = PINCTRL_STATE_DEFAULT, 9795513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 9805513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 9815513b411SDrew Fustini .data.mux.function = "mmc0", 9825513b411SDrew Fustini }, 9835513b411SDrew Fustini }; 9845513b411SDrew Fustini 9855513b411SDrew FustiniThe dev_name here matches to the unique device name that can be used to look 9865513b411SDrew Fustiniup the device struct (just like with clockdev or regulators). The function name 9875513b411SDrew Fustinimust match a function provided by the pinmux driver handling this pin range. 9885513b411SDrew Fustini 9895513b411SDrew FustiniAs you can see we may have several pin controllers on the system and thus 9905513b411SDrew Fustiniwe need to specify which one of them contains the functions we wish to map. 9915513b411SDrew Fustini 992af6f64c6SAndy ShevchenkoYou register this pinmux mapping to the pinmux subsystem by simply: 993af6f64c6SAndy Shevchenko 994af6f64c6SAndy Shevchenko.. code-block:: c 9955513b411SDrew Fustini 9965513b411SDrew Fustini ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping)); 9975513b411SDrew Fustini 9985513b411SDrew FustiniSince the above construct is pretty common there is a helper macro to make 9995513b411SDrew Fustiniit even more compact which assumes you want to use pinctrl-foo and position 1000af6f64c6SAndy Shevchenko0 for mapping, for example: 1001af6f64c6SAndy Shevchenko 1002af6f64c6SAndy Shevchenko.. code-block:: c 10035513b411SDrew Fustini 10045513b411SDrew Fustini static struct pinctrl_map mapping[] __initdata = { 1005*f8e52fb8SMarc Ferland PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, 10065513b411SDrew Fustini "pinctrl-foo", NULL, "i2c0"), 10075513b411SDrew Fustini }; 10085513b411SDrew Fustini 10095513b411SDrew FustiniThe mapping table may also contain pin configuration entries. It's common for 10105513b411SDrew Fustinieach pin/group to have a number of configuration entries that affect it, so 10115513b411SDrew Fustinithe table entries for configuration reference an array of config parameters 1012af6f64c6SAndy Shevchenkoand values. An example using the convenience macros is shown below: 1013af6f64c6SAndy Shevchenko 1014af6f64c6SAndy Shevchenko.. code-block:: c 10155513b411SDrew Fustini 10165513b411SDrew Fustini static unsigned long i2c_grp_configs[] = { 10175513b411SDrew Fustini FOO_PIN_DRIVEN, 10185513b411SDrew Fustini FOO_PIN_PULLUP, 10195513b411SDrew Fustini }; 10205513b411SDrew Fustini 10215513b411SDrew Fustini static unsigned long i2c_pin_configs[] = { 10225513b411SDrew Fustini FOO_OPEN_COLLECTOR, 10235513b411SDrew Fustini FOO_SLEW_RATE_SLOW, 10245513b411SDrew Fustini }; 10255513b411SDrew Fustini 10265513b411SDrew Fustini static struct pinctrl_map mapping[] __initdata = { 10275513b411SDrew Fustini PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, 10285513b411SDrew Fustini "pinctrl-foo", "i2c0", "i2c0"), 10295513b411SDrew Fustini PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, 10305513b411SDrew Fustini "pinctrl-foo", "i2c0", i2c_grp_configs), 10315513b411SDrew Fustini PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, 10325513b411SDrew Fustini "pinctrl-foo", "i2c0scl", i2c_pin_configs), 10335513b411SDrew Fustini PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, 10345513b411SDrew Fustini "pinctrl-foo", "i2c0sda", i2c_pin_configs), 10355513b411SDrew Fustini }; 10365513b411SDrew Fustini 10375513b411SDrew FustiniFinally, some devices expect the mapping table to contain certain specific 10385513b411SDrew Fustininamed states. When running on hardware that doesn't need any pin controller 10395513b411SDrew Fustiniconfiguration, the mapping table must still contain those named states, in 10405513b411SDrew Fustiniorder to explicitly indicate that the states were provided and intended to 104188f8ac47SBagas Sanjayabe empty. Table entry macro ``PIN_MAP_DUMMY_STATE()`` serves the purpose of defining 1042af6f64c6SAndy Shevchenkoa named state without causing any pin controller to be programmed: 1043af6f64c6SAndy Shevchenko 1044af6f64c6SAndy Shevchenko.. code-block:: c 10455513b411SDrew Fustini 10465513b411SDrew Fustini static struct pinctrl_map mapping[] __initdata = { 10475513b411SDrew Fustini PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT), 10485513b411SDrew Fustini }; 10495513b411SDrew Fustini 10505513b411SDrew Fustini 10515513b411SDrew FustiniComplex mappings 10525513b411SDrew Fustini================ 10535513b411SDrew Fustini 10545513b411SDrew FustiniAs it is possible to map a function to different groups of pins an optional 1055af6f64c6SAndy Shevchenko.group can be specified like this: 1056af6f64c6SAndy Shevchenko 1057af6f64c6SAndy Shevchenko.. code-block:: c 10585513b411SDrew Fustini 10595513b411SDrew Fustini ... 10605513b411SDrew Fustini { 10615513b411SDrew Fustini .dev_name = "foo-spi.0", 10625513b411SDrew Fustini .name = "spi0-pos-A", 10635513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 10645513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 10655513b411SDrew Fustini .function = "spi0", 10665513b411SDrew Fustini .group = "spi0_0_grp", 10675513b411SDrew Fustini }, 10685513b411SDrew Fustini { 10695513b411SDrew Fustini .dev_name = "foo-spi.0", 10705513b411SDrew Fustini .name = "spi0-pos-B", 10715513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 10725513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 10735513b411SDrew Fustini .function = "spi0", 10745513b411SDrew Fustini .group = "spi0_1_grp", 10755513b411SDrew Fustini }, 10765513b411SDrew Fustini ... 10775513b411SDrew Fustini 10785513b411SDrew FustiniThis example mapping is used to switch between two positions for spi0 at 1079af6f64c6SAndy Shevchenkoruntime, as described further below under the heading `Runtime pinmuxing`_. 10805513b411SDrew Fustini 10815513b411SDrew FustiniFurther it is possible for one named state to affect the muxing of several 10825513b411SDrew Fustinigroups of pins, say for example in the mmc0 example above, where you can 10835513b411SDrew Fustiniadditively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all 10845513b411SDrew Fustinithree groups for a total of 2 + 2 + 4 = 8 pins (for an 8-bit MMC bus as is the 1085af6f64c6SAndy Shevchenkocase), we define a mapping like this: 1086af6f64c6SAndy Shevchenko 1087af6f64c6SAndy Shevchenko.. code-block:: c 10885513b411SDrew Fustini 10895513b411SDrew Fustini ... 10905513b411SDrew Fustini { 10915513b411SDrew Fustini .dev_name = "foo-mmc.0", 10925513b411SDrew Fustini .name = "2bit" 10935513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 10945513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 10955513b411SDrew Fustini .function = "mmc0", 10965513b411SDrew Fustini .group = "mmc0_1_grp", 10975513b411SDrew Fustini }, 10985513b411SDrew Fustini { 10995513b411SDrew Fustini .dev_name = "foo-mmc.0", 11005513b411SDrew Fustini .name = "4bit" 11015513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 11025513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 11035513b411SDrew Fustini .function = "mmc0", 11045513b411SDrew Fustini .group = "mmc0_1_grp", 11055513b411SDrew Fustini }, 11065513b411SDrew Fustini { 11075513b411SDrew Fustini .dev_name = "foo-mmc.0", 11085513b411SDrew Fustini .name = "4bit" 11095513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 11105513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 11115513b411SDrew Fustini .function = "mmc0", 11125513b411SDrew Fustini .group = "mmc0_2_grp", 11135513b411SDrew Fustini }, 11145513b411SDrew Fustini { 11155513b411SDrew Fustini .dev_name = "foo-mmc.0", 11165513b411SDrew Fustini .name = "8bit" 11175513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 11185513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 11195513b411SDrew Fustini .function = "mmc0", 11205513b411SDrew Fustini .group = "mmc0_1_grp", 11215513b411SDrew Fustini }, 11225513b411SDrew Fustini { 11235513b411SDrew Fustini .dev_name = "foo-mmc.0", 11245513b411SDrew Fustini .name = "8bit" 11255513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 11265513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 11275513b411SDrew Fustini .function = "mmc0", 11285513b411SDrew Fustini .group = "mmc0_2_grp", 11295513b411SDrew Fustini }, 11305513b411SDrew Fustini { 11315513b411SDrew Fustini .dev_name = "foo-mmc.0", 11325513b411SDrew Fustini .name = "8bit" 11335513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 11345513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 11355513b411SDrew Fustini .function = "mmc0", 11365513b411SDrew Fustini .group = "mmc0_3_grp", 11375513b411SDrew Fustini }, 11385513b411SDrew Fustini ... 11395513b411SDrew Fustini 11405513b411SDrew FustiniThe result of grabbing this mapping from the device with something like 1141af6f64c6SAndy Shevchenkothis (see next paragraph): 1142af6f64c6SAndy Shevchenko 1143af6f64c6SAndy Shevchenko.. code-block:: c 11445513b411SDrew Fustini 11455513b411SDrew Fustini p = devm_pinctrl_get(dev); 11465513b411SDrew Fustini s = pinctrl_lookup_state(p, "8bit"); 11475513b411SDrew Fustini ret = pinctrl_select_state(p, s); 11485513b411SDrew Fustini 1149af6f64c6SAndy Shevchenkoor more simply: 1150af6f64c6SAndy Shevchenko 1151af6f64c6SAndy Shevchenko.. code-block:: c 11525513b411SDrew Fustini 11535513b411SDrew Fustini p = devm_pinctrl_get_select(dev, "8bit"); 11545513b411SDrew Fustini 11555513b411SDrew FustiniWill be that you activate all the three bottom records in the mapping at 11565513b411SDrew Fustinionce. Since they share the same name, pin controller device, function and 11575513b411SDrew Fustinidevice, and since we allow multiple groups to match to a single device, they 11585513b411SDrew Fustiniall get selected, and they all get enabled and disable simultaneously by the 11595513b411SDrew Fustinipinmux core. 11605513b411SDrew Fustini 11615513b411SDrew Fustini 11625513b411SDrew FustiniPin control requests from drivers 11635513b411SDrew Fustini================================= 11645513b411SDrew Fustini 11655513b411SDrew FustiniWhen a device driver is about to probe the device core will automatically 116688f8ac47SBagas Sanjayaattempt to issue ``pinctrl_get_select_default()`` on these devices. 11675513b411SDrew FustiniThis way driver writers do not need to add any of the boilerplate code 11685513b411SDrew Fustiniof the type found below. However when doing fine-grained state selection 11695513b411SDrew Fustiniand not using the "default" state, you may have to do some device driver 11705513b411SDrew Fustinihandling of the pinctrl handles and states. 11715513b411SDrew Fustini 11725513b411SDrew FustiniSo if you just want to put the pins for a certain device into the default 11735513b411SDrew Fustinistate and be done with it, there is nothing you need to do besides 11745513b411SDrew Fustiniproviding the proper mapping table. The device core will take care of 11755513b411SDrew Fustinithe rest. 11765513b411SDrew Fustini 11775513b411SDrew FustiniGenerally it is discouraged to let individual drivers get and enable pin 11785513b411SDrew Fustinicontrol. So if possible, handle the pin control in platform code or some other 11795513b411SDrew Fustiniplace where you have access to all the affected struct device * pointers. In 11805513b411SDrew Fustinisome cases where a driver needs to e.g. switch between different mux mappings 11815513b411SDrew Fustiniat runtime this is not possible. 11825513b411SDrew Fustini 11835513b411SDrew FustiniA typical case is if a driver needs to switch bias of pins from normal 118488f8ac47SBagas Sanjayaoperation and going to sleep, moving from the ``PINCTRL_STATE_DEFAULT`` to 118588f8ac47SBagas Sanjaya``PINCTRL_STATE_SLEEP`` at runtime, re-biasing or even re-muxing pins to save 11865513b411SDrew Fustinicurrent in sleep mode. 11875513b411SDrew Fustini 11885513b411SDrew FustiniA driver may request a certain control state to be activated, usually just the 1189af6f64c6SAndy Shevchenkodefault state like this: 1190af6f64c6SAndy Shevchenko 1191af6f64c6SAndy Shevchenko.. code-block:: c 11925513b411SDrew Fustini 11935513b411SDrew Fustini #include <linux/pinctrl/consumer.h> 11945513b411SDrew Fustini 11955513b411SDrew Fustini struct foo_state { 11965513b411SDrew Fustini struct pinctrl *p; 11975513b411SDrew Fustini struct pinctrl_state *s; 11985513b411SDrew Fustini ... 11995513b411SDrew Fustini }; 12005513b411SDrew Fustini 12015513b411SDrew Fustini foo_probe() 12025513b411SDrew Fustini { 12035513b411SDrew Fustini /* Allocate a state holder named "foo" etc */ 12045513b411SDrew Fustini struct foo_state *foo = ...; 12055513b411SDrew Fustini 12065513b411SDrew Fustini foo->p = devm_pinctrl_get(&device); 12075513b411SDrew Fustini if (IS_ERR(foo->p)) { 12085513b411SDrew Fustini /* FIXME: clean up "foo" here */ 12095513b411SDrew Fustini return PTR_ERR(foo->p); 12105513b411SDrew Fustini } 12115513b411SDrew Fustini 12125513b411SDrew Fustini foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT); 12135513b411SDrew Fustini if (IS_ERR(foo->s)) { 12145513b411SDrew Fustini /* FIXME: clean up "foo" here */ 1215775c93a7SNiklas Söderlund return PTR_ERR(foo->s); 12165513b411SDrew Fustini } 12175513b411SDrew Fustini 1218c1542be1SSiarhei Volkau ret = pinctrl_select_state(foo->p, foo->s); 12195513b411SDrew Fustini if (ret < 0) { 12205513b411SDrew Fustini /* FIXME: clean up "foo" here */ 12215513b411SDrew Fustini return ret; 12225513b411SDrew Fustini } 12235513b411SDrew Fustini } 12245513b411SDrew Fustini 12255513b411SDrew FustiniThis get/lookup/select/put sequence can just as well be handled by bus drivers 12265513b411SDrew Fustiniif you don't want each and every driver to handle it and you know the 12275513b411SDrew Fustiniarrangement on your bus. 12285513b411SDrew Fustini 12295513b411SDrew FustiniThe semantics of the pinctrl APIs are: 12305513b411SDrew Fustini 123188f8ac47SBagas Sanjaya- ``pinctrl_get()`` is called in process context to obtain a handle to all pinctrl 12325513b411SDrew Fustini information for a given client device. It will allocate a struct from the 12335513b411SDrew Fustini kernel memory to hold the pinmux state. All mapping table parsing or similar 12345513b411SDrew Fustini slow operations take place within this API. 12355513b411SDrew Fustini 123688f8ac47SBagas Sanjaya- ``devm_pinctrl_get()`` is a variant of pinctrl_get() that causes ``pinctrl_put()`` 12375513b411SDrew Fustini to be called automatically on the retrieved pointer when the associated 12385513b411SDrew Fustini device is removed. It is recommended to use this function over plain 123988f8ac47SBagas Sanjaya ``pinctrl_get()``. 12405513b411SDrew Fustini 124188f8ac47SBagas Sanjaya- ``pinctrl_lookup_state()`` is called in process context to obtain a handle to a 12425513b411SDrew Fustini specific state for a client device. This operation may be slow, too. 12435513b411SDrew Fustini 124488f8ac47SBagas Sanjaya- ``pinctrl_select_state()`` programs pin controller hardware according to the 12455513b411SDrew Fustini definition of the state as given by the mapping table. In theory, this is a 12465513b411SDrew Fustini fast-path operation, since it only involved blasting some register settings 12475513b411SDrew Fustini into hardware. However, note that some pin controllers may have their 12485513b411SDrew Fustini registers on a slow/IRQ-based bus, so client devices should not assume they 124988f8ac47SBagas Sanjaya can call ``pinctrl_select_state()`` from non-blocking contexts. 12505513b411SDrew Fustini 125188f8ac47SBagas Sanjaya- ``pinctrl_put()`` frees all information associated with a pinctrl handle. 12525513b411SDrew Fustini 125388f8ac47SBagas Sanjaya- ``devm_pinctrl_put()`` is a variant of ``pinctrl_put()`` that may be used to 125488f8ac47SBagas Sanjaya explicitly destroy a pinctrl object returned by ``devm_pinctrl_get()``. 12555513b411SDrew Fustini However, use of this function will be rare, due to the automatic cleanup 12565513b411SDrew Fustini that will occur even without calling it. 12575513b411SDrew Fustini 125888f8ac47SBagas Sanjaya ``pinctrl_get()`` must be paired with a plain ``pinctrl_put()``. 125988f8ac47SBagas Sanjaya ``pinctrl_get()`` may not be paired with ``devm_pinctrl_put()``. 126088f8ac47SBagas Sanjaya ``devm_pinctrl_get()`` can optionally be paired with ``devm_pinctrl_put()``. 126188f8ac47SBagas Sanjaya ``devm_pinctrl_get()`` may not be paired with plain ``pinctrl_put()``. 12625513b411SDrew Fustini 12635513b411SDrew FustiniUsually the pin control core handled the get/put pair and call out to the 12645513b411SDrew Fustinidevice drivers bookkeeping operations, like checking available functions and 126588f8ac47SBagas Sanjayathe associated pins, whereas ``pinctrl_select_state()`` pass on to the pin controller 12665513b411SDrew Fustinidriver which takes care of activating and/or deactivating the mux setting by 12675513b411SDrew Fustiniquickly poking some registers. 12685513b411SDrew Fustini 126988f8ac47SBagas SanjayaThe pins are allocated for your device when you issue the ``devm_pinctrl_get()`` 12705513b411SDrew Fustinicall, after this you should be able to see this in the debugfs listing of all 12715513b411SDrew Fustinipins. 12725513b411SDrew Fustini 127388f8ac47SBagas SanjayaNOTE: the pinctrl system will return ``-EPROBE_DEFER`` if it cannot find the 12745513b411SDrew Fustinirequested pinctrl handles, for example if the pinctrl driver has not yet 12755513b411SDrew Fustiniregistered. Thus make sure that the error path in your driver gracefully 12765513b411SDrew Fustinicleans up and is ready to retry the probing later in the startup process. 12775513b411SDrew Fustini 12785513b411SDrew Fustini 12795513b411SDrew FustiniDrivers needing both pin control and GPIOs 12805513b411SDrew Fustini========================================== 12815513b411SDrew Fustini 12825513b411SDrew FustiniAgain, it is discouraged to let drivers lookup and select pin control states 12835513b411SDrew Fustinithemselves, but again sometimes this is unavoidable. 12845513b411SDrew Fustini 1285af6f64c6SAndy ShevchenkoSo say that your driver is fetching its resources like this: 1286af6f64c6SAndy Shevchenko 1287af6f64c6SAndy Shevchenko.. code-block:: c 12885513b411SDrew Fustini 12895513b411SDrew Fustini #include <linux/pinctrl/consumer.h> 1290af6f64c6SAndy Shevchenko #include <linux/gpio/consumer.h> 12915513b411SDrew Fustini 12925513b411SDrew Fustini struct pinctrl *pinctrl; 1293af6f64c6SAndy Shevchenko struct gpio_desc *gpio; 12945513b411SDrew Fustini 12955513b411SDrew Fustini pinctrl = devm_pinctrl_get_select_default(&dev); 1296af6f64c6SAndy Shevchenko gpio = devm_gpiod_get(&dev, "foo"); 12975513b411SDrew Fustini 1298af6f64c6SAndy ShevchenkoHere we first request a certain pin state and then request GPIO "foo" to be 12995513b411SDrew Fustiniused. If you're using the subsystems orthogonally like this, you should 13005513b411SDrew Fustininominally always get your pinctrl handle and select the desired pinctrl 13015513b411SDrew Fustinistate BEFORE requesting the GPIO. This is a semantic convention to avoid 13025513b411SDrew Fustinisituations that can be electrically unpleasant, you will certainly want to 13035513b411SDrew Fustinimux in and bias pins in a certain way before the GPIO subsystems starts to 13045513b411SDrew Fustinideal with them. 13055513b411SDrew Fustini 13065513b411SDrew FustiniThe above can be hidden: using the device core, the pinctrl core may be 13075513b411SDrew Fustinisetting up the config and muxing for the pins right before the device is 13085513b411SDrew Fustiniprobing, nevertheless orthogonal to the GPIO subsystem. 13095513b411SDrew Fustini 13105513b411SDrew FustiniBut there are also situations where it makes sense for the GPIO subsystem 13115513b411SDrew Fustinito communicate directly with the pinctrl subsystem, using the latter as a 13125513b411SDrew Fustiniback-end. This is when the GPIO driver may call out to the functions 1313af6f64c6SAndy Shevchenkodescribed in the section `Pin control interaction with the GPIO subsystem`_ 13145513b411SDrew Fustiniabove. This only involves per-pin multiplexing, and will be completely 1315af6f64c6SAndy Shevchenkohidden behind the gpiod_*() function namespace. In this case, the driver 13165513b411SDrew Fustinineed not interact with the pin control subsystem at all. 13175513b411SDrew Fustini 13185513b411SDrew FustiniIf a pin control driver and a GPIO driver is dealing with the same pins 13195513b411SDrew Fustiniand the use cases involve multiplexing, you MUST implement the pin controller 13205513b411SDrew Fustinias a back-end for the GPIO driver like this, unless your hardware design 13215513b411SDrew Fustiniis such that the GPIO controller can override the pin controller's 13225513b411SDrew Fustinimultiplexing state through hardware without the need to interact with the 13235513b411SDrew Fustinipin control system. 13245513b411SDrew Fustini 13255513b411SDrew Fustini 13265513b411SDrew FustiniSystem pin control hogging 13275513b411SDrew Fustini========================== 13285513b411SDrew Fustini 13295513b411SDrew FustiniPin control map entries can be hogged by the core when the pin controller 133088f8ac47SBagas Sanjayais registered. This means that the core will attempt to call ``pinctrl_get()``, 133188f8ac47SBagas Sanjaya``pinctrl_lookup_state()`` and ``pinctrl_select_state()`` on it immediately after 1332af6f64c6SAndy Shevchenkothe pin control device has been registered. 13335513b411SDrew Fustini 13345513b411SDrew FustiniThis occurs for mapping table entries where the client device name is equal 133588f8ac47SBagas Sanjayato the pin controller device name, and the state name is ``PINCTRL_STATE_DEFAULT``: 1336af6f64c6SAndy Shevchenko 1337af6f64c6SAndy Shevchenko.. code-block:: c 13385513b411SDrew Fustini 13395513b411SDrew Fustini { 13405513b411SDrew Fustini .dev_name = "pinctrl-foo", 13415513b411SDrew Fustini .name = PINCTRL_STATE_DEFAULT, 13425513b411SDrew Fustini .type = PIN_MAP_TYPE_MUX_GROUP, 13435513b411SDrew Fustini .ctrl_dev_name = "pinctrl-foo", 13445513b411SDrew Fustini .function = "power_func", 13455513b411SDrew Fustini }, 13465513b411SDrew Fustini 13475513b411SDrew FustiniSince it may be common to request the core to hog a few always-applicable 13485513b411SDrew Fustinimux settings on the primary pin controller, there is a convenience macro for 1349af6f64c6SAndy Shevchenkothis: 1350af6f64c6SAndy Shevchenko 1351af6f64c6SAndy Shevchenko.. code-block:: c 13525513b411SDrew Fustini 13535513b411SDrew Fustini PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, 13545513b411SDrew Fustini "power_func") 13555513b411SDrew Fustini 13565513b411SDrew FustiniThis gives the exact same result as the above construction. 13575513b411SDrew Fustini 13585513b411SDrew Fustini 13595513b411SDrew FustiniRuntime pinmuxing 13605513b411SDrew Fustini================= 13615513b411SDrew Fustini 13625513b411SDrew FustiniIt is possible to mux a certain function in and out at runtime, say to move 13635513b411SDrew Fustinian SPI port from one set of pins to another set of pins. Say for example for 13645513b411SDrew Fustinispi0 in the example above, we expose two different groups of pins for the same 13655513b411SDrew Fustinifunction, but with different named in the mapping as described under 13665513b411SDrew Fustini"Advanced mapping" above. So that for an SPI device, we have two states named 13675513b411SDrew Fustini"pos-A" and "pos-B". 13685513b411SDrew Fustini 13695513b411SDrew FustiniThis snippet first initializes a state object for both groups (in foo_probe()), 13705513b411SDrew Fustinithen muxes the function in the pins defined by group A, and finally muxes it in 1371af6f64c6SAndy Shevchenkoon the pins defined by group B: 1372af6f64c6SAndy Shevchenko 1373af6f64c6SAndy Shevchenko.. code-block:: c 13745513b411SDrew Fustini 13755513b411SDrew Fustini #include <linux/pinctrl/consumer.h> 13765513b411SDrew Fustini 13775513b411SDrew Fustini struct pinctrl *p; 13785513b411SDrew Fustini struct pinctrl_state *s1, *s2; 13795513b411SDrew Fustini 13805513b411SDrew Fustini foo_probe() 13815513b411SDrew Fustini { 13825513b411SDrew Fustini /* Setup */ 13835513b411SDrew Fustini p = devm_pinctrl_get(&device); 13845513b411SDrew Fustini if (IS_ERR(p)) 13855513b411SDrew Fustini ... 13865513b411SDrew Fustini 13874829297cSSiarhei Volkau s1 = pinctrl_lookup_state(p, "pos-A"); 13885513b411SDrew Fustini if (IS_ERR(s1)) 13895513b411SDrew Fustini ... 13905513b411SDrew Fustini 13914829297cSSiarhei Volkau s2 = pinctrl_lookup_state(p, "pos-B"); 13925513b411SDrew Fustini if (IS_ERR(s2)) 13935513b411SDrew Fustini ... 13945513b411SDrew Fustini } 13955513b411SDrew Fustini 13965513b411SDrew Fustini foo_switch() 13975513b411SDrew Fustini { 13985513b411SDrew Fustini /* Enable on position A */ 1399c1542be1SSiarhei Volkau ret = pinctrl_select_state(p, s1); 14005513b411SDrew Fustini if (ret < 0) 14015513b411SDrew Fustini ... 14025513b411SDrew Fustini 14035513b411SDrew Fustini ... 14045513b411SDrew Fustini 14055513b411SDrew Fustini /* Enable on position B */ 1406c1542be1SSiarhei Volkau ret = pinctrl_select_state(p, s2); 14075513b411SDrew Fustini if (ret < 0) 14085513b411SDrew Fustini ... 14095513b411SDrew Fustini 14105513b411SDrew Fustini ... 14115513b411SDrew Fustini } 14125513b411SDrew Fustini 14135513b411SDrew FustiniThe above has to be done from process context. The reservation of the pins 14145513b411SDrew Fustiniwill be done when the state is activated, so in effect one specific pin 14155513b411SDrew Fustinican be used by different functions at different times on a running system. 14161ae6478bSDrew Fustini 14171ae6478bSDrew Fustini 14181ae6478bSDrew FustiniDebugfs files 14191ae6478bSDrew Fustini============= 1420af6f64c6SAndy Shevchenko 14211ae6478bSDrew FustiniThese files are created in ``/sys/kernel/debug/pinctrl``: 14221ae6478bSDrew Fustini 14231ae6478bSDrew Fustini- ``pinctrl-devices``: prints each pin controller device along with columns to 14241ae6478bSDrew Fustini indicate support for pinmux and pinconf 14251ae6478bSDrew Fustini 14261ae6478bSDrew Fustini- ``pinctrl-handles``: prints each configured pin controller handle and the 14271ae6478bSDrew Fustini corresponding pinmux maps 14281ae6478bSDrew Fustini 1429af6f64c6SAndy Shevchenko- ``pinctrl-maps``: prints all pinctrl maps 14301ae6478bSDrew Fustini 14311ae6478bSDrew FustiniA sub-directory is created inside of ``/sys/kernel/debug/pinctrl`` for each pin 14321ae6478bSDrew Fustinicontroller device containing these files: 14331ae6478bSDrew Fustini 14341ae6478bSDrew Fustini- ``pins``: prints a line for each pin registered on the pin controller. The 14351ae6478bSDrew Fustini pinctrl driver may add additional information such as register contents. 14361ae6478bSDrew Fustini 1437af6f64c6SAndy Shevchenko- ``gpio-ranges``: prints ranges that map gpio lines to pins on the controller 14381ae6478bSDrew Fustini 1439af6f64c6SAndy Shevchenko- ``pingroups``: prints all pin groups registered on the pin controller 14401ae6478bSDrew Fustini 1441af6f64c6SAndy Shevchenko- ``pinconf-pins``: prints pin config settings for each pin 14421ae6478bSDrew Fustini 1443af6f64c6SAndy Shevchenko- ``pinconf-groups``: prints pin config settings per pin group 14441ae6478bSDrew Fustini 1445af6f64c6SAndy Shevchenko- ``pinmux-functions``: prints each pin function along with the pin groups that 14461ae6478bSDrew Fustini map to the pin function 14471ae6478bSDrew Fustini 1448af6f64c6SAndy Shevchenko- ``pinmux-pins``: iterates through all pins and prints mux owner, gpio owner 14491ae6478bSDrew Fustini and if the pin is a hog 14501ae6478bSDrew Fustini 1451af6f64c6SAndy Shevchenko- ``pinmux-select``: write to this file to activate a pin function for a group: 1452af6f64c6SAndy Shevchenko 1453af6f64c6SAndy Shevchenko .. code-block:: sh 14541ae6478bSDrew Fustini 14551ae6478bSDrew Fustini echo "<group-name function-name>" > pinmux-select 1456