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