Documentation/gpio/board.txt

   1 GPIO Mappings
   2 =============
   3
   4 This document explains how GPIOs can be assigned to given devices and functions.
   5 Note that it only applies to the new descriptor-based interface. For a
   6 description of the deprecated integer-based GPIO interface please refer to
   7 gpio-legacy.txt (actually, there is no real mapping possible with the old
   8 interface; you just fetch an integer from somewhere and request the
   9 corresponding GPIO).
  10
  11 All platforms can enable the GPIO library, but if the platform strictly
  12 requires GPIO functionality to be present, it needs to select GPIOLIB from its
  13 Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
  14 describe its hardware layout. Currently, mappings can be defined through device
  15 tree, ACPI, and platform data.
  16
  17 Device Tree
  18 -----------
  19 GPIOs can easily be mapped to devices and functions in the device tree. The
  20 exact way to do it depends on the GPIO controller providing the GPIOs, see the
  21 device tree bindings for your controller.
  22
  23 GPIOs mappings are defined in the consumer device's node, in a property named
  24 <function>-gpios, where <function> is the function the driver will request
  25 through gpiod_get(). For example:
  26
  27         foo_device {
  28                 compatible = "acme,foo";
  29                 ...
  30                 led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
  31                             <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
  32                             <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
  33
  34                 power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
  35         };
  36
  37 Properties named <function>-gpio are also considered valid and old bindings use
  38 it but are only supported for compatibility reasons and should not be used for
  39 newer bindings since it has been deprecated.
  40
  41 This property will make GPIOs 15, 16 and 17 available to the driver under the
  42 "led" function, and GPIO 1 as the "power" GPIO:
  43
  44         struct gpio_desc *red, *green, *blue, *power;
  45
  46         red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
  47         green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
  48         blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
  49
  50         power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
  51
  52 The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
  53 gpiod_is_active_low(power) will be true).
  54
  55 The second parameter of the gpiod_get() functions, the con_id string, has to be
  56 the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
  57 looked up by the gpiod functions internally) used in the device tree. With above
  58 "led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
  59
  60 Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
  61 with the string passed in con_id to get the resulting string
  62 (snprintf(... "%s-%s", con_id, gpio_suffixes[]).
  63
  64 ACPI
  65 ----
  66 ACPI also supports function names for GPIOs in a similar fashion to DT.
  67 The above DT example can be converted to an equivalent ACPI description
  68 with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
  69
  70         Device (FOO) {
  71                 Name (_CRS, ResourceTemplate () {
  72                         GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  73                                 "\\_SB.GPI0") {15} // red
  74                         GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  75                                 "\\_SB.GPI0") {16} // green
  76                         GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  77                                 "\\_SB.GPI0") {17} // blue
  78                         GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  79                                 "\\_SB.GPI0") {1} // power
  80                 })
  81
  82                 Name (_DSD, Package () {
  83                         ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
  84                         Package () {
  85                                 Package () {
  86                                         "led-gpios",
  87                                         Package () {
  88                                                 ^FOO, 0, 0, 1,
  89                                                 ^FOO, 1, 0, 1,
  90                                                 ^FOO, 2, 0, 1,
  91                                         }
  92                                 },
  93                                 Package () {
  94                                         "power-gpios",
  95                                         Package () {^FOO, 3, 0, 0},
  96                                 },
  97                         }
  98                 })
  99         }
 100
 101 For more information about the ACPI GPIO bindings see
 102 Documentation/acpi/gpio-properties.txt.
 103
 104 Platform Data
 105 -------------
 106 Finally, GPIOs can be bound to devices and functions using platform data. Board
 107 files that desire to do so need to include the following header:
 108
 109         #include <linux/gpio/machine.h>
 110
 111 GPIOs are mapped by the means of tables of lookups, containing instances of the
 112 gpiod_lookup structure. Two macros are defined to help declaring such mappings:
 113
 114         GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
 115         GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)
 116
 117 where
 118
 119   - chip_label is the label of the gpiod_chip instance providing the GPIO
 120   - chip_hwnum is the hardware number of the GPIO within the chip
 121   - con_id is the name of the GPIO function from the device point of view. It
 122         can be NULL, in which case it will match any function.
 123   - idx is the index of the GPIO within the function.
 124   - flags is defined to specify the following properties:
 125         * GPIOF_ACTIVE_LOW      - to configure the GPIO as active-low
 126         * GPIOF_OPEN_DRAIN      - GPIO pin is open drain type.
 127         * GPIOF_OPEN_SOURCE     - GPIO pin is open source type.
 128
 129 In the future, these flags might be extended to support more properties.
 130
 131 Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
 132
 133 A lookup table can then be defined as follows, with an empty entry defining its
 134 end. The 'dev_id' field of the table is the identifier of the device that will
 135 make use of these GPIOs. It can be NULL, in which case it will be matched for
 136 calls to gpiod_get() with a NULL device.
 137
 138 struct gpiod_lookup_table gpios_table = {
 139         .dev_id = "foo.0",
 140         .table = {
 141                 GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
 142                 GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
 143                 GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
 144                 GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
 145                 { },
 146         },
 147 };
 148
 149 And the table can be added by the board code as follows:
 150
 151         gpiod_add_lookup_table(&gpios_table);
 152
 153 The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
 154
 155         struct gpio_desc *red, *green, *blue, *power;
 156
 157         red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
 158         green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
 159         blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
 160
 161         power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
 162
 163 Since the "led" GPIOs are mapped as active-high, this example will switch their
 164 signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
 165 as active-low, its actual signal will be 0 after this code. Contrary to the
 166 legacy integer GPIO interface, the active-low property is handled during
 167 mapping and is thus transparent to GPIO consumers.
 168
 169 A set of functions such as gpiod_set_value() is available to work with
 170 the new descriptor-oriented interface.