217 lines · plain
1=============2GPIO Mappings3=============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 strictly8requires GPIO functionality to be present, it needs to select GPIOLIB from its9Kconfig. Then, how GPIOs are mapped depends on what the platform uses to10describe its hardware layout. Currently, mappings can be defined through device11tree, ACPI, and platform data.12 13Device Tree14-----------15GPIOs can easily be mapped to devices and functions in the device tree. The16exact way to do it depends on the GPIO controller providing the GPIOs, see the17device tree bindings for your controller.18 19GPIOs mappings are defined in the consumer device's node, in a property named20<function>-gpios, where <function> is the function the driver will request21through 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 use34it but are only supported for compatibility reasons and should not be used for35newer bindings since it has been deprecated.36 37This property will make GPIOs 15, 16 and 17 available to the driver under the38"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 be52the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically53looked up by the gpiod functions internally) used in the device tree. With above54"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 string58(``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).59 60ACPI61----62ACPI also supports function names for GPIOs in a similar fashion to DT.63The above DT example can be converted to an equivalent ACPI description64with 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 } // red70 GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,71 "\\_SB.GPI0", 0, ResourceConsumer) { 16 } // green72 GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,73 "\\_SB.GPI0", 0, ResourceConsumer) { 17 } // blue74 GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly,75 "\\_SB.GPI0", 0, ResourceConsumer) { 1 } // power76 })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 see95Documentation/firmware-guide/acpi/gpio-properties.rst.96 97Platform Data98-------------99Finally, GPIOs can be bound to devices and functions using platform data. Board100files that desire to do so need to include the following header::101 102 #include <linux/gpio/machine.h>103 104GPIOs are mapped by the means of tables of lookups, containing instances of the105gpiod_lookup structure. Two macros are defined to help declaring such mappings::106 107 GPIO_LOOKUP(key, chip_hwnum, con_id, flags)108 GPIO_LOOKUP_IDX(key, chip_hwnum, con_id, idx, flags)109 110where111 112 - key is either the label of the gpiod_chip instance providing the GPIO, or113 the GPIO line name114 - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX115 to indicate that key is a GPIO line name116 - con_id is the name of the GPIO function from the device point of view. It117 can be NULL, in which case it will match any function.118 - idx is the index of the GPIO within the function.119 - flags is defined to specify the following properties:120 * GPIO_ACTIVE_HIGH - GPIO line is active high121 * GPIO_ACTIVE_LOW - GPIO line is active low122 * GPIO_OPEN_DRAIN - GPIO line is set up as open drain123 * GPIO_OPEN_SOURCE - GPIO line is set up as open source124 * GPIO_PERSISTENT - GPIO line is persistent during125 suspend/resume and maintains its value126 * GPIO_TRANSITORY - GPIO line is transitory and may loose its127 electrical state during suspend/resume128 129In the future, these flags might be extended to support more properties.130 131Note that:132 1. GPIO line names are not guaranteed to be globally unique, so the first133 match found will be used.134 2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.135 136A lookup table can then be defined as follows, with an empty entry defining its137end. The 'dev_id' field of the table is the identifier of the device that will138make use of these GPIOs. It can be NULL, in which case it will be matched for139calls to gpiod_get() with a NULL device.140 141.. code-block:: c142 143 struct gpiod_lookup_table gpios_table = {144 .dev_id = "foo.0",145 .table = {146 GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),147 GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),148 GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),149 GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),150 { },151 },152 };153 154And the table can be added by the board code as follows::155 156 gpiod_add_lookup_table(&gpios_table);157 158The driver controlling "foo.0" will then be able to obtain its GPIOs as follows::159 160 struct gpio_desc *red, *green, *blue, *power;161 162 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);163 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);164 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);165 166 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);167 168Since the "led" GPIOs are mapped as active-high, this example will switch their169signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped170as active-low, its actual signal will be 0 after this code. Contrary to the171legacy integer GPIO interface, the active-low property is handled during172mapping and is thus transparent to GPIO consumers.173 174A set of functions such as gpiod_set_value() is available to work with175the new descriptor-oriented interface.176 177Boards using platform data can also hog GPIO lines by defining GPIO hog tables.178 179.. code-block:: c180 181 struct gpiod_hog gpio_hog_table[] = {182 GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH),183 { }184 };185 186And the table can be added to the board code as follows::187 188 gpiod_add_hogs(gpio_hog_table);189 190The line will be hogged as soon as the gpiochip is created or - in case the191chip was created earlier - when the hog table is registered.192 193Arrays of pins194--------------195In addition to requesting pins belonging to a function one by one, a device may196also request an array of pins assigned to the function. The way those pins are197mapped to the device determines if the array qualifies for fast bitmap198processing. If yes, a bitmap is passed over get/set array functions directly199between a caller and a respective .get/set_multiple() callback of a GPIO chip.200 201In order to qualify for fast bitmap processing, the array must meet the202following requirements:203 204- pin hardware number of array member 0 must also be 0,205- pin hardware numbers of consecutive array members which belong to the same206 chip as member 0 does must also match their array indexes.207 208Otherwise fast bitmap processing path is not used in order to avoid consecutive209pins which belong to the same chip but are not in hardware order being processed210separately.211 212If the array applies for fast bitmap processing path, pins which belong to213different chips than member 0 does, as well as those with indexes different from214their hardware pin numbers, are excluded from the fast path, both input and215output. Moreover, open drain and open source pins are excluded from fast bitmap216output processing.217