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 Note that it only applies to the new descriptor-based interface. For a
   8 description of the deprecated integer-based GPIO interface please refer to
   9 gpio-legacy.txt (actually, there is no real mapping possible with the old
  10 interface; you just fetch an integer from somewhere and request the
  11 corresponding GPIO).
  12
  13 All platforms can enable the GPIO library, but if the platform strictly
  14 requires GPIO functionality to be present, it needs to select GPIOLIB from its
  15 Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
  16 describe its hardware layout. Currently, mappings can be defined through device
  17 tree, ACPI, and platform data.
  18
  19 Device Tree
  20 -----------
  21 GPIOs can easily be mapped to devices and functions in the device tree. The
  22 exact way to do it depends on the GPIO controller providing the GPIOs, see the
  23 device tree bindings for your controller.
  24
  25 GPIOs 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
  27 through 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
  39 Properties named <function>-gpio are also considered valid and old bindings use
  40 it but are only supported for compatibility reasons and should not be used for
  41 newer bindings since it has been deprecated.
  42
  43 This 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
  54 The led GPIOs will be active high, while the power GPIO will be active low (i.e.
  55 gpiod_is_active_low(power) will be true).
  56
  57 The second parameter of the gpiod_get() functions, the con_id string, has to be
  58 the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
  59 looked 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
  62 Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
  63 with the string passed in con_id to get the resulting string
  64 (``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).
  65
  66 ACPI
  67 ----
  68 ACPI also supports function names for GPIOs in a similar fashion to DT.
  69 The above DT example can be converted to an equivalent ACPI description
  70 with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
  71
  72         Device (FOO) {
  73                 Name (_CRS, ResourceTemplate () {
  74                         GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  75                                 "\\_SB.GPI0") {15} // red
  76                         GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  77                                 "\\_SB.GPI0") {16} // green
  78                         GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  79                                 "\\_SB.GPI0") {17} // blue
  80                         GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  81                                 "\\_SB.GPI0") {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 () {
  96                                         "power-gpios",
  97                                         Package () {^FOO, 3, 0, 0},
  98                                 },
  99                         }
 100                 })
 101         }
 102
 103 For more information about the ACPI GPIO bindings see
 104 Documentation/acpi/gpio-properties.txt.
 105
 106 Platform Data
 107 -------------
 108 Finally, GPIOs can be bound to devices and functions using platform data. Board
 109 files that desire to do so need to include the following header::
 110
 111         #include <linux/gpio/machine.h>
 112
 113 GPIOs are mapped by the means of tables of lookups, containing instances of the
 114 gpiod_lookup structure. Two macros are defined to help declaring such mappings::
 115
 116         GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
 117         GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)
 118
 119 where
 120
 121   - chip_label is the label of the gpiod_chip instance providing the GPIO
 122   - chip_hwnum is the hardware number of the GPIO within the chip
 123   - con_id is the name of the GPIO function from the device point of view. It
 124         can be NULL, in which case it will match any function.
 125   - idx is the index of the GPIO within the function.
 126   - flags is defined to specify the following properties:
 127         * GPIO_ACTIVE_HIGH      - GPIO line is active high
 128         * GPIO_ACTIVE_LOW       - GPIO line is active low
 129         * GPIO_OPEN_DRAIN       - GPIO line is set up as open drain
 130         * GPIO_OPEN_SOURCE      - GPIO line is set up as open source
 131         * GPIO_PERSISTENT       - GPIO line is persistent during
 132                                   suspend/resume and maintains its value
 133         * GPIO_TRANSITORY       - GPIO line is transitory and may loose its
 134                                   electrical state during suspend/resume
 135
 136 In the future, these flags might be extended to support more properties.
 137
 138 Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
 139
 140 A lookup table can then be defined as follows, with an empty entry defining its
 141 end. The 'dev_id' field of the table is the identifier of the device that will
 142 make use of these GPIOs. It can be NULL, in which case it will be matched for
 143 calls to gpiod_get() with a NULL device.
 144
 145 .. code-block:: c
 146
 147         struct gpiod_lookup_table gpios_table = {
 148                 .dev_id = "foo.0",
 149                 .table = {
 150                         GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
 151                         GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
 152                         GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
 153                         GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
 154                         { },
 155                 },
 156         };
 157
 158 And the table can be added by the board code as follows::
 159
 160         gpiod_add_lookup_table(&gpios_table);
 161
 162 The driver controlling "foo.0" will then be able to obtain its GPIOs as follows::
 163
 164         struct gpio_desc *red, *green, *blue, *power;
 165
 166         red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
 167         green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
 168         blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
 169
 170         power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
 171
 172 Since the "led" GPIOs are mapped as active-high, this example will switch their
 173 signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
 174 as active-low, its actual signal will be 0 after this code. Contrary to the
 175 legacy integer GPIO interface, the active-low property is handled during
 176 mapping and is thus transparent to GPIO consumers.
 177
 178 A set of functions such as gpiod_set_value() is available to work with
 179 the new descriptor-oriented interface.
 180
 181 Boards using platform data can also hog GPIO lines by defining GPIO hog tables.
 182
 183 .. code-block:: c
 184
 185         struct gpiod_hog gpio_hog_table[] = {
 186                 GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH),
 187                 { }
 188         };
 189
 190 And the table can be added to the board code as follows::
 191
 192         gpiod_add_hogs(gpio_hog_table);
 193
 194 The line will be hogged as soon as the gpiochip is created or - in case the
 195 chip was created earlier - when the hog table is registered.