Documentation/driver-api/gpio/board.rst

   1 =============
   2 GPIO Mappings
   3 =============
   4
   5 This document explains how GPIOs can be assigned to given devices and functions.
   6
   7 All platforms can enable the GPIO library, but if the platform strictly
   8 requires GPIO functionality to be present, it needs to select GPIOLIB from its
   9 Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
  10 describe its hardware layout. Currently, mappings can be defined through device
  11 tree, ACPI, and platform data.
  12
  13 Device Tree
  14 -----------
  15 GPIOs can easily be mapped to devices and functions in the device tree. The
  16 exact way to do it depends on the GPIO controller providing the GPIOs, see the
  17 device tree bindings for your controller.
  18
  19 GPIOs 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
  21 through 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
  33 Properties named <function>-gpio are also considered valid and old bindings use
  34 it but are only supported for compatibility reasons and should not be used for
  35 newer bindings since it has been deprecated.
  36
  37 This 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
  48 The led GPIOs will be active high, while the power GPIO will be active low (i.e.
  49 gpiod_is_active_low(power) will be true).
  50
  51 The second parameter of the gpiod_get() functions, the con_id string, has to be
  52 the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
  53 looked 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
  56 Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
  57 with the string passed in con_id to get the resulting string
  58 (``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).
  59
  60 ACPI
  61 ----
  62 ACPI also supports function names for GPIOs in a similar fashion to DT.
  63 The above DT example can be converted to an equivalent ACPI description
  64 with 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
  94 For more information about the ACPI GPIO bindings see
  95 Documentation/firmware-guide/acpi/gpio-properties.rst.
  96
  97 Platform Data
  98 -------------
  99 Finally, GPIOs can be bound to devices and functions using platform data. Board
 100 files that desire to do so need to include the following header::
 101
 102         #include <linux/gpio/machine.h>
 103
 104 GPIOs are mapped by the means of tables of lookups, containing instances of the
 105 gpiod_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
 110 where
 111
 112   - key is either the label of the gpiod_chip instance providing the GPIO, or
 113     the GPIO line name
 114   - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX
 115     to indicate that key is a GPIO line name
 116   - con_id is the name of the GPIO function from the device point of view. It
 117         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 high
 121         * GPIO_ACTIVE_LOW       - GPIO line is active low
 122         * GPIO_OPEN_DRAIN       - GPIO line is set up as open drain
 123         * GPIO_OPEN_SOURCE      - GPIO line is set up as open source
 124         * GPIO_PERSISTENT       - GPIO line is persistent during
 125                                   suspend/resume and maintains its value
 126         * GPIO_TRANSITORY       - GPIO line is transitory and may loose its
 127                                   electrical state during suspend/resume
 128
 129 In the future, these flags might be extended to support more properties.
 130
 131 Note that:
 132   1. GPIO line names are not guaranteed to be globally unique, so the first
 133      match found will be used.
 134   2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
 135
 136 A lookup table can then be defined as follows, with an empty entry defining its
 137 end. The 'dev_id' field of the table is the identifier of the device that will
 138 make use of these GPIOs. It can be NULL, in which case it will be matched for
 139 calls to gpiod_get() with a NULL device.
 140
 141 .. code-block:: c
 142
 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
 154 And the table can be added by the board code as follows::
 155
 156         gpiod_add_lookup_table(&gpios_table);
 157
 158 The 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
 168 Since the "led" GPIOs are mapped as active-high, this example will switch their
 169 signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
 170 as active-low, its actual signal will be 0 after this code. Contrary to the
 171 legacy integer GPIO interface, the active-low property is handled during
 172 mapping and is thus transparent to GPIO consumers.
 173
 174 A set of functions such as gpiod_set_value() is available to work with
 175 the new descriptor-oriented interface.
 176
 177 Boards using platform data can also hog GPIO lines by defining GPIO hog tables.
 178
 179 .. code-block:: c
 180
 181         struct gpiod_hog gpio_hog_table[] = {
 182                 GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH),
 183                 { }
 184         };
 185
 186 And the table can be added to the board code as follows::
 187
 188         gpiod_add_hogs(gpio_hog_table);
 189
 190 The line will be hogged as soon as the gpiochip is created or - in case the
 191 chip was created earlier - when the hog table is registered.
 192
 193 Arrays of pins
 194 --------------
 195 In addition to requesting pins belonging to a function one by one, a device may
 196 also request an array of pins assigned to the function.  The way those pins are
 197 mapped to the device determines if the array qualifies for fast bitmap
 198 processing.  If yes, a bitmap is passed over get/set array functions directly
 199 between a caller and a respective .get/set_multiple() callback of a GPIO chip.
 200
 201 In order to qualify for fast bitmap processing, the array must meet the
 202 following 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 same
 206   chip as member 0 does must also match their array indexes.
 207
 208 Otherwise fast bitmap processing path is not used in order to avoid consecutive
 209 pins which belong to the same chip but are not in hardware order being processed
 210 separately.
 211
 212 If the array applies for fast bitmap processing path, pins which belong to
 213 different chips than member 0 does, as well as those with indexes different from
 214 their hardware pin numbers, are excluded from the fast path, both input and
 215 output.  Moreover, open drain and open source pins are excluded from fast bitmap
 216 output processing.