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