diff options
Diffstat (limited to 'Documentation/gpio.txt')
-rw-r--r-- | Documentation/gpio.txt | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt new file mode 100644 index 000000000000..09dd510c4a5f --- /dev/null +++ b/Documentation/gpio.txt | |||
@@ -0,0 +1,271 @@ | |||
1 | GPIO Interfaces | ||
2 | |||
3 | This provides an overview of GPIO access conventions on Linux. | ||
4 | |||
5 | |||
6 | What is a GPIO? | ||
7 | =============== | ||
8 | A "General Purpose Input/Output" (GPIO) is a flexible software-controlled | ||
9 | digital signal. They are provided from many kinds of chip, and are familiar | ||
10 | to Linux developers working with embedded and custom hardware. Each GPIO | ||
11 | represents a bit connected to a particular pin, or "ball" on Ball Grid Array | ||
12 | (BGA) packages. Board schematics show which external hardware connects to | ||
13 | which GPIOs. Drivers can be written generically, so that board setup code | ||
14 | passes such pin configuration data to drivers. | ||
15 | |||
16 | System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every | ||
17 | non-dedicated pin can be configured as a GPIO; and most chips have at least | ||
18 | several dozen of them. Programmable logic devices (like FPGAs) can easily | ||
19 | provide GPIOs; multifunction chips like power managers, and audio codecs | ||
20 | often have a few such pins to help with pin scarcity on SOCs; and there are | ||
21 | also "GPIO Expander" chips that connect using the I2C or SPI serial busses. | ||
22 | Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS | ||
23 | firmware knowing how they're used). | ||
24 | |||
25 | The exact capabilities of GPIOs vary between systems. Common options: | ||
26 | |||
27 | - Output values are writable (high=1, low=0). Some chips also have | ||
28 | options about how that value is driven, so that for example only one | ||
29 | value might be driven ... supporting "wire-OR" and similar schemes | ||
30 | for the other value. | ||
31 | |||
32 | - Input values are likewise readable (1, 0). Some chips support readback | ||
33 | of pins configured as "output", which is very useful in such "wire-OR" | ||
34 | cases (to support bidirectional signaling). GPIO controllers may have | ||
35 | input de-glitch logic, sometimes with software controls. | ||
36 | |||
37 | - Inputs can often be used as IRQ signals, often edge triggered but | ||
38 | sometimes level triggered. Such IRQs may be configurable as system | ||
39 | wakeup events, to wake the system from a low power state. | ||
40 | |||
41 | - Usually a GPIO will be configurable as either input or output, as needed | ||
42 | by different product boards; single direction ones exist too. | ||
43 | |||
44 | - Most GPIOs can be accessed while holding spinlocks, but those accessed | ||
45 | through a serial bus normally can't. Some systems support both types. | ||
46 | |||
47 | On a given board each GPIO is used for one specific purpose like monitoring | ||
48 | MMC/SD card insertion/removal, detecting card writeprotect status, driving | ||
49 | a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware | ||
50 | watchdog, sensing a switch, and so on. | ||
51 | |||
52 | |||
53 | GPIO conventions | ||
54 | ================ | ||
55 | Note that this is called a "convention" because you don't need to do it this | ||
56 | way, and it's no crime if you don't. There **are** cases where portability | ||
57 | is not the main issue; GPIOs are often used for the kind of board-specific | ||
58 | glue logic that may even change between board revisions, and can't ever be | ||
59 | used on a board that's wired differently. Only least-common-denominator | ||
60 | functionality can be very portable. Other features are platform-specific, | ||
61 | and that can be critical for glue logic. | ||
62 | |||
63 | Plus, this doesn't define an implementation framework, just an interface. | ||
64 | One platform might implement it as simple inline functions accessing chip | ||
65 | registers; another might implement it by delegating through abstractions | ||
66 | used for several very different kinds of GPIO controller. | ||
67 | |||
68 | That said, if the convention is supported on their platform, drivers should | ||
69 | use it when possible: | ||
70 | |||
71 | #include <asm/gpio.h> | ||
72 | |||
73 | If you stick to this convention then it'll be easier for other developers to | ||
74 | see what your code is doing, and help maintain it. | ||
75 | |||
76 | |||
77 | Identifying GPIOs | ||
78 | ----------------- | ||
79 | GPIOs are identified by unsigned integers in the range 0..MAX_INT. That | ||
80 | reserves "negative" numbers for other purposes like marking signals as | ||
81 | "not available on this board", or indicating faults. | ||
82 | |||
83 | Platforms define how they use those integers, and usually #define symbols | ||
84 | for the GPIO lines so that board-specific setup code directly corresponds | ||
85 | to the relevant schematics. In contrast, drivers should only use GPIO | ||
86 | numbers passed to them from that setup code, using platform_data to hold | ||
87 | board-specific pin configuration data (along with other board specific | ||
88 | data they need). That avoids portability problems. | ||
89 | |||
90 | So for example one platform uses numbers 32-159 for GPIOs; while another | ||
91 | uses numbers 0..63 with one set of GPIO controllers, 64-79 with another | ||
92 | type of GPIO controller, and on one particular board 80-95 with an FPGA. | ||
93 | The numbers need not be contiguous; either of those platforms could also | ||
94 | use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders. | ||
95 | |||
96 | Whether a platform supports multiple GPIO controllers is currently a | ||
97 | platform-specific implementation issue. | ||
98 | |||
99 | |||
100 | Using GPIOs | ||
101 | ----------- | ||
102 | One of the first things to do with a GPIO, often in board setup code when | ||
103 | setting up a platform_device using the GPIO, is mark its direction: | ||
104 | |||
105 | /* set as input or output, returning 0 or negative errno */ | ||
106 | int gpio_direction_input(unsigned gpio); | ||
107 | int gpio_direction_output(unsigned gpio); | ||
108 | |||
109 | The return value is zero for success, else a negative errno. It should | ||
110 | be checked, since the get/set calls don't have error returns and since | ||
111 | misconfiguration is possible. (These calls could sleep.) | ||
112 | |||
113 | Setting the direction can fail if the GPIO number is invalid, or when | ||
114 | that particular GPIO can't be used in that mode. It's generally a bad | ||
115 | idea to rely on boot firmware to have set the direction correctly, since | ||
116 | it probably wasn't validated to do more than boot Linux. (Similarly, | ||
117 | that board setup code probably needs to multiplex that pin as a GPIO, | ||
118 | and configure pullups/pulldowns appropriately.) | ||
119 | |||
120 | |||
121 | Spinlock-Safe GPIO access | ||
122 | ------------------------- | ||
123 | Most GPIO controllers can be accessed with memory read/write instructions. | ||
124 | That doesn't need to sleep, and can safely be done from inside IRQ handlers. | ||
125 | |||
126 | Use these calls to access such GPIOs: | ||
127 | |||
128 | /* GPIO INPUT: return zero or nonzero */ | ||
129 | int gpio_get_value(unsigned gpio); | ||
130 | |||
131 | /* GPIO OUTPUT */ | ||
132 | void gpio_set_value(unsigned gpio, int value); | ||
133 | |||
134 | The values are boolean, zero for low, nonzero for high. When reading the | ||
135 | value of an output pin, the value returned should be what's seen on the | ||
136 | pin ... that won't always match the specified output value, because of | ||
137 | issues including wire-OR and output latencies. | ||
138 | |||
139 | The get/set calls have no error returns because "invalid GPIO" should have | ||
140 | been reported earlier in gpio_set_direction(). However, note that not all | ||
141 | platforms can read the value of output pins; those that can't should always | ||
142 | return zero. Also, these calls will be ignored for GPIOs that can't safely | ||
143 | be accessed wihtout sleeping (see below). | ||
144 | |||
145 | Platform-specific implementations are encouraged to optimise the two | ||
146 | calls to access the GPIO value in cases where the GPIO number (and for | ||
147 | output, value) are constant. It's normal for them to need only a couple | ||
148 | of instructions in such cases (reading or writing a hardware register), | ||
149 | and not to need spinlocks. Such optimized calls can make bitbanging | ||
150 | applications a lot more efficient (in both space and time) than spending | ||
151 | dozens of instructions on subroutine calls. | ||
152 | |||
153 | |||
154 | GPIO access that may sleep | ||
155 | -------------------------- | ||
156 | Some GPIO controllers must be accessed using message based busses like I2C | ||
157 | or SPI. Commands to read or write those GPIO values require waiting to | ||
158 | get to the head of a queue to transmit a command and get its response. | ||
159 | This requires sleeping, which can't be done from inside IRQ handlers. | ||
160 | |||
161 | Platforms that support this type of GPIO distinguish them from other GPIOs | ||
162 | by returning nonzero from this call: | ||
163 | |||
164 | int gpio_cansleep(unsigned gpio); | ||
165 | |||
166 | To access such GPIOs, a different set of accessors is defined: | ||
167 | |||
168 | /* GPIO INPUT: return zero or nonzero, might sleep */ | ||
169 | int gpio_get_value_cansleep(unsigned gpio); | ||
170 | |||
171 | /* GPIO OUTPUT, might sleep */ | ||
172 | void gpio_set_value_cansleep(unsigned gpio, int value); | ||
173 | |||
174 | Other than the fact that these calls might sleep, and will not be ignored | ||
175 | for GPIOs that can't be accessed from IRQ handlers, these calls act the | ||
176 | same as the spinlock-safe calls. | ||
177 | |||
178 | |||
179 | Claiming and Releasing GPIOs (OPTIONAL) | ||
180 | --------------------------------------- | ||
181 | To help catch system configuration errors, two calls are defined. | ||
182 | However, many platforms don't currently support this mechanism. | ||
183 | |||
184 | /* request GPIO, returning 0 or negative errno. | ||
185 | * non-null labels may be useful for diagnostics. | ||
186 | */ | ||
187 | int gpio_request(unsigned gpio, const char *label); | ||
188 | |||
189 | /* release previously-claimed GPIO */ | ||
190 | void gpio_free(unsigned gpio); | ||
191 | |||
192 | Passing invalid GPIO numbers to gpio_request() will fail, as will requesting | ||
193 | GPIOs that have already been claimed with that call. The return value of | ||
194 | gpio_request() must be checked. (These calls could sleep.) | ||
195 | |||
196 | These calls serve two basic purposes. One is marking the signals which | ||
197 | are actually in use as GPIOs, for better diagnostics; systems may have | ||
198 | several hundred potential GPIOs, but often only a dozen are used on any | ||
199 | given board. Another is to catch conflicts between drivers, reporting | ||
200 | errors when drivers wrongly think they have exclusive use of that signal. | ||
201 | |||
202 | These two calls are optional because not not all current Linux platforms | ||
203 | offer such functionality in their GPIO support; a valid implementation | ||
204 | could return success for all gpio_request() calls. Unlike the other calls, | ||
205 | the state they represent doesn't normally match anything from a hardware | ||
206 | register; it's just a software bitmap which clearly is not necessary for | ||
207 | correct operation of hardware or (bug free) drivers. | ||
208 | |||
209 | Note that requesting a GPIO does NOT cause it to be configured in any | ||
210 | way; it just marks that GPIO as in use. Separate code must handle any | ||
211 | pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown). | ||
212 | |||
213 | |||
214 | GPIOs mapped to IRQs | ||
215 | -------------------- | ||
216 | GPIO numbers are unsigned integers; so are IRQ numbers. These make up | ||
217 | two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can | ||
218 | map between them using calls like: | ||
219 | |||
220 | /* map GPIO numbers to IRQ numbers */ | ||
221 | int gpio_to_irq(unsigned gpio); | ||
222 | |||
223 | /* map IRQ numbers to GPIO numbers */ | ||
224 | int irq_to_gpio(unsigned irq); | ||
225 | |||
226 | Those return either the corresponding number in the other namespace, or | ||
227 | else a negative errno code if the mapping can't be done. (For example, | ||
228 | some GPIOs can't used as IRQs.) It is an unchecked error to use a GPIO | ||
229 | number that hasn't been marked as an input using gpio_set_direction(), or | ||
230 | to use an IRQ number that didn't originally come from gpio_to_irq(). | ||
231 | |||
232 | These two mapping calls are expected to cost on the order of a single | ||
233 | addition or subtraction. They're not allowed to sleep. | ||
234 | |||
235 | Non-error values returned from gpio_to_irq() can be passed to request_irq() | ||
236 | or free_irq(). They will often be stored into IRQ resources for platform | ||
237 | devices, by the board-specific initialization code. Note that IRQ trigger | ||
238 | options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are | ||
239 | system wakeup capabilities. | ||
240 | |||
241 | Non-error values returned from irq_to_gpio() would most commonly be used | ||
242 | with gpio_get_value(). | ||
243 | |||
244 | |||
245 | |||
246 | What do these conventions omit? | ||
247 | =============================== | ||
248 | One of the biggest things these conventions omit is pin multiplexing, since | ||
249 | this is highly chip-specific and nonportable. One platform might not need | ||
250 | explicit multiplexing; another might have just two options for use of any | ||
251 | given pin; another might have eight options per pin; another might be able | ||
252 | to route a given GPIO to any one of several pins. (Yes, those examples all | ||
253 | come from systems that run Linux today.) | ||
254 | |||
255 | Related to multiplexing is configuration and enabling of the pullups or | ||
256 | pulldowns integrated on some platforms. Not all platforms support them, | ||
257 | or support them in the same way; and any given board might use external | ||
258 | pullups (or pulldowns) so that the on-chip ones should not be used. | ||
259 | |||
260 | There are other system-specific mechanisms that are not specified here, | ||
261 | like the aforementioned options for input de-glitching and wire-OR output. | ||
262 | Hardware may support reading or writing GPIOs in gangs, but that's usually | ||
263 | configuration dependednt: for GPIOs sharing the same bank. (GPIOs are | ||
264 | commonly grouped in banks of 16 or 32, with a given SOC having several such | ||
265 | banks.) Code relying on such mechanisms will necessarily be nonportable. | ||
266 | |||
267 | Dynamic definition of GPIOs is not currently supported; for example, as | ||
268 | a side effect of configuring an add-on board with some GPIO expanders. | ||
269 | |||
270 | These calls are purely for kernel space, but a userspace API could be built | ||
271 | on top of it. | ||