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