driver-api/gpio/legacy.rst

2 Legacy GPIO Interfaces
5 This provides an overview of GPIO access conventions on Linux.
11 What is a GPIO?
13 A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
15 to Linux developers working with embedded and custom hardware.  Each GPIO
22 non-dedicated pin can be configured as a GPIO; and most chips have at least
26 also "GPIO Expander" chips that connect using the I2C or SPI serial busses.
27 Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
39     cases (to support bidirectional signaling).  GPIO controllers may have
46   - Usually a GPIO will be configurable as either input or output, as needed
52 On a given board each GPIO is used for one specific purpose like monitoring
58 GPIO conventions
71 used for several very different kinds of GPIO controller.  (There is some
73 in this document, but drivers acting as clients to the GPIO interface must
77 use it when possible.  Platforms must select GPIOLIB if GPIO functionality
79 standard GPIO calls should have Kconfig entries which depend on GPIOLIB.  The
80 GPIO calls are available, either as "real code" or as optimized-away stubs,
100 for the GPIO lines so that board-specific setup code directly corresponds
101 to the relevant schematics.  In contrast, drivers should only use GPIO
107 uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
108 type of GPIO controller, and on one particular board 80-95 with an FPGA.
110 use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.
112 If you want to initialize a structure with an invalid GPIO number, use
114 test if such number from such a structure could reference a GPIO, you
123 Whether a platform supports multiple GPIO controllers is a platform-specific
125 of GPIO numbers, and whether new controllers can be added at runtime.  Such issues
126 can affect things including whether adjacent GPIO numbers are both valid.
130 The first thing a system should do with a GPIO is allocate it, using
133 One of the next things to do with a GPIO, often in board setup code when
134 setting up a platform_device using the GPIO, is mark its direction::
150 of a GPIO implicitly requests that GPIO (see below) if it has not been
154 Setting the direction can fail if the GPIO number is invalid, or when
155 that particular GPIO can't be used in that mode.  It's generally a bad
158 that board setup code probably needs to multiplex that pin as a GPIO,
162 Spinlock-Safe GPIO access
164 Most GPIO controllers can be accessed with memory read/write instructions.
171 	/* GPIO INPUT:  return zero or nonzero */
174 	/* GPIO OUTPUT */
182 The get/set calls have no error returns because "invalid GPIO" should have
189 calls to access the GPIO value in cases where the GPIO number (and for
197 GPIO access that may sleep
199 Some GPIO controllers must be accessed using message based busses like I2C
200 or SPI.  Commands to read or write those GPIO values require waiting to
204 Platforms that support this type of GPIO distinguish them from other GPIOs
205 by returning nonzero from this call (which requires a valid GPIO number,
212 	/* GPIO INPUT:  return zero or nonzero, might sleep */
215 	/* GPIO OUTPUT, might sleep */
228 from contexts which may sleep, since they may need to access the GPIO
249 	/* request GPIO, returning 0 or negative errno.
254 	/* release previously-claimed GPIO */
257 Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
270 GPIO can serve as a kind of lock.
284 GPIO signal to the appropriate pin should occur within a GPIO driver's
286 setup of an output GPIO's value. This allows a glitch-free migration from a
287 pin's special function to GPIO. This is sometimes required when using a GPIO
288 to implement a workaround on signals typically driven by a non-GPIO HW block.
290 Some platforms allow some or all GPIO signals to be routed to different pins.
291 Similarly, other aspects of the GPIO or pin may need to be configured, such as
294 the pinctrl subsystem's mapping table, so that GPIO users need not be aware
297 Also note that it's your responsibility to have stopped using a GPIO
303 	/* request a single GPIO, with initial configuration specified by
383 GPIO numbers are unsigned integers; so are IRQ numbers.  These make up
384 two logically distinct namespaces (GPIO 0 need not use IRQ 0).  You can
387 	/* map GPIO numbers to IRQ numbers */
390 	/* map IRQ numbers to GPIO numbers (avoid using this) */
395 some GPIOs can't be used as IRQs.)  It is an unchecked error to use a GPIO
425 Some GPIO controllers directly support open drain outputs; many don't.  When
427 there's a common idiom you can use to emulate it with any GPIO pin that can
444 GPIO controllers and the pinctrl subsystem
447 A GPIO controller on a SOC might be tightly coupled with the pinctrl
450 case where e.g. a GPIO controller need to reserve a pin or set the
458 But how does the pin control subsystem cross-correlate the GPIO
492 to route a given GPIO to any one of several pins.  (Yes, those examples all
514 a side effect of configuring an add-on board with some GPIO expanders.
517 GPIO implementor's framework (OPTIONAL)
520 easier for platforms to support different kinds of GPIO controller using
530 In this framework each GPIO controller is packaged as a "struct gpio_chip"
533  - methods to establish GPIO direction
534  - methods used to access GPIO values
540 the number of its first GPIO, and how many GPIOs it exposes.
544 gpio_chip and issue gpiochip_add().  Removing a GPIO controller should be
548 not exposed by the GPIO interfaces, such as addressing, power management,
549 and more.  Chips such as codecs will have complex non-GPIO state.
553 either NULL or the label associated with that GPIO when it was requested.
559 else it is up to the user to configure support for GPIO.
564 also ones on GPIO expanders.
567 GPIOs through GPIO-lib and the code cannot be enabled by the user.
578 referenced GPIO is the constant "12", getting or setting its value could
594 For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi
596 registering controller devices and ensures that their drivers know what GPIO
601 of GPIOs that chip will expose, and passes them to each GPIO expander chip
606 an I2C-based GPIO, its probe() routine should only be called after that GPIO
608 calls for that GPIO can work.  One way to address such dependencies is for
612 the GPIO controller device becomes unavailable.
619 debugfs interface, since it provides control over GPIO direction and
624 know for example that GPIO #23 controls the write protect line used to
626 may need to temporarily remove that protection, first importing a GPIO,
628 the write protection.  In normal use, GPIO #23 would never be touched,
632 userspace GPIO can be used to determine system configuration data that
634 GPIO drivers could be all that the system really needs.
637 GPIO tasks:  "leds-gpio" and "gpio_keys", respectively.  Use those
650    -	GPIO controllers ("gpio_chip" instances).
659 		a GPIO to userspace by writing its number to this file.
662 		for GPIO #19, if that's not requested by kernel code.
669 GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
678 		configure the GPIO as an output with that initial value.
681 		doesn't support changing the direction of a GPIO, or
683 		allow userspace to reconfigure this GPIO's direction.
685 	"value" ... reads as either 0 (low) or 1 (high).  If the GPIO
712 GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
718     	"base" ... same as N, the first GPIO managed by this chip
729 the correct GPIO number to use for a given signal.
737 	/* export the GPIO to userspace */
743 	/* create a sysfs link to an exported GPIO node */
747 After a kernel driver requests a GPIO, it may only be made available in
756 After the GPIO has been exported, gpio_export_link() allows creating
757 symlinks from elsewhere in sysfs to the GPIO sysfs node.  Drivers can
765 The functions listed in this section are deprecated. The GPIO descriptor based