driver-api/gpio/intro.rst

6 GPIO Interfaces
10 GPIOs in drivers, and how to write a driver for a device that provides GPIOs
14 What is a GPIO?
17 A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
19 to Linux developers working with embedded and custom hardware. Each GPIO
20 represents a bit connected to a particular pin, or "ball" on Ball Grid Array
25 System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
26 non-dedicated pin can be configured as a GPIO; and most chips have at least
29 often have a few such pins to help with pin scarcity on SOCs; and there are
30 also "GPIO Expander" chips that connect using the I2C or SPI serial buses.
31 Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
36   - Output values are writable (high=1, low=0). Some chips also have
38     value might be driven, supporting "wire-OR" and similar schemes for the
41   - Input values are likewise readable (1, 0). Some chips support readback
42     of pins configured as "output", which is very useful in such "wire-OR"
43     cases (to support bidirectional signaling). GPIO controllers may have
44     input de-glitch/debounce logic, sometimes with software controls.
46   - Inputs can often be used as IRQ signals, often edge triggered but
48     wakeup events, to wake the system from a low power state.
50   - Usually a GPIO will be configurable as either input or output, as needed
53   - Most GPIOs can be accessed while holding spinlocks, but those accessed
54     through a serial bus normally can't. Some systems support both types.
56 On a given board each GPIO is used for one specific purpose like monitoring
57 MMC/SD card insertion/removal, detecting card write-protect status, driving
58 a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware
59 watchdog, sensing a switch, and so on.
62 Common GPIO Properties
65 These properties are met through all the other documents of the GPIO interface
66 and it is useful to understand them, especially if you need to define GPIO
69 Active-High and Active-Low
70 --------------------------
71 It is natural to assume that a GPIO is "active" when its output signal is 1
72 ("high"), and inactive when it is 0 ("low"). However in practice the signal of a
73 GPIO may be inverted before is reaches its destination, or a device could decide
75 be transparent to device drivers, therefore it is possible to define a GPIO as
76 being either active-high ("1" means "active", the default) or active-low ("0"
81 --------------------------
85 used for TTL. A pullup or pulldown resistor causes the high or low signal level.
86 This is sometimes called a "wire-AND"; or more practically, from the negative
87 logic (low=true) perspective this is a "wire-OR".
89 One common example of an open drain signal is a shared active-low IRQ line.
92 Some GPIO controllers directly support open drain and open source outputs; many
94 support it, there's a common idiom you can use to emulate it with any GPIO pin
97  **LOW**: ``gpiod_direction_output(gpio, 0)`` ... this drives the signal and
100  **HIGH**: ``gpiod_direction_input(gpio)`` ... this turns off the output, so
104 high signal and configuring the GPIO as input for low. This open drain/open
105 source emulation can be handled transparently by the GPIO framework.
107 If you are "driving" the signal high but gpiod_get_value(gpio) reports a low
110 example, that's how I2C clocks are stretched:  a slave that needs a slower clock