1============
  2Introduction
  3============
  4
  5
  6GPIO Interfaces
  7===============
  8
  9The documents in this directory give detailed instructions on how to access
 10GPIOs in drivers, and how to write a driver for a device that provides GPIOs
 11itself.
 12
 
 
 
 
 
 
 
 
 
 
 
 
 13
 14What is a GPIO?
 15===============
 16
 17A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
 18digital signal. They are provided from many kinds of chips, and are familiar
 19to Linux developers working with embedded and custom hardware. Each GPIO
 20represents a bit connected to a particular pin, or "ball" on Ball Grid Array
 21(BGA) packages. Board schematics show which external hardware connects to
 22which GPIOs. Drivers can be written generically, so that board setup code
 23passes such pin configuration data to drivers.
 24
 25System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
 26non-dedicated pin can be configured as a GPIO; and most chips have at least
 27several dozen of them. Programmable logic devices (like FPGAs) can easily
 28provide GPIOs; multifunction chips like power managers, and audio codecs
 29often have a few such pins to help with pin scarcity on SOCs; and there are
 30also "GPIO Expander" chips that connect using the I2C or SPI serial buses.
 31Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
 32firmware knowing how they're used).
 33
 34The exact capabilities of GPIOs vary between systems. Common options:
 35
 36  - Output values are writable (high=1, low=0). Some chips also have
 37    options about how that value is driven, so that for example only one
 38    value might be driven, supporting "wire-OR" and similar schemes for the
 39    other value (notably, "open drain" signaling).
 40
 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.
 45
 46  - Inputs can often be used as IRQ signals, often edge triggered but
 47    sometimes level triggered. Such IRQs may be configurable as system
 48    wakeup events, to wake the system from a low power state.
 49
 50  - Usually a GPIO will be configurable as either input or output, as needed
 51    by different product boards; single direction ones exist too.
 52
 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.
 55
 56On a given board each GPIO is used for one specific purpose like monitoring
 57MMC/SD card insertion/removal, detecting card write-protect status, driving
 58a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware
 59watchdog, sensing a switch, and so on.
 60
 61
 62Common GPIO Properties
 63======================
 64
 65These properties are met through all the other documents of the GPIO interface
 66and it is useful to understand them, especially if you need to define GPIO
 67mappings.
 68
 69Active-High and Active-Low
 70--------------------------
 71It 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
 73GPIO may be inverted before is reaches its destination, or a device could decide
 74to have different conventions about what "active" means. Such decisions should
 75be transparent to device drivers, therefore it is possible to define a GPIO as
 76being either active-high ("1" means "active", the default) or active-low ("0"
 77means "active") so that drivers only need to worry about the logical signal and
 78not about what happens at the line level.
 79
 80Open Drain and Open Source
 81--------------------------
 82Sometimes shared signals need to use "open drain" (where only the low signal
 83level is actually driven), or "open source" (where only the high signal level is
 84driven) signaling. That term applies to CMOS transistors; "open collector" is
 85used for TTL. A pullup or pulldown resistor causes the high or low signal level.
 86This is sometimes called a "wire-AND"; or more practically, from the negative
 87logic (low=true) perspective this is a "wire-OR".
 88
 89One common example of an open drain signal is a shared active-low IRQ line.
 90Also, bidirectional data bus signals sometimes use open drain signals.
 91
 92Some GPIO controllers directly support open drain and open source outputs; many
 93don't. When you need open drain signaling but your hardware doesn't directly
 94support it, there's a common idiom you can use to emulate it with any GPIO pin
 95that can be used as either an input or an output:
 96
 97 **LOW**: ``gpiod_direction_output(gpio, 0)`` ... this drives the signal and
 98 overrides the pullup.
 99
