1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================================
4 _DSD Device Properties Related to GPIO
5 ======================================
6
7 With the release of ACPI 5.1, the _DSD configu
8 allows names to be given to GPIOs (and other t
9 by _CRS. Previously, we were only able to use
10 the corresponding GPIO, which is pretty error
11 the _CRS output ordering, for example).
12
13 With _DSD we can now query GPIOs using a name
14 index, like the ASL example below shows::
15
16 // Bluetooth device with reset and shutdown
17 Device (BTH)
18 {
19 Name (_HID, ...)
20
21 Name (_CRS, ResourceTemplate ()
22 {
23 GpioIo (Exclusive, PullUp, 0, 0, IoR
24 "\\_SB.GPO0", 0, ResourceCon
25 GpioIo (Exclusive, PullUp, 0, 0, IoR
26 "\\_SB.GPO0", 0, ResourceCon
27 })
28
29 Name (_DSD, Package ()
30 {
31 ToUUID("daffd814-6eba-4d8c-8a91-bc9b
32 Package ()
33 {
34 Package () { "reset-gpios", Pack
35 Package () { "shutdown-gpios", P
36 }
37 })
38 }
39
40 The format of the supported GPIO property is::
41
42 Package () { "name", Package () { ref, index
43
44 ref
45 The device that has _CRS containing GpioIo()
46 typically this is the device itself (BTH in
47 index
48 Index of the GpioIo()/GpioInt() resource in
49 pin
50 Pin in the GpioIo()/GpioInt() resource. Typi
51 active_low
52 If 1, the GPIO is marked as active_low.
53
54 Since ACPI GpioIo() resource does not have a f
55 active low or high, the "active_low" argument
56 it to 1 marks the GPIO as active low.
57
58 Note, active_low in _DSD does not make sense f
59 must be 0. GpioInt() resource has its own mean
60
61 In our Bluetooth example the "reset-gpios" ref
62 resource, second pin in that resource with the
63
64 The GpioIo() resource unfortunately doesn't ex
65 state of the output pin which driver should us
66
67 Linux tries to use common sense here and deriv
68 and polarity settings. The table below shows t
69
70 +-------------+-------------+-----------------
71 | Pull Bias | Polarity | Requested...
72 +=============+=============+=================
73 | Implicit
74 +-------------+-------------+-----------------
75 | **Default** | x | AS IS (assumed f
76 +-------------+-------------+-----------------
77 | Explicit
78 +-------------+-------------+-----------------
79 | **None** | x | AS IS (assumed f
80 | | | with no Pull Bia
81 +-------------+-------------+-----------------
82 | **Up** | x (no _DSD) |
83 | +-------------+ as high, assumin
84 | | Low |
85 | +-------------+-----------------
86 | | High | as high, assumin
87 +-------------+-------------+-----------------
88 | **Down** | x (no _DSD) |
89 | +-------------+ as low, assuming
90 | | High |
91 | +-------------+-----------------
92 | | Low | as low, assuming
93 +-------------+-------------+-----------------
94
95 That said, for our above example the both GPIO
96 is explicit and _DSD is present, will be treat
97 polarity and Linux will configure the pins in
98 reprograms them differently.
99
100 It is possible to leave holes in the array of
101 cases like with SPI host controllers where som
102 implemented as GPIOs and some as native signal
103 controller can have chip selects 0 and 2 imple
104 native::
105
106 Package () {
107 "cs-gpios",
108 Package () {
109 ^GPIO, 19, 0, 0, // chip select 0: G
110 0, // chip select 1: n
111 ^GPIO, 20, 0, 0, // chip select 2: G
112 }
113 }
114
115 Note, that historically ACPI has no means of t
116 the SPISerialBus() resource defines it on the
117 to avoid a chain of negations, the GPIO polari
118 Active High. Even for the cases when _DSD() is
119 above) the GPIO CS polarity must be defined Ac
120
121 Other supported properties
122 ==========================
123
124 Following Device Tree compatible device proper
125 _DSD device properties for GPIO controllers:
126
127 - gpio-hog
128 - output-high
129 - output-low
130 - input
131 - line-name
132
133 Example::
134
135 Name (_DSD, Package () {
136 // _DSD Hierarchical Properties Extensio
137 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a
138 Package () {
139 Package () { "hog-gpio8", "G8PU" }
140 }
141 })
142
143 Name (G8PU, Package () {
144 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4a
145 Package () {
146 Package () { "gpio-hog", 1 },
147 Package () { "gpios", Package () { 8
148 Package () { "output-high", 1 },
149 Package () { "line-name", "gpio8-pul
150 }
151 })
152
153 - gpio-line-names
154
155 The ``gpio-line-names`` declaration is a list
156 describes each line/pin of a GPIO controller/e
157 a package, must be inserted inside the GPIO co
158 table (typically inside the DSDT). The ``gpio-
159 following rules (see also the examples):
160
161 - the first name in the list corresponds wit
162 controller/expander
163 - the names inside the list must be consecut
164 - the list can be incomplete and can end bef
165 other words, it is not mandatory to fill a
166 - empty names are allowed (two quotation mar
167 name)
168 - names inside one GPIO controller/expander
169
170 Example of a GPIO controller of 16 lines, with
171 empty names::
172
173 Package () {
174 "gpio-line-names",
175 Package () {
176 "pin_0",
177 "pin_1",
178 "",
179 "",
180 "pin_3",
181 "pin_4_push_button",
182 }
183 }
184
185 At runtime, the above declaration produces the
186 "libgpiod" tools)::
187
188 root@debian:~# gpioinfo gpiochip4
189 gpiochip4 - 16 lines:
190 line 0: "pin_0" unused
191 line 1: "pin_1" unused
192 line 2: unnamed unused
193 line 3: unnamed unused
194 line 4: "pin_3" unused
195 line 5: "pin_4_push_button" unused
196 line 6: unnamed unused
197 line 7 unnamed unused
198 line 8: unnamed unused
199 line 9: unnamed unused
200 line 10: unnamed unused
201 line 11: unnamed unused
202 line 12: unnamed unused
203 line 13: unnamed unused
204 line 14: unnamed unused
205 line 15: unnamed unused
206 root@debian:~# gpiofind pin_4_push_button
207 gpiochip4 5
208 root@debian:~#
209
210 Another example::
211
212 Package () {
213 "gpio-line-names",
214 Package () {
215 "SPI0_CS_N", "EXP2_INT", "MUX6_IO",
216 "MUX7_IO", "LVL_C_A1", "MUX0_IO", "S
217 }
218 }
219
220 See Documentation/devicetree/bindings/gpio/gpi
221 about these properties.
222
223 ACPI GPIO Mappings Provided by Drivers
224 ======================================
225
226 There are systems in which the ACPI tables do
227 with GpioIo()/GpioInt() resources and device d
228 them.
229
230 In those cases ACPI device identification obje
231 available to the driver can be used to identif
232 to be sufficient to determine the meaning and
233 listed by the GpioIo()/GpioInt() resources ret
234 the driver is supposed to know what to use the
235 once it has identified the device. Having don
236 to the GPIO lines it is going to use and provi
237 mapping between those names and the ACPI GPIO
238
239 To do that, the driver needs to define a mappi
240 array of struct acpi_gpio_mapping objects that
241 to an array of line data (struct acpi_gpio_par
242 array. Each struct acpi_gpio_params object co
243 crs_entry_index, line_index, active_low, repre
244 GpioIo()/GpioInt() resource in _CRS starting f
245 line in that resource starting from zero, and
246 respectively, in analogy with the _DSD GPIO pr
247
248 For the example Bluetooth device discussed pre
249 question would look like this::
250
251 static const struct acpi_gpio_params reset_g
252 static const struct acpi_gpio_params shutdow
253
254 static const struct acpi_gpio_mapping blueto
255 { "reset-gpios", &reset_gpio, 1 },
256 { "shutdown-gpios", &shutdown_gpio, 1 },
257 { }
258 };
259
260 Next, the mapping table needs to be passed as
261 acpi_dev_add_driver_gpios() or its managed ana
262 register it with the ACPI device object pointe
263 argument. That should be done in the driver's
264 On removal, the driver should unregister its G
265 calling acpi_dev_remove_driver_gpios() on the
266 table was previously registered.
267
268 Using the _CRS fallback
269 =======================
270
271 If a device does not have _DSD or the driver d
272 mapping, the Linux GPIO framework refuses to r
273 because the driver does not know what it actua
274 have a device like below::
275
276 Device (BTH)
277 {
278 Name (_HID, ...)
279
280 Name (_CRS, ResourceTemplate () {
281 GpioIo (Exclusive, PullNone, 0, 0, I
282 "\\_SB.GPO0", 0, ResourceCon
283 GpioIo (Exclusive, PullNone, 0, 0, I
284 "\\_SB.GPO0", 0, ResourceCon
285 })
286 }
287
288 The driver might expect to get the right GPIO
289
290 desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW
291 if (IS_ERR(desc))
292 ...error handling...
293
294 but since there is no way to know the mapping
295 the GpioIo() in _CRS desc will hold ERR_PTR(-E
296
297 The driver author can solve this by passing th
298 (this is the recommended way and it's document
299
300 The ACPI GPIO mapping tables should not contam
301 knowing about which exact device they are serv
302 the ACPI GPIO mapping tables are hardly linked
303 objects, as listed in the above chapter, of th
304
305 Getting GPIO descriptor
306 =======================
307
308 There are two main approaches to get GPIO reso
309
310 desc = gpiod_get(dev, connection_id, flags);
311 desc = gpiod_get_index(dev, connection_id, i
312
313 We may consider two different cases here, i.e.
314 provided and otherwise.
315
316 Case 1::
317
318 desc = gpiod_get(dev, "non-null-connection-i
319 desc = gpiod_get_index(dev, "non-null-connec
320
321 Case 2::
322
323 desc = gpiod_get(dev, NULL, flags);
324 desc = gpiod_get_index(dev, NULL, index, fla
325
326 Case 1 assumes that corresponding ACPI device
327 defined device properties and will prevent to
328 otherwise.
329
330 Case 2 explicitly tells GPIO core to look for
331
332 Be aware that gpiod_get_index() in cases 1 and
333 are two versions of ACPI device description pr
334 present in the driver, will return different r
335 certain driver has to handle them carefully as
336 chapter.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.