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