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