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