Introduction

GPIO Interfaces

The documents in this directory give detailed instructions on how to accessGPIOs in drivers, and how to write a driver for a device that provides GPIOsitself.

Due to the history of GPIO interfaces in the kernel, there are two differentways to obtain and use GPIOs:

  • The descriptor-based interface is the preferred way to manipulate GPIOs,and is described by all the files in this directory excepted gpio-legacy.txt.
  • The legacy integer-based interface which is considered deprecated (but stillusable for compatibility reasons) is documented in gpio-legacy.txt.

The remainder of this document applies to the new descriptor-based interface.gpio-legacy.txt contains the same information applied to the legacyinteger-based interface.

What is a GPIO?

A “General Purpose Input/Output” (GPIO) is a flexible software-controlleddigital signal. They are provided from many kinds of chip, and are familiarto Linux developers working with embedded and custom hardware. Each GPIOrepresents a bit connected to a particular pin, or “ball” on Ball Grid Array(BGA) packages. Board schematics show which external hardware connects towhich GPIOs. Drivers can be written generically, so that board setup codepasses such pin configuration data to drivers.

System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, everynon-dedicated pin can be configured as a GPIO; and most chips have at leastseveral dozen of them. Programmable logic devices (like FPGAs) can easilyprovide GPIOs; multifunction chips like power managers, and audio codecsoften have a few such pins to help with pin scarcity on SOCs; and there arealso “GPIO Expander” chips that connect using the I2C or SPI serial buses.Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOSfirmware knowing how they’re used).

The exact capabilities of GPIOs vary between systems. Common options:

  • Output values are writable (high=1, low=0). Some chips also haveoptions about how that value is driven, so that for example only onevalue might be driven, supporting “wire-OR” and similar schemes for theother value (notably, “open drain” signaling).
  • Input values are likewise readable (1, 0). Some chips support readbackof pins configured as “output”, which is very useful in such “wire-OR”cases (to support bidirectional signaling). GPIO controllers may haveinput de-glitch/debounce logic, sometimes with software controls.
  • Inputs can often be used as IRQ signals, often edge triggered butsometimes level triggered. Such IRQs may be configurable as systemwakeup events, to wake the system from a low power state.
  • Usually a GPIO will be configurable as either input or output, as neededby different product boards; single direction ones exist too.
  • Most GPIOs can be accessed while holding spinlocks, but those accessedthrough a serial bus normally can’t. Some systems support both types.

On a given board each GPIO is used for one specific purpose like monitoringMMC/SD card insertion/removal, detecting card write-protect status, drivinga LED, configuring a transceiver, bit-banging a serial bus, poking a hardwarewatchdog, sensing a switch, and so on.

Common GPIO Properties

These properties are met through all the other documents of the GPIO interfaceand it is useful to understand them, especially if you need to define GPIOmappings.

Active-High and Active-Low

It is natural to assume that a GPIO is “active” when its output signal is 1(“high”), and inactive when it is 0 (“low”). However in practice the signal of aGPIO may be inverted before is reaches its destination, or a device could decideto have different conventions about what “active” means. Such decisions shouldbe transparent to device drivers, therefore it is possible to define a GPIO asbeing either active-high (“1” means “active”, the default) or active-low (“0”means “active”) so that drivers only need to worry about the logical signal andnot about what happens at the line level.

Open Drain and Open Source

Sometimes shared signals need to use “open drain” (where only the low signallevel is actually driven), or “open source” (where only the high signal level isdriven) signaling. That term applies to CMOS transistors; “open collector” isused for TTL. A pullup or pulldown resistor causes the high or low signal level.This is sometimes called a “wire-AND”; or more practically, from the negativelogic (low=true) perspective this is a “wire-OR”.

One common example of an open drain signal is a shared active-low IRQ line.Also, bidirectional data bus signals sometimes use open drain signals.

Some GPIO controllers directly support open drain and open source outputs; manydon’t. When you need open drain signaling but your hardware doesn’t directlysupport it, there’s a common idiom you can use to emulate it with any GPIO pinthat can be used as either an input or an output:

LOW: gpiod_direction_output(gpio, 0) … this drives the signal and overrides
the pullup.
HIGH: gpiod_direction_input(gpio) … this turns off the output, so the pullup
(or some other device) controls the signal.

The same logic can be applied to emulate open source signaling, by driving thehigh signal and configuring the GPIO as input for low. This open drain/opensource emulation can be handled transparently by the GPIO framework.

If you are “driving” the signal high but gpiod_get_value(gpio) reports a lowvalue (after the appropriate rise time passes), you know some other component isdriving the shared signal low. That’s not necessarily an error. As one commonexample, that’s how I2C clocks are stretched: a slave that needs a slower clockdelays the rising edge of SCK, and the I2C master adjusts its signaling rateaccordingly.