gpio: gpio.txt

File gpio.txt, 6.1 KB (added by Cale Collins, 4 months ago)

GPIO.txt

Line 
11       GPIO Interfaces
22       ===============
33       
44       The documents in this directory give detailed instructions on how to access
55       GPIOs in drivers, and how to write a driver for a device that provides GPIOs
66       itself.
77       
88       Due to the history of GPIO interfaces in the kernel, there are two different
99       ways to obtain and use GPIOs:
1010     
1111        - The descriptor-based interface is the preferred way to manipulate GPIOs,
1212      and is described by all the files in this directory excepted gpio-legacy.txt.
1313        - The legacy integer-based interface which is considered deprecated (but still
1414      usable for compatibility reasons) is documented in gpio-legacy.txt.
1515     
1616      The remainder of this document applies to the new descriptor-based interface.
1717      gpio-legacy.txt contains the same information applied to the legacy
1818      integer-based interface.
1919     
2020     
2121      What is a GPIO?
2222      ===============
2323     
2424      A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
2525      digital signal. They are provided from many kinds of chip, and are familiar
2626      to Linux developers working with embedded and custom hardware. Each GPIO
2727      represents a bit connected to a particular pin, or "ball" on Ball Grid Array
2828      (BGA) packages. Board schematics show which external hardware connects to
2929      which GPIOs. Drivers can be written generically, so that board setup code
3030      passes such pin configuration data to drivers.
3131     
3232      System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
3333      non-dedicated pin can be configured as a GPIO; and most chips have at least
3434      several dozen of them. Programmable logic devices (like FPGAs) can easily
3535      provide GPIOs; multifunction chips like power managers, and audio codecs
3636      often have a few such pins to help with pin scarcity on SOCs; and there are
3737      also "GPIO Expander" chips that connect using the I2C or SPI serial buses.
3838      Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
3939      firmware knowing how they're used).
4040     
4141      The exact capabilities of GPIOs vary between systems. Common options:
4242     
4343        - Output values are writable (high=1, low=0). Some chips also have
4444          options about how that value is driven, so that for example only one
4545          value might be driven, supporting "wire-OR" and similar schemes for the
4646          other value (notably, "open drain" signaling).
4747     
4848        - Input values are likewise readable (1, 0). Some chips support readback
4949          of pins configured as "output", which is very useful in such "wire-OR"
5050          cases (to support bidirectional signaling). GPIO controllers may have
5151          input de-glitch/debounce logic, sometimes with software controls.
5252     
5353        - Inputs can often be used as IRQ signals, often edge triggered but
5454          sometimes level triggered. Such IRQs may be configurable as system
5555          wakeup events, to wake the system from a low power state.
5656     
5757        - Usually a GPIO will be configurable as either input or output, as needed
5858          by different product boards; single direction ones exist too.
5959     
6060        - Most GPIOs can be accessed while holding spinlocks, but those accessed
6161          through a serial bus normally can't. Some systems support both types.
6262     
6363      On a given board each GPIO is used for one specific purpose like monitoring
6464      MMC/SD card insertion/removal, detecting card write-protect status, driving
6565      a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware
6666      watchdog, sensing a switch, and so on.
6767     
6868     
6969      Common GPIO Properties
7070      ======================
7171     
7272      These properties are met through all the other documents of the GPIO interface
7373      and it is useful to understand them, especially if you need to define GPIO
7474      mappings.
7575     
7676      Active-High and Active-Low
7777      --------------------------
7878      It is natural to assume that a GPIO is "active" when its output signal is 1
7979      ("high"), and inactive when it is 0 ("low"). However in practice the signal of a
8080      GPIO may be inverted before is reaches its destination, or a device could decide
8181      to have different conventions about what "active" means. Such decisions should
8282      be transparent to device drivers, therefore it is possible to define a GPIO as
8383      being either active-high ("1" means "active", the default) or active-low ("0"
8484      means "active") so that drivers only need to worry about the logical signal and
8585      not about what happens at the line level.
8686     
8787      Open Drain and Open Source
8888      --------------------------
8989      Sometimes shared signals need to use "open drain" (where only the low signal
9090      level is actually driven), or "open source" (where only the high signal level is
9191      driven) signaling. That term applies to CMOS transistors; "open collector" is
9292      used for TTL. A pullup or pulldown resistor causes the high or low signal level.
9393      This is sometimes called a "wire-AND"; or more practically, from the negative
9494      logic (low=true) perspective this is a "wire-OR".
9595     
9696      One common example of an open drain signal is a shared active-low IRQ line.
9797      Also, bidirectional data bus signals sometimes use open drain signals.
9898     
9999      Some GPIO controllers directly support open drain and open source outputs; many
100100     don't. When you need open drain signaling but your hardware doesn't directly
101101     support it, there's a common idiom you can use to emulate it with any GPIO pin
102102     that can be used as either an input or an output:
103103     
104104      LOW:   gpiod_direction_output(gpio, 0) ... this drives the signal and overrides
105105             the pullup.
106106     
107107      HIGH:  gpiod_direction_input(gpio) ... this turns off the output, so the pullup
108108             (or some other device) controls the signal.
109109     
110110     The same logic can be applied to emulate open source signaling, by driving the
111111     high signal and configuring the GPIO as input for low. This open drain/open
112112     source emulation can be handled transparently by the GPIO framework.
113113     
114114     If you are "driving" the signal high but gpiod_get_value(gpio) reports a low
115115     value (after the appropriate rise time passes), you know some other component is
116116     driving the shared signal low. That's not necessarily an error. As one common
117117     example, that's how I2C clocks are stretched:  a slave that needs a slower clock
118118     delays the rising edge of SCK, and the I2C master adjusts its signaling rate
119119     accordingly.