1 ============= 1 =============
2 GPIO Mappings 2 GPIO Mappings
3 ============= 3 =============
4 4
5 This document explains how GPIOs can be assign 5 This document explains how GPIOs can be assigned to given devices and functions.
6 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 legacy.rst (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
7 All platforms can enable the GPIO library, but 13 All platforms can enable the GPIO library, but if the platform strictly
8 requires GPIO functionality to be present, it 14 requires GPIO functionality to be present, it needs to select GPIOLIB from its
9 Kconfig. Then, how GPIOs are mapped depends on 15 Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
10 describe its hardware layout. Currently, mappi 16 describe its hardware layout. Currently, mappings can be defined through device
11 tree, ACPI, and platform data. 17 tree, ACPI, and platform data.
12 18
13 Device Tree 19 Device Tree
14 ----------- 20 -----------
15 GPIOs can easily be mapped to devices and func 21 GPIOs can easily be mapped to devices and functions in the device tree. The
16 exact way to do it depends on the GPIO control 22 exact way to do it depends on the GPIO controller providing the GPIOs, see the
17 device tree bindings for your controller. 23 device tree bindings for your controller.
18 24
19 GPIOs mappings are defined in the consumer dev 25 GPIOs mappings are defined in the consumer device's node, in a property named
20 <function>-gpios, where <function> is the func 26 <function>-gpios, where <function> is the function the driver will request
21 through gpiod_get(). For example:: 27 through gpiod_get(). For example::
22 28
23 foo_device { 29 foo_device {
24 compatible = "acme,foo"; 30 compatible = "acme,foo";
25 ... 31 ...
26 led-gpios = <&gpio 15 GPIO_ACT 32 led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
27 <&gpio 16 GPIO_ACT 33 <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
28 <&gpio 17 GPIO_ACT 34 <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
29 35
30 power-gpios = <&gpio 1 GPIO_AC 36 power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
31 }; 37 };
32 38
33 Properties named <function>-gpio are also cons 39 Properties named <function>-gpio are also considered valid and old bindings use
34 it but are only supported for compatibility re 40 it but are only supported for compatibility reasons and should not be used for
35 newer bindings since it has been deprecated. 41 newer bindings since it has been deprecated.
36 42
37 This property will make GPIOs 15, 16 and 17 av 43 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 44 "led" function, and GPIO 1 as the "power" GPIO::
39 45
40 struct gpio_desc *red, *green, *blue, 46 struct gpio_desc *red, *green, *blue, *power;
41 47
42 red = gpiod_get_index(dev, "led", 0, G 48 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
43 green = gpiod_get_index(dev, "led", 1, 49 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
44 blue = gpiod_get_index(dev, "led", 2, 50 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
45 51
46 power = gpiod_get(dev, "power", GPIOD_ 52 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
47 53
48 The led GPIOs will be active high, while the p 54 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). 55 gpiod_is_active_low(power) will be true).
50 56
51 The second parameter of the gpiod_get() functi 57 The second parameter of the gpiod_get() functions, the con_id string, has to be
52 the <function>-prefix of the GPIO suffixes ("g 58 the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
53 looked up by the gpiod functions internally) u 59 looked up by the gpiod functions internally) used in the device tree. With above
54 "led-gpios" example, use the prefix without th 60 "led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
55 61
56 Internally, the GPIO subsystem prefixes the GP 62 Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
57 with the string passed in con_id to get the re 63 with the string passed in con_id to get the resulting string
58 (``snprintf(... "%s-%s", con_id, gpio_suffixes 64 (``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).
59 65
60 ACPI 66 ACPI
61 ---- 67 ----
62 ACPI also supports function names for GPIOs in 68 ACPI also supports function names for GPIOs in a similar fashion to DT.
63 The above DT example can be converted to an eq 69 The above DT example can be converted to an equivalent ACPI description
64 with the help of _DSD (Device Specific Data), 70 with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
65 71
66 Device (FOO) { 72 Device (FOO) {
67 Name (_CRS, ResourceTemplate ( 73 Name (_CRS, ResourceTemplate () {
68 GpioIo (Exclusive, Pul 74 GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,
69 "\\_SB.GPI0", 75 "\\_SB.GPI0", 0, ResourceConsumer) { 15 } // red
70 GpioIo (Exclusive, Pul 76 GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,
71 "\\_SB.GPI0", 77 "\\_SB.GPI0", 0, ResourceConsumer) { 16 } // green
72 GpioIo (Exclusive, Pul 78 GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,
73 "\\_SB.GPI0", 79 "\\_SB.GPI0", 0, ResourceConsumer) { 17 } // blue
74 GpioIo (Exclusive, Pul 80 GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly,
75 "\\_SB.GPI0", 81 "\\_SB.GPI0", 0, ResourceConsumer) { 1 } // power
76 }) 82 })
77 83
78 Name (_DSD, Package () { 84 Name (_DSD, Package () {
79 ToUUID("daffd814-6eba- 85 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
80 Package () { 86 Package () {
81 Package () { 87 Package () {
82 "led-g 88 "led-gpios",
83 Packag 89 Package () {
84 90 ^FOO, 0, 0, 1,
85 91 ^FOO, 1, 0, 1,
86 92 ^FOO, 2, 0, 1,
87 } 93 }
88 }, 94 },
89 Package () { " 95 Package () { "power-gpios", Package () { ^FOO, 3, 0, 0 } },
90 } 96 }
91 }) 97 })
92 } 98 }
93 99
94 For more information about the ACPI GPIO bindi 100 For more information about the ACPI GPIO bindings see
95 Documentation/firmware-guide/acpi/gpio-propert 101 Documentation/firmware-guide/acpi/gpio-properties.rst.
96 102
97 Platform Data 103 Platform Data
98 ------------- 104 -------------
99 Finally, GPIOs can be bound to devices and fun 105 Finally, GPIOs can be bound to devices and functions using platform data. Board
100 files that desire to do so need to include the 106 files that desire to do so need to include the following header::
101 107
102 #include <linux/gpio/machine.h> 108 #include <linux/gpio/machine.h>
103 109
104 GPIOs are mapped by the means of tables of loo 110 GPIOs are mapped by the means of tables of lookups, containing instances of the
105 gpiod_lookup structure. Two macros are defined 111 gpiod_lookup structure. Two macros are defined to help declaring such mappings::
106 112
107 GPIO_LOOKUP(key, chip_hwnum, con_id, f 113 GPIO_LOOKUP(key, chip_hwnum, con_id, flags)
108 GPIO_LOOKUP_IDX(key, chip_hwnum, con_i 114 GPIO_LOOKUP_IDX(key, chip_hwnum, con_id, idx, flags)
109 115
110 where 116 where
111 117
112 - key is either the label of the gpiod_chip 118 - key is either the label of the gpiod_chip instance providing the GPIO, or
113 the GPIO line name 119 the GPIO line name
114 - chip_hwnum is the hardware number of the G 120 - 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 121 to indicate that key is a GPIO line name
116 - con_id is the name of the GPIO function fr 122 - 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 mat 123 can be NULL, in which case it will match any function.
118 - idx is the index of the GPIO within the fu 124 - idx is the index of the GPIO within the function.
119 - flags is defined to specify the following 125 - flags is defined to specify the following properties:
120 * GPIO_ACTIVE_HIGH - GPIO line is 126 * GPIO_ACTIVE_HIGH - GPIO line is active high
121 * GPIO_ACTIVE_LOW - GPIO line is 127 * GPIO_ACTIVE_LOW - GPIO line is active low
122 * GPIO_OPEN_DRAIN - GPIO line is 128 * GPIO_OPEN_DRAIN - GPIO line is set up as open drain
123 * GPIO_OPEN_SOURCE - GPIO line is 129 * GPIO_OPEN_SOURCE - GPIO line is set up as open source
124 * GPIO_PERSISTENT - GPIO line is 130 * GPIO_PERSISTENT - GPIO line is persistent during
125 suspend/resu 131 suspend/resume and maintains its value
126 * GPIO_TRANSITORY - GPIO line is 132 * GPIO_TRANSITORY - GPIO line is transitory and may loose its
127 electrical s 133 electrical state during suspend/resume
128 134
129 In the future, these flags might be extended t 135 In the future, these flags might be extended to support more properties.
130 136
131 Note that: 137 Note that:
132 1. GPIO line names are not guaranteed to be 138 1. GPIO line names are not guaranteed to be globally unique, so the first
133 match found will be used. 139 match found will be used.
134 2. GPIO_LOOKUP() is just a shortcut to GPIO_ 140 2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
135 141
136 A lookup table can then be defined as follows, 142 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 id 143 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 wh 144 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. 145 calls to gpiod_get() with a NULL device.
140 146
141 .. code-block:: c 147 .. code-block:: c
142 148
143 struct gpiod_lookup_table gpios_table 149 struct gpiod_lookup_table gpios_table = {
144 .dev_id = "foo.0", 150 .dev_id = "foo.0",
145 .table = { 151 .table = {
146 GPIO_LOOKUP_IDX("gpio. 152 GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
147 GPIO_LOOKUP_IDX("gpio. 153 GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
148 GPIO_LOOKUP_IDX("gpio. 154 GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
149 GPIO_LOOKUP("gpio.0", 155 GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
150 { }, 156 { },
151 }, 157 },
152 }; 158 };
153 159
154 And the table can be added by the board code a 160 And the table can be added by the board code as follows::
155 161
156 gpiod_add_lookup_table(&gpios_table); 162 gpiod_add_lookup_table(&gpios_table);
157 163
158 The driver controlling "foo.0" will then be ab 164 The driver controlling "foo.0" will then be able to obtain its GPIOs as follows::
159 165
160 struct gpio_desc *red, *green, *blue, 166 struct gpio_desc *red, *green, *blue, *power;
161 167
162 red = gpiod_get_index(dev, "led", 0, G 168 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
163 green = gpiod_get_index(dev, "led", 1, 169 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
164 blue = gpiod_get_index(dev, "led", 2, 170 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
165 171
166 power = gpiod_get(dev, "power", GPIOD_ 172 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
167 173
168 Since the "led" GPIOs are mapped as active-hig 174 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 175 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 aft 176 as active-low, its actual signal will be 0 after this code. Contrary to the
171 legacy integer GPIO interface, the active-low 177 legacy integer GPIO interface, the active-low property is handled during
172 mapping and is thus transparent to GPIO consum 178 mapping and is thus transparent to GPIO consumers.
173 179
174 A set of functions such as gpiod_set_value() i 180 A set of functions such as gpiod_set_value() is available to work with
175 the new descriptor-oriented interface. 181 the new descriptor-oriented interface.
176 182
177 Boards using platform data can also hog GPIO l 183 Boards using platform data can also hog GPIO lines by defining GPIO hog tables.
178 184
179 .. code-block:: c 185 .. code-block:: c
180 186
181 struct gpiod_hog gpio_hog_table[] = { 187 struct gpiod_hog gpio_hog_table[] = {
182 GPIO_HOG("gpio.0", 10, "foo", 188 GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH),
183 { } 189 { }
184 }; 190 };
185 191
186 And the table can be added to the board code a 192 And the table can be added to the board code as follows::
187 193
188 gpiod_add_hogs(gpio_hog_table); 194 gpiod_add_hogs(gpio_hog_table);
189 195
190 The line will be hogged as soon as the gpiochi 196 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 197 chip was created earlier - when the hog table is registered.
192 198
193 Arrays of pins 199 Arrays of pins
194 -------------- 200 --------------
195 In addition to requesting pins belonging to a 201 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 202 also request an array of pins assigned to the function. The way those pins are
197 mapped to the device determines if the array q 203 mapped to the device determines if the array qualifies for fast bitmap
198 processing. If yes, a bitmap is passed over g 204 processing. If yes, a bitmap is passed over get/set array functions directly
199 between a caller and a respective .get/set_mul 205 between a caller and a respective .get/set_multiple() callback of a GPIO chip.
200 206
201 In order to qualify for fast bitmap processing 207 In order to qualify for fast bitmap processing, the array must meet the
202 following requirements: 208 following requirements:
203 209
204 - pin hardware number of array member 0 must a 210 - pin hardware number of array member 0 must also be 0,
205 - pin hardware numbers of consecutive array me 211 - pin hardware numbers of consecutive array members which belong to the same
206 chip as member 0 does must also match their 212 chip as member 0 does must also match their array indexes.
207 213
208 Otherwise fast bitmap processing path is not u 214 Otherwise fast bitmap processing path is not used in order to avoid consecutive
209 pins which belong to the same chip but are not 215 pins which belong to the same chip but are not in hardware order being processed
210 separately. 216 separately.
211 217
212 If the array applies for fast bitmap processin 218 If the array applies for fast bitmap processing path, pins which belong to
213 different chips than member 0 does, as well as 219 different chips than member 0 does, as well as those with indexes different from
214 their hardware pin numbers, are excluded from 220 their hardware pin numbers, are excluded from the fast path, both input and
215 output. Moreover, open drain and open source 221 output. Moreover, open drain and open source pins are excluded from fast bitmap
216 output processing. 222 output processing.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.