Documentation/driver-api/gpio/intro.rst

   1 ============
   2 Introduction
   3 ============
   4
   5
   6 GPIO Interfaces
   7 ===============
   8
   9 The documents in this directory give detailed instructions on how to access
  10 GPIOs in drivers, and how to write a driver for a device that provides GPIOs
  11 itself.
  12
  13
  14 What is a GPIO?
  15 ===============
  16
  17 A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
  18 digital signal. They are provided from many kinds of chips, and are familiar
  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
  21 (BGA) packages. Board schematics show which external hardware connects to
  22 which GPIOs. Drivers can be written generically, so that board setup code
  23 passes such pin configuration data to drivers.
  24
  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
  27 several dozen of them. Programmable logic devices (like FPGAs) can easily
  28 provide GPIOs; multifunction chips like power managers, and audio codecs
  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
  32 firmware knowing how they're used).
  33
  34 The 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
  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.
  60
  61
  62 Common GPIO Properties
  63 ======================
  64
  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
  67 mappings.
  68
  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
  74 to have different conventions about what "active" means. Such decisions should
  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"
  77 means "active") so that drivers only need to worry about the logical signal and
  78 not about what happens at the line level.
  79
  80 Open Drain and Open Source
  81 --------------------------
  82 Sometimes shared signals need to use "open drain" (where only the low signal
  83 level is actually driven), or "open source" (where only the high signal level is
  84 driven) signaling. That term applies to CMOS transistors; "open collector" is
  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".
  88
  89 One common example of an open drain signal is a shared active-low IRQ line.
  90 Also, bidirectional data bus signals sometimes use open drain signals.
  91
  92 Some GPIO controllers directly support open drain and open source outputs; many
  93 don't. When you need open drain signaling but your hardware doesn't directly
  94 support it, there's a common idiom you can use to emulate it with any GPIO pin
  95 that 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
 103 The same logic can be applied to emulate open source signaling, by driving the
 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.
 106
 107 If you are "driving" the signal high but gpiod_get_value(gpio) reports a low
 108 value (after the appropriate rise time passes), you know some other component is
 109 driving the shared signal low. That's not necessarily an error. As one common
 110 example, that's how I2C clocks are stretched:  a slave that needs a slower clock
 111 delays the rising edge of SCK, and the I2C master adjusts its signaling rate
 112 accordingly.