113 lines · plain
1============2Introduction3============4 5 6GPIO Interfaces7===============8 9The documents in this directory give detailed instructions on how to access10GPIOs in drivers, and how to write a driver for a device that provides GPIOs11itself.12 13 14What is a GPIO?15===============16 17A "General Purpose Input/Output" (GPIO) is a flexible software-controlled18digital signal. They are provided from many kinds of chips, and are familiar19to Linux developers working with embedded and custom hardware. Each GPIO20represents a bit connected to a particular pin, or "ball" on Ball Grid Array21(BGA) packages. Board schematics show which external hardware connects to22which GPIOs. Drivers can be written generically, so that board setup code23passes such pin configuration data to drivers.24 25System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every26non-dedicated pin can be configured as a GPIO; and most chips have at least27several dozen of them. Programmable logic devices (like FPGAs) can easily28provide GPIOs; multifunction chips like power managers, and audio codecs29often have a few such pins to help with pin scarcity on SOCs; and there are30also "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 BIOS32firmware 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 have37 options about how that value is driven, so that for example only one38 value might be driven, supporting "wire-OR" and similar schemes for the39 other value (notably, "open drain" signaling).40 41 - Input values are likewise readable (1, 0). Some chips support readback42 of pins configured as "output", which is very useful in such "wire-OR"43 cases (to support bidirectional signaling). GPIO controllers may have44 input de-glitch/debounce logic, sometimes with software controls.45 46 - Inputs can often be used as IRQ signals, often edge triggered but47 sometimes level triggered. Such IRQs may be configurable as system48 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 needed51 by different product boards; single direction ones exist too.52 53 - Most GPIOs can be accessed while holding spinlocks, but those accessed54 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 monitoring57MMC/SD card insertion/removal, detecting card write-protect status, driving58a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware59watchdog, sensing a switch, and so on.60 61 62Common GPIO Properties63======================64 65These properties are met through all the other documents of the GPIO interface66and it is useful to understand them, especially if you need to define GPIO67mappings.68 69Active-High and Active-Low70--------------------------71It is natural to assume that a GPIO is "active" when its output signal is 172("high"), and inactive when it is 0 ("low"). However in practice the signal of a73GPIO may be inverted before is reaches its destination, or a device could decide74to have different conventions about what "active" means. Such decisions should75be transparent to device drivers, therefore it is possible to define a GPIO as76being 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 and78not about what happens at the line level.79 80Open Drain and Open Source81--------------------------82Sometimes shared signals need to use "open drain" (where only the low signal83level is actually driven), or "open source" (where only the high signal level is84driven) signaling. That term applies to CMOS transistors; "open collector" is85used 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 negative87logic (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; many93don't. When you need open drain signaling but your hardware doesn't directly94support it, there's a common idiom you can use to emulate it with any GPIO pin95that can be used as either an input or an output:96 97 **LOW**: ``gpiod_direction_output(gpio, 0)`` ... this drives the signal and98 overrides the pullup.99 100 **HIGH**: ``gpiod_direction_input(gpio)`` ... this turns off the output, so101 the pullup (or some other device) controls the signal.102 103The same logic can be applied to emulate open source signaling, by driving the104high signal and configuring the GPIO as input for low. This open drain/open105source emulation can be handled transparently by the GPIO framework.106 107If you are "driving" the signal high but gpiod_get_value(gpio) reports a low108value (after the appropriate rise time passes), you know some other component is109driving the shared signal low. That's not necessarily an error. As one common110example, that's how I2C clocks are stretched: a slave that needs a slower clock111delays the rising edge of SCK, and the I2C master adjusts its signaling rate112accordingly.113