100 **HIGH**: ``gpiod_direction_input(gpio)`` ... this turns off the output, so
101 the pullup (or some other device) controls the signal.
102
103The same logic can be applied to emulate open source signaling, by driving the
104high signal and configuring the GPIO as input for low. This open drain/open
105source emulation can be handled transparently by the GPIO framework.
106
107If you are "driving" the signal high but gpiod_get_value(gpio) reports a low
108value (after the appropriate rise time passes), you know some other component is
109driving the shared signal low. That's not necessarily an error. As one common
110example, that's how I2C clocks are stretched:  a slave that needs a slower clock
111delays the rising edge of SCK, and the I2C master adjusts its signaling rate
112accordingly.

  1============
  2Introduction
  3============
  4
  5
  6GPIO Interfaces
  7===============
  8
  9The documents in this directory give detailed instructions on how to access
 10GPIOs in drivers, and how to write a driver for a device that provides GPIOs
 11itself.
 12
 13Due to the history of GPIO interfaces in the kernel, there are two different
 14ways to obtain and use GPIOs:
 15
 16  - The descriptor-based interface is the preferred way to manipulate GPIOs,
 17    and is described by all the files in this directory excepted legacy.rst.
 18  - The legacy integer-based interface which is considered deprecated (but still
 19    usable for compatibility reasons) is documented in legacy.rst.
 20
 21The remainder of this document applies to the new descriptor-based interface.
 22legacy.rst contains the same information applied to the legacy
 23integer-based interface.
 24
 25
 26What is a GPIO?
 27===============
 28
 29A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
 30digital signal. They are provided from many kinds of chips, and are familiar
 31to Linux developers working with embedded and custom hardware. Each GPIO
 32represents a bit connected to a particular pin, or "ball" on Ball Grid Array
 33(BGA) packages. Board schematics show which external hardware connects to
 34which GPIOs. Drivers can be written generically, so that board setup code
 35passes such pin configuration data to drivers.
 36
 37System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
 38non-dedicated pin can be configured as a GPIO; and most chips have at least
 39several dozen of them. Programmable logic devices (like FPGAs) can easily
 40provide GPIOs; multifunction chips like power managers, and audio codecs
 41often have a few such pins to help with pin scarcity on SOCs; and there are
 42also "GPIO Expander" chips that connect using the I2C or SPI serial buses.
 43Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
 44firmware knowing how they're used).
 45
 46The exact capabilities of GPIOs vary between systems. Common options:
 47
 48  - Output values are writable (high=1, low=0). Some chips also have
 49    options about how that value is driven, so that for example only one
 50    value might be driven, supporting "wire-OR" and similar schemes for the
 51    other value (notably, "open drain" signaling).
 52
 53  - Input values are likewise readable (1, 0). Some chips support readback
 54    of pins configured as "output", which is very useful in such "wire-OR"
 55    cases (to support bidirectional signaling). GPIO controllers may have
 56    input de-glitch/debounce logic, sometimes with software controls.
 57
 58  - Inputs can often be used as IRQ signals, often edge triggered but
 59    sometimes level triggered. Such IRQs may be configurable as system
 60    wakeup events, to wake the system from a low power state.
 61
 62  - Usually a GPIO will be configurable as either input or output, as needed
 63    by different product boards; single direction ones exist too.
 64
 65  - Most GPIOs can be accessed while holding spinlocks, but those accessed
 66    through a serial bus normally can't. Some systems support both types.
 67
 68On a given board each GPIO is used for one specific purpose like monitoring
 69MMC/SD card insertion/removal, detecting card write-protect status, driving
 70a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware
 71watchdog, sensing a switch, and so on.
 72
 73
 74Common GPIO Properties
 75======================
 76
 77These properties are met through all the other documents of the GPIO interface
 78and it is useful to understand them, especially if you need to define GPIO
 79mappings.
 80
 81Active-High and Active-Low
 82--------------------------
 83It is natural to assume that a GPIO is "active" when its output signal is 1
 84("high"), and inactive when it is 0 ("low"). However in practice the signal of a
 85GPIO may be inverted before is reaches its destination, or a device could decide
 86to have different conventions about what "active" means. Such decisions should
 87be transparent to device drivers, therefore it is possible to define a GPIO as
 88being either active-high ("1" means "active", the default) or active-low ("0"
 89means "active") so that drivers only need to worry about the logical signal and
 90not about what happens at the line level.
 91
 92Open Drain and Open Source
 93--------------------------
 94Sometimes shared signals need to use "open drain" (where only the low signal
 95level is actually driven), or "open source" (where only the high signal level is
 96driven) signaling. That term applies to CMOS transistors; "open collector" is
 97used for TTL. A pullup or pulldown resistor causes the high or low signal level.
 98This is sometimes called a "wire-AND"; or more practically, from the negative
 99logic (low=true) perspective this is a "wire-OR".
100
101One common example of an open drain signal is a shared active-low IRQ line.
102Also, bidirectional data bus signals sometimes use open drain signals.
103
104Some GPIO controllers directly support open drain and open source outputs; many
105don't. When you need open drain signaling but your hardware doesn't directly
106support it, there's a common idiom you can use to emulate it with any GPIO pin
107that can be used as either an input or an output:
108
109 **LOW**: ``gpiod_direction_output(gpio, 0)`` ... this drives the signal and
110 overrides the pullup.
111
112 **HIGH**: ``gpiod_direction_input(gpio)`` ... this turns off the output, so
113 the pullup (or some other device) controls the signal.
114
115The same logic can be applied to emulate open source signaling, by driving the
116high signal and configuring the GPIO as input for low. This open drain/open
117source emulation can be handled transparently by the GPIO framework.
118
119If you are "driving" the signal high but gpiod_get_value(gpio) reports a low
120value (after the appropriate rise time passes), you know some other component is
121driving the shared signal low. That's not necessarily an error. As one common
122example, that's how I2C clocks are stretched:  a slave that needs a slower clock
123delays the rising edge of SCK, and the I2C master adjusts its signaling rate
124accordingly.