Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 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 | Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage |
| 12 | is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in |
| 13 | their 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 |
Javier Martinez Canillas | ae80d64 | 2015-09-01 10:46:15 +0200 | [diff] [blame] | 24 | either <function>-gpios or <function>-gpio, where <function> is the function |
| 25 | the driver will request through gpiod_get(). For example: |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 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 | |
Javier Martinez Canillas | ae80d64 | 2015-09-01 10:46:15 +0200 | [diff] [blame] | 34 | power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>; |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 35 | }; |
| 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 | |
Dirk Behme | 69de52b | 2015-09-02 20:07:09 +0200 | [diff] [blame] | 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); |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 45 | |
Dirk Behme | 69de52b | 2015-09-02 20:07:09 +0200 | [diff] [blame] | 46 | power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 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 | |
Dirk Behme | 87e77e4 | 2015-09-02 20:07:10 +0200 | [diff] [blame] | 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 | |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 60 | ACPI |
| 61 | ---- |
Mika Westerberg | cfc5076 | 2015-04-01 11:13:16 +0300 | [diff] [blame] | 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, ..., IoRestrictionOutputOnly, |
| 69 | "\\_SB.GPI0") {15} // red |
| 70 | GpioIo (Exclusive, ..., IoRestrictionOutputOnly, |
| 71 | "\\_SB.GPI0") {16} // green |
| 72 | GpioIo (Exclusive, ..., IoRestrictionOutputOnly, |
| 73 | "\\_SB.GPI0") {17} // blue |
| 74 | GpioIo (Exclusive, ..., IoRestrictionOutputOnly, |
| 75 | "\\_SB.GPI0") {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 () { |
| 90 | "power-gpios", |
| 91 | Package () {^FOO, 3, 0, 0}, |
| 92 | }, |
| 93 | } |
| 94 | }) |
| 95 | } |
| 96 | |
| 97 | For more information about the ACPI GPIO bindings see |
| 98 | Documentation/acpi/gpio-properties.txt. |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 99 | |
| 100 | Platform Data |
| 101 | ------------- |
| 102 | Finally, GPIOs can be bound to devices and functions using platform data. Board |
| 103 | files that desire to do so need to include the following header: |
| 104 | |
Linus Walleij | 0a6d315 | 2014-07-24 20:08:55 +0200 | [diff] [blame] | 105 | #include <linux/gpio/machine.h> |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 106 | |
| 107 | GPIOs are mapped by the means of tables of lookups, containing instances of the |
| 108 | gpiod_lookup structure. Two macros are defined to help declaring such mappings: |
| 109 | |
| 110 | GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags) |
| 111 | GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags) |
| 112 | |
| 113 | where |
| 114 | |
| 115 | - chip_label is the label of the gpiod_chip instance providing the GPIO |
| 116 | - chip_hwnum is the hardware number of the GPIO within the chip |
Alexandre Courbot | ad82478 | 2013-12-03 12:20:11 +0900 | [diff] [blame] | 117 | - dev_id is the identifier of the device that will make use of this GPIO. It |
| 118 | can be NULL, in which case it will be matched for calls to gpiod_get() |
| 119 | with a NULL device. |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 120 | - con_id is the name of the GPIO function from the device point of view. It |
Alexandre Courbot | ad82478 | 2013-12-03 12:20:11 +0900 | [diff] [blame] | 121 | can be NULL, in which case it will match any function. |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 122 | - idx is the index of the GPIO within the function. |
| 123 | - flags is defined to specify the following properties: |
| 124 | * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low |
| 125 | * GPIOF_OPEN_DRAIN - GPIO pin is open drain type. |
| 126 | * GPIOF_OPEN_SOURCE - GPIO pin is open source type. |
| 127 | |
| 128 | In the future, these flags might be extended to support more properties. |
| 129 | |
| 130 | Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. |
| 131 | |
Alexandre Courbot | ad82478 | 2013-12-03 12:20:11 +0900 | [diff] [blame] | 132 | A lookup table can then be defined as follows, with an empty entry defining its |
| 133 | end: |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 134 | |
Alexandre Courbot | ad82478 | 2013-12-03 12:20:11 +0900 | [diff] [blame] | 135 | struct gpiod_lookup_table gpios_table = { |
| 136 | .dev_id = "foo.0", |
| 137 | .table = { |
| 138 | GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH), |
| 139 | GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH), |
| 140 | GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH), |
| 141 | GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW), |
| 142 | { }, |
| 143 | }, |
| 144 | }; |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 145 | |
| 146 | And the table can be added by the board code as follows: |
| 147 | |
Alexandre Courbot | ad82478 | 2013-12-03 12:20:11 +0900 | [diff] [blame] | 148 | gpiod_add_lookup_table(&gpios_table); |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 149 | |
| 150 | The driver controlling "foo.0" will then be able to obtain its GPIOs as follows: |
| 151 | |
| 152 | struct gpio_desc *red, *green, *blue, *power; |
| 153 | |
Dirk Behme | 69de52b | 2015-09-02 20:07:09 +0200 | [diff] [blame] | 154 | red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH); |
| 155 | green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH); |
| 156 | blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH); |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 157 | |
Dirk Behme | 69de52b | 2015-09-02 20:07:09 +0200 | [diff] [blame] | 158 | power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); |
Alexandre Courbot | fd8e198 | 2013-11-16 21:34:21 +0900 | [diff] [blame] | 159 | |
Dirk Behme | 69de52b | 2015-09-02 20:07:09 +0200 | [diff] [blame] | 160 | Since the "led" GPIOs are mapped as active-high, this example will switch their |
| 161 | signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped |
| 162 | as active-low, its actual signal will be 0 after this code. Contrary to the legacy |
| 163 | integer GPIO interface, the active-low property is handled during mapping and is |
| 164 | thus transparent to GPIO consumers. |