blob: 989f1130f4f33e6960459b971b41862b10713a2d [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);
David Brownell28735a72007-03-16 13:38:14 -0800108 int gpio_direction_output(unsigned gpio, int value);
David Brownell4c203862007-02-12 00:53:11 -0800109
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
David Brownell28735a72007-03-16 13:38:14 -0800114For output GPIOs, the value provided becomes the initial output value.
115This helps avoid signal glitching during system startup.
116
David Brownell4c203862007-02-12 00:53:11 -0800117Setting the direction can fail if the GPIO number is invalid, or when
118that particular GPIO can't be used in that mode. It's generally a bad
119idea to rely on boot firmware to have set the direction correctly, since
120it probably wasn't validated to do more than boot Linux. (Similarly,
121that board setup code probably needs to multiplex that pin as a GPIO,
122and configure pullups/pulldowns appropriately.)
123
124
125Spinlock-Safe GPIO access
126-------------------------
127Most GPIO controllers can be accessed with memory read/write instructions.
128That doesn't need to sleep, and can safely be done from inside IRQ handlers.
129
130Use these calls to access such GPIOs:
131
132 /* GPIO INPUT: return zero or nonzero */
133 int gpio_get_value(unsigned gpio);
134
135 /* GPIO OUTPUT */
136 void gpio_set_value(unsigned gpio, int value);
137
138The values are boolean, zero for low, nonzero for high. When reading the
139value of an output pin, the value returned should be what's seen on the
140pin ... that won't always match the specified output value, because of
141issues including wire-OR and output latencies.
142
143The get/set calls have no error returns because "invalid GPIO" should have
144been reported earlier in gpio_set_direction(). However, note that not all
145platforms can read the value of output pins; those that can't should always
David Brownellf5de6112007-02-16 01:27:14 -0800146return zero. Also, using these calls for GPIOs that can't safely be accessed
147without sleeping (see below) is an error.
David Brownell4c203862007-02-12 00:53:11 -0800148
David Brownellf5de6112007-02-16 01:27:14 -0800149Platform-specific implementations are encouraged to optimize the two
David Brownell4c203862007-02-12 00:53:11 -0800150calls to access the GPIO value in cases where the GPIO number (and for
151output, value) are constant. It's normal for them to need only a couple
152of instructions in such cases (reading or writing a hardware register),
153and not to need spinlocks. Such optimized calls can make bitbanging
154applications a lot more efficient (in both space and time) than spending
155dozens of instructions on subroutine calls.
156
157
158GPIO access that may sleep
159--------------------------
160Some GPIO controllers must be accessed using message based busses like I2C
161or SPI. Commands to read or write those GPIO values require waiting to
162get to the head of a queue to transmit a command and get its response.
163This requires sleeping, which can't be done from inside IRQ handlers.
164
165Platforms that support this type of GPIO distinguish them from other GPIOs
166by returning nonzero from this call:
167
168 int gpio_cansleep(unsigned gpio);
169
170To access such GPIOs, a different set of accessors is defined:
171
172 /* GPIO INPUT: return zero or nonzero, might sleep */
173 int gpio_get_value_cansleep(unsigned gpio);
174
175 /* GPIO OUTPUT, might sleep */
176 void gpio_set_value_cansleep(unsigned gpio, int value);
177
178Other than the fact that these calls might sleep, and will not be ignored
179for GPIOs that can't be accessed from IRQ handlers, these calls act the
180same as the spinlock-safe calls.
181
182
183Claiming and Releasing GPIOs (OPTIONAL)
184---------------------------------------
185To help catch system configuration errors, two calls are defined.
186However, many platforms don't currently support this mechanism.
187
188 /* request GPIO, returning 0 or negative errno.
189 * non-null labels may be useful for diagnostics.
190 */
191 int gpio_request(unsigned gpio, const char *label);
192
193 /* release previously-claimed GPIO */
194 void gpio_free(unsigned gpio);
195
196Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
197GPIOs that have already been claimed with that call. The return value of
198gpio_request() must be checked. (These calls could sleep.)
199
200These calls serve two basic purposes. One is marking the signals which
201are actually in use as GPIOs, for better diagnostics; systems may have
202several hundred potential GPIOs, but often only a dozen are used on any
203given board. Another is to catch conflicts between drivers, reporting
204errors when drivers wrongly think they have exclusive use of that signal.
205
206These two calls are optional because not not all current Linux platforms
207offer such functionality in their GPIO support; a valid implementation
208could return success for all gpio_request() calls. Unlike the other calls,
209the state they represent doesn't normally match anything from a hardware
210register; it's just a software bitmap which clearly is not necessary for
211correct operation of hardware or (bug free) drivers.
212
213Note that requesting a GPIO does NOT cause it to be configured in any
214way; it just marks that GPIO as in use. Separate code must handle any
215pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown).
216
217
218GPIOs mapped to IRQs
219--------------------
220GPIO numbers are unsigned integers; so are IRQ numbers. These make up
221two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can
222map between them using calls like:
223
224 /* map GPIO numbers to IRQ numbers */
225 int gpio_to_irq(unsigned gpio);
226
227 /* map IRQ numbers to GPIO numbers */
228 int irq_to_gpio(unsigned irq);
229
230Those return either the corresponding number in the other namespace, or
231else a negative errno code if the mapping can't be done. (For example,
232some GPIOs can't used as IRQs.) It is an unchecked error to use a GPIO
233number that hasn't been marked as an input using gpio_set_direction(), or
234to use an IRQ number that didn't originally come from gpio_to_irq().
235
236These two mapping calls are expected to cost on the order of a single
237addition or subtraction. They're not allowed to sleep.
238
239Non-error values returned from gpio_to_irq() can be passed to request_irq()
240or free_irq(). They will often be stored into IRQ resources for platform
241devices, by the board-specific initialization code. Note that IRQ trigger
242options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are
243system wakeup capabilities.
244
245Non-error values returned from irq_to_gpio() would most commonly be used
David Brownellf5de6112007-02-16 01:27:14 -0800246with gpio_get_value(), for example to initialize or update driver state
247when the IRQ is edge-triggered.
David Brownell4c203862007-02-12 00:53:11 -0800248
249
250
251What do these conventions omit?
252===============================
253One of the biggest things these conventions omit is pin multiplexing, since
254this is highly chip-specific and nonportable. One platform might not need
255explicit multiplexing; another might have just two options for use of any
256given pin; another might have eight options per pin; another might be able
257to route a given GPIO to any one of several pins. (Yes, those examples all
258come from systems that run Linux today.)
259
260Related to multiplexing is configuration and enabling of the pullups or
261pulldowns integrated on some platforms. Not all platforms support them,
262or support them in the same way; and any given board might use external
263pullups (or pulldowns) so that the on-chip ones should not be used.
264
265There are other system-specific mechanisms that are not specified here,
266like the aforementioned options for input de-glitching and wire-OR output.
267Hardware may support reading or writing GPIOs in gangs, but that's usually
David Brownellf5de6112007-02-16 01:27:14 -0800268configuration dependent: for GPIOs sharing the same bank. (GPIOs are
David Brownell4c203862007-02-12 00:53:11 -0800269commonly grouped in banks of 16 or 32, with a given SOC having several such
David Brownellf5de6112007-02-16 01:27:14 -0800270banks.) Some systems can trigger IRQs from output GPIOs. Code relying on
271such mechanisms will necessarily be nonportable.
David Brownell4c203862007-02-12 00:53:11 -0800272
273Dynamic definition of GPIOs is not currently supported; for example, as
274a side effect of configuring an add-on board with some GPIO expanders.
275
276These calls are purely for kernel space, but a userspace API could be built
277on top of it.