driver-api/gpio/consumer.rst

6 it describes the new descriptor-based interface. For a description of the
7 deprecated integer-based GPIO interface please refer to legacy.rst.
10 Guidelines for GPIOs consumers
15 obtain and use GPIOs are available by including the following file::
23 - Simple compile coverage with e.g. COMPILE_TEST - it does not matter that
27 - Truly optional GPIOLIB support - where the driver does not really make use
28   of the GPIOs on certain compile-time configurations for certain systems, but
29   will use it under other compile-time configurations. In this case the
37 All the functions that work with the descriptor-based GPIO interface are
44 Obtaining and Disposing GPIOs
47 With the descriptor-based interface, GPIOs are identified with an opaque,
48 non-forgeable handler that must be obtained through a call to one of the
56 If a function is implemented by using several GPIOs together (e.g. a simple LED
64 see Documentation/driver-api/gpio/board.rst
89 with IS_ERR() (they will never return a NULL pointer). -ENOENT will be returned
96 instead of -ENOENT if no GPIO has been assigned to the requested function::
110 -ENOSYS return codes.  System integrators should however be careful to enable
113 For a function using multiple GPIOs all of those can be obtained with one call::
129 The following function returns NULL instead of -ENOENT if no GPIOs have been
136 Device-managed variants of these functions are also defined::
167 For an array of GPIOs this function can be used::
175 The device-managed variants are, unsurprisingly::
182 Using GPIOs
186 -----------------
188 direction-setting flags have been given to gpiod_get*(), this is done by
197 for spinlock-safe GPIOs it is OK to use them before tasking is enabled, as part
200 For output GPIOs, the value provided becomes the initial output value. This
209 Be aware that there is no default direction for GPIOs. Therefore, **using a GPIO
214 Spinlock-Safe GPIO Access
215 -------------------------
217 don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ
220 Use the following calls to access GPIOs from an atomic context::
228 open-drain signaling and output latencies.
233 Also, using these calls for GPIOs that can't safely be accessed without sleeping
238 --------------------------
242 sleeping, which can't be done from inside IRQ handlers.
244 Platforms that support this type of GPIO distinguish them from other GPIOs by
249 To access such GPIOs, a different set of accessors is defined::
254 Accessing such GPIOs requires a context which may sleep, for example a threaded
255 IRQ handler, and those accessors must be used instead of spinlock-safe
258 Other than the fact that these accessors might sleep, and will work on GPIOs
260 spinlock-safe calls.
266 ---------------------------------------
280 parameter "value" as "asserted" ("1") or "de-asserted" ("0"). The physical line
302 but it should be avoided as much as possible, especially by system-agnostic drivers
308 -------------------------
313 The following set of calls ignore the active-low or open drain property of a GPIO and
332 Access multiple GPIOs with a single function call
333 -------------------------------------------------
334 The following functions get or set the values of an array of GPIOs::
370 The array can be an arbitrary set of GPIOs. The functions will try to access
371 GPIOs belonging to the same bank or chip simultaneously if supported by the
373 can be expected. If simultaneous access is not possible the GPIOs will be
378 	* array_size	- the number of array elements
379 	* desc_array	- an array of GPIO descriptors
380 	* array_info	- optional information obtained from gpiod_get_array()
381 	* value_bitmap	- a bitmap to store the GPIOs' values (get) or
382           a bitmap of values to assign to the GPIOs (set)
386 matches the desired group of GPIOs, those GPIOs can be accessed by simply using
390 	gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc,
391 			      my_gpio_descs->info, my_gpio_value_bitmap);
399 Note that for optimal performance GPIOs belonging to the same chip should be
416 GPIOs mapped to IRQs
417 --------------------
424 done (most likely because that particular GPIO cannot be used as IRQ). It is an
429 Non-error values returned from gpiod_to_irq() can be passed to request_irq() or
431 by the board-specific initialization code. Note that IRQ trigger options are
436 GPIOs and ACPI
439 On ACPI systems, GPIOs are described by GpioIo()/GpioInt() resources listed by
441 connection IDs (names) for GPIOs, so it is necessary to use an additional
446 GPIOs described by the GpioIo()/GpioInt() resources in _CRS.  If that is the
451 For details refer to Documentation/firmware-guide/acpi/gpio-properties.rst
456 Many kernel subsystems and drivers still handle GPIOs using the legacy
457 integer-based interface. It is strongly recommended to update these to the new
460 and vice-versa::