1============= 2GPIO Mappings 3============= 4 5This document explains how GPIOs can be assigned to given devices and functions. 6 7Note that it only applies to the new descriptor-based interface. For a 8description of the deprecated integer-based GPIO interface please refer to 9legacy.rst (actually, there is no real mapping possible with the old 10interface; you just fetch an integer from somewhere and request the 11corresponding GPIO). 12 13All platforms can enable the GPIO library, but if the platform strictly 14requires GPIO functionality to be present, it needs to select GPIOLIB from its 15Kconfig. Then, how GPIOs are mapped depends on what the platform uses to 16describe its hardware layout. Currently, mappings can be defined through device 17tree, ACPI, and platform data. 18 19Device Tree 20----------- 21GPIOs can easily be mapped to devices and functions in the device tree. The 22exact way to do it depends on the GPIO controller providing the GPIOs, see the 23device tree bindings for your controller. 24 25GPIOs mappings are defined in the consumer device's node, in a property named 26<function>-gpios, where <function> is the function the driver will request 27through gpiod_get(). For example:: 28 29 foo_device { 30 compatible = "acme,foo"; 31 ... 32 led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */ 33 <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */ 34 <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */ 35 36 power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>; 37 }; 38 39Properties named <function>-gpio are also considered valid and old bindings use 40it but are only supported for compatibility reasons and should not be used for 41newer bindings since it has been deprecated. 42 43This property will make GPIOs 15, 16 and 17 available to the driver under the 44"led" function, and GPIO 1 as the "power" GPIO:: 45 46 struct gpio_desc *red, *green, *blue, *power; 47 48 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH); 49 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH); 50 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH); 51 52 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); 53 54The led GPIOs will be active high, while the power GPIO will be active low (i.e. 55gpiod_is_active_low(power) will be true). 56 57The second parameter of the gpiod_get() functions, the con_id string, has to be 58the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically 59looked up by the gpiod functions internally) used in the device tree. With above 60"led-gpios" example, use the prefix without the "-" as con_id parameter: "led". 61 62Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio") 63with the string passed in con_id to get the resulting string 64(``snprintf(... "%s-%s", con_id, gpio_suffixes[]``). 65 66ACPI 67---- 68ACPI also supports function names for GPIOs in a similar fashion to DT. 69The above DT example can be converted to an equivalent ACPI description 70with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:: 71 72 Device (FOO) { 73 Name (_CRS, ResourceTemplate () { 74 GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, 75 "\\_SB.GPI0", 0, ResourceConsumer) { 15 } // red 76 GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, 77 "\\_SB.GPI0", 0, ResourceConsumer) { 16 } // green 78 GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, 79 "\\_SB.GPI0", 0, ResourceConsumer) { 17 } // blue 80 GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly, 81 "\\_SB.GPI0", 0, ResourceConsumer) { 1 } // power 82 }) 83 84 Name (_DSD, Package () { 85 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 86 Package () { 87 Package () { 88 "led-gpios", 89 Package () { 90 ^FOO, 0, 0, 1, 91 ^FOO, 1, 0, 1, 92 ^FOO, 2, 0, 1, 93 } 94 }, 95 Package () { "power-gpios", Package () { ^FOO, 3, 0, 0 } }, 96 } 97 }) 98 } 99 100For more information about the ACPI GPIO bindings see 101Documentation/firmware-guide/acpi/gpio-properties.rst. 102 103Platform Data 104------------- 105Finally, GPIOs can be bound to devices and functions using platform data. Board 106files that desire to do so need to include the following header:: 107 108 #include <linux/gpio/machine.h> 109 110GPIOs are mapped by the means of tables of lookups, containing instances of the 111gpiod_lookup structure. Two macros are defined to help declaring such mappings:: 112 113 GPIO_LOOKUP(key, chip_hwnum, con_id, flags) 114 GPIO_LOOKUP_IDX(key, chip_hwnum, con_id, idx, flags) 115 116where 117 118 - key is either the label of the gpiod_chip instance providing the GPIO, or 119 the GPIO line name 120 - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX 121 to indicate that key is a GPIO line name 122 - con_id is the name of the GPIO function from the device point of view. It 123 can be NULL, in which case it will match any function. 124 - idx is the index of the GPIO within the function. 125 - flags is defined to specify the following properties: 126 * GPIO_ACTIVE_HIGH - GPIO line is active high 127 * GPIO_ACTIVE_LOW - GPIO line is active low 128 * GPIO_OPEN_DRAIN - GPIO line is set up as open drain 129 * GPIO_OPEN_SOURCE - GPIO line is set up as open source 130 * GPIO_PERSISTENT - GPIO line is persistent during 131 suspend/resume and maintains its value 132 * GPIO_TRANSITORY - GPIO line is transitory and may loose its 133 electrical state during suspend/resume 134 135In the future, these flags might be extended to support more properties. 136 137Note that: 138 1. GPIO line names are not guaranteed to be globally unique, so the first 139 match found will be used. 140 2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. 141 142A lookup table can then be defined as follows, with an empty entry defining its 143end. The 'dev_id' field of the table is the identifier of the device that will 144make use of these GPIOs. It can be NULL, in which case it will be matched for 145calls to gpiod_get() with a NULL device. 146 147.. code-block:: c 148 149 struct gpiod_lookup_table gpios_table = { 150 .dev_id = "foo.0", 151 .table = { 152 GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH), 153 GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH), 154 GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH), 155 GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW), 156 { }, 157 }, 158 }; 159 160And the table can be added by the board code as follows:: 161 162 gpiod_add_lookup_table(&gpios_table); 163 164The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:: 165 166 struct gpio_desc *red, *green, *blue, *power; 167 168 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH); 169 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH); 170 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH); 171 172 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); 173 174Since the "led" GPIOs are mapped as active-high, this example will switch their 175signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped 176as active-low, its actual signal will be 0 after this code. Contrary to the 177legacy integer GPIO interface, the active-low property is handled during 178mapping and is thus transparent to GPIO consumers. 179 180A set of functions such as gpiod_set_value() is available to work with 181the new descriptor-oriented interface. 182 183Boards using platform data can also hog GPIO lines by defining GPIO hog tables. 184 185.. code-block:: c 186 187 struct gpiod_hog gpio_hog_table[] = { 188 GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH), 189 { } 190 }; 191 192And the table can be added to the board code as follows:: 193 194 gpiod_add_hogs(gpio_hog_table); 195 196The line will be hogged as soon as the gpiochip is created or - in case the 197chip was created earlier - when the hog table is registered. 198 199Arrays of pins 200-------------- 201In addition to requesting pins belonging to a function one by one, a device may 202also request an array of pins assigned to the function. The way those pins are 203mapped to the device determines if the array qualifies for fast bitmap 204processing. If yes, a bitmap is passed over get/set array functions directly 205between a caller and a respective .get/set_multiple() callback of a GPIO chip. 206 207In order to qualify for fast bitmap processing, the array must meet the 208following requirements: 209 210- pin hardware number of array member 0 must also be 0, 211- pin hardware numbers of consecutive array members which belong to the same 212 chip as member 0 does must also match their array indexes. 213 214Otherwise fast bitmap processing path is not used in order to avoid consecutive 215pins which belong to the same chip but are not in hardware order being processed 216separately. 217 218If the array applies for fast bitmap processing path, pins which belong to 219different chips than member 0 does, as well as those with indexes different from 220their hardware pin numbers, are excluded from the fast path, both input and 221output. Moreover, open drain and open source pins are excluded from fast bitmap 222output processing. 223