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