1 ==================================
2 GPIO Descriptor Consumer Interface
3 ==================================
4
5 This document describes the consumer interface
6
7
8 Guidelines for GPIOs consumers
9 ==============================
10
11 Drivers that can't work without standard GPIO
12 that depend on GPIOLIB or select GPIOLIB. The
13 obtain and use GPIOs are available by includin
14
15 #include <linux/gpio/consumer.h>
16
17 There are static inline stubs for all function
18 where GPIOLIB is disabled. When these stubs ar
19 warnings. These stubs are used for two use cas
20
21 - Simple compile coverage with e.g. COMPILE_TE
22 the current platform does not enable or sele
23 going to execute the system anyway.
24
25 - Truly optional GPIOLIB support - where the d
26 of the GPIOs on certain compile-time configu
27 will use it under other compile-time configu
28 consumer must make sure not to call into the
29 be met with console warnings that may be per
30 Combining truly optional GPIOLIB usage with
31 ``[devm_]gpiod_get_optional()`` is a *bad id
32 error messages. Use the ordinary getter func
33 some open coding of error handling should be
34
35 All the functions that work with the descripto
36 prefixed with ``gpiod_``. The ``gpio_`` prefix
37 interface. No other function in the kernel sho
38 of the legacy functions is strongly discourage
39 <linux/gpio/consumer.h> and descriptors exclus
40
41
42 Obtaining and Disposing GPIOs
43 =============================
44
45 With the descriptor-based interface, GPIOs are
46 non-forgeable handler that must be obtained th
47 gpiod_get() functions. Like many other kernel
48 device that will use the GPIO and the function
49 fulfill::
50
51 struct gpio_desc *gpiod_get(struct dev
52 enum gpiod
53
54 If a function is implemented by using several
55 device that displays digits), an additional in
56
57 struct gpio_desc *gpiod_get_index(stru
58 cons
59 enum
60
61 For a more detailed description of the con_id
62 see Documentation/driver-api/gpio/board.rst
63
64 The flags parameter is used to optionally spec
65 for the GPIO. Values can be:
66
67 * GPIOD_ASIS or 0 to not initialize the GPIO a
68 later with one of the dedicated functions.
69 * GPIOD_IN to initialize the GPIO as input.
70 * GPIOD_OUT_LOW to initialize the GPIO as outp
71 * GPIOD_OUT_HIGH to initialize the GPIO as out
72 * GPIOD_OUT_LOW_OPEN_DRAIN same as GPIOD_OUT_L
73 to be electrically used with open drain.
74 * GPIOD_OUT_HIGH_OPEN_DRAIN same as GPIOD_OUT_
75 to be electrically used with open drain.
76
77 Note that the initial value is *logical* and t
78 whether the line is configured active high or
79 :ref:`active_low_semantics`).
80
81 The two last flags are used for use cases wher
82 as I2C: if the line is not already configured
83 (see board.rst), then open drain will be enfor
84 printed that the board configuration needs to
85
86 Both functions return either a valid GPIO desc
87 with IS_ERR() (they will never return a NULL p
88 if and only if no GPIO has been assigned to th
89 other error codes are used for cases where a G
90 occurred while trying to acquire it. This is u
91 errors and an absence of GPIO for optional GPI
92 pattern where a GPIO is optional, the gpiod_ge
93 gpiod_get_index_optional() functions can be us
94 instead of -ENOENT if no GPIO has been assigne
95
96 struct gpio_desc *gpiod_get_optional(s
97 c
98 e
99
100 struct gpio_desc *gpiod_get_index_opti
101
102
103
104
105 Note that gpio_get*_optional() functions (and
106 the rest of gpiolib API, also return NULL when
107 This is helpful to driver authors, since they
108 -ENOSYS return codes. System integrators shou
109 gpiolib on systems that need it.
110
111 For a function using multiple GPIOs all of tho
112
113 struct gpio_descs *gpiod_get_array(str
114 con
115 enu
116
117 This function returns a struct gpio_descs whic
118 descriptors. It also contains a pointer to a
119 if passed back to get/set array functions, may
120
121 struct gpio_descs {
122 struct gpio_array *info;
123 unsigned int ndescs;
124 struct gpio_desc *desc[];
125 }
126
127 The following function returns NULL instead of
128 assigned to the requested function::
129
130 struct gpio_descs *gpiod_get_array_opt
131
132
133
134 Device-managed variants of these functions are
135
136 struct gpio_desc *devm_gpiod_get(struc
137 enum
138
139 struct gpio_desc *devm_gpiod_get_index
140
141
142
143
144 struct gpio_desc *devm_gpiod_get_optio
145
146
147
148 struct gpio_desc *devm_gpiod_get_index
149
150
151
152
153 struct gpio_descs *devm_gpiod_get_arra
154
155
156
157 struct gpio_descs *devm_gpiod_get_arra
158
159
160
161 A GPIO descriptor can be disposed of using the
162
163 void gpiod_put(struct gpio_desc *desc)
164
165 For an array of GPIOs this function can be use
166
167 void gpiod_put_array(struct gpio_descs
168
169 It is strictly forbidden to use a descriptor a
170 It is also not allowed to individually release
171 from an array acquired with gpiod_get_array().
172
173 The device-managed variants are, unsurprisingl
174
175 void devm_gpiod_put(struct device *dev
176
177 void devm_gpiod_put_array(struct devic
178
179
180 Using GPIOs
181 ===========
182
183 Setting Direction
184 -----------------
185 The first thing a driver must do with a GPIO i
186 direction-setting flags have been given to gpi
187 invoking one of the gpiod_direction_*() functi
188
189 int gpiod_direction_input(struct gpio_
190 int gpiod_direction_output(struct gpio
191
192 The return value is zero for success, else a n
193 checked, since the get/set calls don't return
194 is possible. You should normally issue these c
195 for spinlock-safe GPIOs it is OK to use them b
196 of early board setup.
197
198 For output GPIOs, the value provided becomes t
199 helps avoid signal glitching during system sta
200
201 A driver can also query the current direction
202
203 int gpiod_get_direction(const struct g
204
205 This function returns 0 for output, 1 for inpu
206
207 Be aware that there is no default direction fo
208 without setting its direction first is illegal
209 behavior!**
210
211
212 Spinlock-Safe GPIO Access
213 -------------------------
214 Most GPIO controllers can be accessed with mem
215 don't need to sleep, and can safely be done fr
216 handlers and similar contexts.
217
218 Use the following calls to access GPIOs from a
219
220 int gpiod_get_value(const struct gpio_
221 void gpiod_set_value(struct gpio_desc
222
223 The values are boolean, zero for inactive, non
224 value of an output pin, the value returned sho
225 That won't always match the specified output v
226 open-drain signaling and output latencies.
227
228 The get/set calls do not return errors because
229 reported earlier from gpiod_direction_*(). How
230 can read the value of output pins; those that
231 Also, using these calls for GPIOs that can't s
232 (see below) is an error.
233
234
235 GPIO Access That May Sleep
236 --------------------------
237 Some GPIO controllers must be accessed using m
238 SPI. Commands to read or write those GPIO valu
239 head of a queue to transmit a command and get
240 sleeping, which can't be done from inside IRQ
241
242 Platforms that support this type of GPIO disti
243 returning nonzero from this call::
244
245 int gpiod_cansleep(const struct gpio_d
246
247 To access such GPIOs, a different set of acces
248
249 int gpiod_get_value_cansleep(const str
250 void gpiod_set_value_cansleep(struct g
251
252 Accessing such GPIOs requires a context which
253 IRQ handler, and those accessors must be used
254 accessors without the cansleep() name suffix.
255
256 Other than the fact that these accessors might
257 that can't be accessed from hardIRQ handlers,
258 spinlock-safe calls.
259
260
261 .. _active_low_semantics:
262
263 The active low and open drain semantics
264 ---------------------------------------
265 As a consumer should not have to care about th
266 gpiod_set_value_xxx() or gpiod_set_array_value
267 the *logical* value. With this they take the a
268 This means that they check whether the GPIO is
269 and if so, they manipulate the passed value be
270 driven.
271
272 The same is applicable for open drain or open
273 actively drive their output high (open drain)
274 switch their output to a high impedance value.
275 care. (For details read about open drain in dr
276
277 With this, all the gpiod_set_(array)_value_xxx
278 parameter "value" as "active" ("1") or "inacti
279 level will be driven accordingly.
280
281 As an example, if the active low property for
282 gpiod_set_(array)_value_xxx() passes "active"
283 will be driven low.
284
285 To summarize::
286
287 Function (example) line prop
288 gpiod_set_raw_value(desc, 0); don't car
289 gpiod_set_raw_value(desc, 1); don't car
290 gpiod_set_value(desc, 0); default (
291 gpiod_set_value(desc, 1); default (
292 gpiod_set_value(desc, 0); active lo
293 gpiod_set_value(desc, 1); active lo
294 gpiod_set_value(desc, 0); open drai
295 gpiod_set_value(desc, 1); open drai
296 gpiod_set_value(desc, 0); open sour
297 gpiod_set_value(desc, 1); open sour
298
299 It is possible to override these semantics usi
300 but it should be avoided as much as possible,
301 which should not need to care about the actual
302 the logical value instead.
303
304
305 Accessing raw GPIO values
306 -------------------------
307 Consumers exist that need to manage the logica
308 their device will actually receive, no matter
309 line.
310
311 The following set of calls ignore the active-l
312 work on the raw line value::
313
314 int gpiod_get_raw_value(const struct g
315 void gpiod_set_raw_value(struct gpio_d
316 int gpiod_get_raw_value_cansleep(const
317 void gpiod_set_raw_value_cansleep(stru
318 int gpiod_direction_output_raw(struct
319
320 The active low state of a GPIO can also be que
321 following calls::
322
323 int gpiod_is_active_low(const struct g
324 void gpiod_toggle_active_low(struct gp
325
326 Note that these functions should only be used
327 should not have to care about the physical lin
328
329
330 Access multiple GPIOs with a single function c
331 ----------------------------------------------
332 The following functions get or set the values
333
334 int gpiod_get_array_value(unsigned int
335 struct gpio_
336 struct gpio_
337 unsigned lon
338 int gpiod_get_raw_array_value(unsigned
339 struct g
340 struct g
341 unsigned
342 int gpiod_get_array_value_cansleep(uns
343 str
344 str
345 uns
346 int gpiod_get_raw_array_value_cansleep
347 str
348 str
349 uns
350
351 int gpiod_set_array_value(unsigned int
352 struct gpio_
353 struct gpio_
354 unsigned lon
355 int gpiod_set_raw_array_value(unsigned
356 struct g
357 struct g
358 unsigned
359 int gpiod_set_array_value_cansleep(uns
360 str
361 str
362 uns
363 int gpiod_set_raw_array_value_cansleep
364
365
366
367
368 The array can be an arbitrary set of GPIOs. Th
369 GPIOs belonging to the same bank or chip simul
370 corresponding chip driver. In that case a sign
371 can be expected. If simultaneous access is not
372 accessed sequentially.
373
374 The functions take four arguments:
375
376 * array_size - the number of array
377 * desc_array - an array of GPIO des
378 * array_info - optional information
379 * value_bitmap - a bitmap to store th
380 a bitmap of values to assign to the
381
382 The descriptor array can be obtained using the
383 or one of its variants. If the group of descri
384 matches the desired group of GPIOs, those GPIO
385 the struct gpio_descs returned by gpiod_get_ar
386
387 struct gpio_descs *my_gpio_descs = gpi
388 gpiod_set_array_value(my_gpio_descs->n
389 my_gpio_descs->i
390
391 It is also possible to access a completely arb
392 descriptors may be obtained using any combinat
393 gpiod_get_array(). Afterwards the array of des
394 manually before it can be passed to one of the
395 array_info should be set to NULL.
396
397 Note that for optimal performance GPIOs belong
398 contiguous within the array of descriptors.
399
400 Still better performance may be achieved if ar
401 match hardware pin numbers of a single chip.
402 array function matches the one obtained from g
403 associated with the array is also passed, the
404 processing path, passing the value_bitmap argu
405 .get/set_multiple() callback of the chip. Tha
406 banks as data I/O ports without much loss of p
407
408 The return value of gpiod_get_array_value() an
409 or negative on error. Note the difference to g
410 0 or 1 on success to convey the GPIO value. Wi
411 values are stored in value_array rather than p
412
413
414 GPIOs mapped to IRQs
415 --------------------
416 GPIO lines can quite often be used as IRQs. Yo
417 corresponding to a given GPIO using the follow
418
419 int gpiod_to_irq(const struct gpio_des
420
421 It will return an IRQ number, or a negative er
422 done (most likely because that particular GPIO
423 unchecked error to use a GPIO that wasn't set
424 gpiod_direction_input(), or to use an IRQ numb
425 from gpiod_to_irq(). gpiod_to_irq() is not all
426
427 Non-error values returned from gpiod_to_irq()
428 free_irq(). They will often be stored into IRQ
429 by the board-specific initialization code. Not
430 part of the IRQ interface, e.g. IRQF_TRIGGER_F
431 capabilities.
432
433
434 GPIOs and ACPI
435 ==============
436
437 On ACPI systems, GPIOs are described by GpioIo
438 the _CRS configuration objects of devices. Th
439 connection IDs (names) for GPIOs, so it is nec
440 mechanism for this purpose.
441
442 Systems compliant with ACPI 5.1 or newer may p
443 which, among other things, may be used to prov
444 GPIOs described by the GpioIo()/GpioInt() reso
445 case, it will be handled by the GPIO subsystem
446 _DSD is not present, the mappings between Gpio
447 connection IDs need to be provided by device d
448
449 For details refer to Documentation/firmware-gu
450
451
452 Interacting With the Legacy GPIO Subsystem
453 ==========================================
454 Many kernel subsystems and drivers still handl
455 integer-based interface. It is strongly recomm
456 gpiod interface. For cases where both interfac
457 two functions allow to convert a GPIO descript
458 and vice-versa::
459
460 int desc_to_gpio(const struct gpio_des
461 struct gpio_desc *gpio_to_desc(unsigne
462
463 The GPIO number returned by desc_to_gpio() can
464 the gpio\_*() functions for as long as the GPI
465 All the same, a GPIO number passed to gpio_to_
466 acquired using e.g. gpio_request_one(), and th
467 considered valid until that GPIO number is rel
468
469 Freeing a GPIO obtained by one API with the ot
470 unchecked error.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.