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