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