Loading...
1======================
2Legacy GPIO Interfaces
3======================
4
5This provides an overview of GPIO access conventions on Linux.
6
7These calls use the gpio_* naming prefix. No other calls should use that
8prefix, or the related __gpio_* prefix.
9
10
11What is a GPIO?
12===============
13A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
14digital signal. They are provided from many kinds of chip, and are familiar
15to Linux developers working with embedded and custom hardware. Each GPIO
16represents a bit connected to a particular pin, or "ball" on Ball Grid Array
17(BGA) packages. Board schematics show which external hardware connects to
18which GPIOs. Drivers can be written generically, so that board setup code
19passes such pin configuration data to drivers.
20
21System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
22non-dedicated pin can be configured as a GPIO; and most chips have at least
23several dozen of them. Programmable logic devices (like FPGAs) can easily
24provide GPIOs; multifunction chips like power managers, and audio codecs
25often have a few such pins to help with pin scarcity on SOCs; and there are
26also "GPIO Expander" chips that connect using the I2C or SPI serial busses.
27Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
28firmware knowing how they're used).
29
30The exact capabilities of GPIOs vary between systems. Common options:
31
32 - Output values are writable (high=1, low=0). Some chips also have
33 options about how that value is driven, so that for example only one
34 value might be driven ... supporting "wire-OR" and similar schemes
35 for the other value (notably, "open drain" signaling).
36
37 - Input values are likewise readable (1, 0). Some chips support readback
38 of pins configured as "output", which is very useful in such "wire-OR"
39 cases (to support bidirectional signaling). GPIO controllers may have
40 input de-glitch/debounce logic, sometimes with software controls.
41
42 - Inputs can often be used as IRQ signals, often edge triggered but
43 sometimes level triggered. Such IRQs may be configurable as system
44 wakeup events, to wake the system from a low power state.
45
46 - Usually a GPIO will be configurable as either input or output, as needed
47 by different product boards; single direction ones exist too.
48
49 - Most GPIOs can be accessed while holding spinlocks, but those accessed
50 through a serial bus normally can't. Some systems support both types.
51
52On a given board each GPIO is used for one specific purpose like monitoring
53MMC/SD card insertion/removal, detecting card writeprotect status, driving
54a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware
55watchdog, sensing a switch, and so on.
56
57
58GPIO conventions
59================
60Note that this is called a "convention" because you don't need to do it this
61way, and it's no crime if you don't. There **are** cases where portability
62is not the main issue; GPIOs are often used for the kind of board-specific
63glue logic that may even change between board revisions, and can't ever be
64used on a board that's wired differently. Only least-common-denominator
65functionality can be very portable. Other features are platform-specific,
66and that can be critical for glue logic.
67
68Plus, this doesn't require any implementation framework, just an interface.
69One platform might implement it as simple inline functions accessing chip
70registers; another might implement it by delegating through abstractions
71used for several very different kinds of GPIO controller. (There is some
72optional code supporting such an implementation strategy, described later
73in this document, but drivers acting as clients to the GPIO interface must
74not care how it's implemented.)
75
76That said, if the convention is supported on their platform, drivers should
77use it when possible. Platforms must select GPIOLIB if GPIO functionality
78is strictly required. Drivers that can't work without
79standard GPIO calls should have Kconfig entries which depend on GPIOLIB. The
80GPIO calls are available, either as "real code" or as optimized-away stubs,
81when drivers use the include file:
82
83 #include <linux/gpio.h>
84
85If you stick to this convention then it'll be easier for other developers to
86see what your code is doing, and help maintain it.
87
88Note that these operations include I/O barriers on platforms which need to
89use them; drivers don't need to add them explicitly.
90
91
92Identifying GPIOs
93-----------------
94GPIOs are identified by unsigned integers in the range 0..MAX_INT. That
95reserves "negative" numbers for other purposes like marking signals as
96"not available on this board", or indicating faults. Code that doesn't
97touch the underlying hardware treats these integers as opaque cookies.
98
99Platforms define how they use those integers, and usually #define symbols
100for the GPIO lines so that board-specific setup code directly corresponds
101to the relevant schematics. In contrast, drivers should only use GPIO
102numbers passed to them from that setup code, using platform_data to hold
103board-specific pin configuration data (along with other board specific
104data they need). That avoids portability problems.
105
106So for example one platform uses numbers 32-159 for GPIOs; while another
107uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
108type of GPIO controller, and on one particular board 80-95 with an FPGA.
109The numbers need not be contiguous; either of those platforms could also
110use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.
111
112If you want to initialize a structure with an invalid GPIO number, use
113some negative number (perhaps "-EINVAL"); that will never be valid. To
114test if such number from such a structure could reference a GPIO, you
115may use this predicate:
116
117 int gpio_is_valid(int number);
118
119A number that's not valid will be rejected by calls which may request
120or free GPIOs (see below). Other numbers may also be rejected; for
121example, a number might be valid but temporarily unused on a given board.
122
123Whether a platform supports multiple GPIO controllers is a platform-specific
124implementation issue, as are whether that support can leave "holes" in the space
125of GPIO numbers, and whether new controllers can be added at runtime. Such issues
126can affect things including whether adjacent GPIO numbers are both valid.
127
128Using GPIOs
129-----------
130The first thing a system should do with a GPIO is allocate it, using
131the gpio_request() call; see later.
132
133One of the next things to do with a GPIO, often in board setup code when
134setting up a platform_device using the GPIO, is mark its direction::
135
136 /* set as input or output, returning 0 or negative errno */
137 int gpio_direction_input(unsigned gpio);
138 int gpio_direction_output(unsigned gpio, int value);
139
140The return value is zero for success, else a negative errno. It should
141be checked, since the get/set calls don't have error returns and since
142misconfiguration is possible. You should normally issue these calls from
143a task context. However, for spinlock-safe GPIOs it's OK to use them
144before tasking is enabled, as part of early board setup.
145
146For output GPIOs, the value provided becomes the initial output value.
147This helps avoid signal glitching during system startup.
148
149For compatibility with legacy interfaces to GPIOs, setting the direction
150of a GPIO implicitly requests that GPIO (see below) if it has not been
151requested already. That compatibility is being removed from the optional
152gpiolib framework.
153
154Setting the direction can fail if the GPIO number is invalid, or when
155that particular GPIO can't be used in that mode. It's generally a bad
156idea to rely on boot firmware to have set the direction correctly, since
157it probably wasn't validated to do more than boot Linux. (Similarly,
158that board setup code probably needs to multiplex that pin as a GPIO,
159and configure pullups/pulldowns appropriately.)
160
161
162Spinlock-Safe GPIO access
163-------------------------
164Most GPIO controllers can be accessed with memory read/write instructions.
165Those don't need to sleep, and can safely be done from inside hard
166(nonthreaded) IRQ handlers and similar contexts.
167
168Use the following calls to access such GPIOs::
169
170 /* GPIO INPUT: return zero or nonzero */
171 int gpio_get_value(unsigned gpio);
172
173 /* GPIO OUTPUT */
174 void gpio_set_value(unsigned gpio, int value);
175
176The values are boolean, zero for low, nonzero for high. When reading the
177value of an output pin, the value returned should be what's seen on the
178pin ... that won't always match the specified output value, because of
179issues including open-drain signaling and output latencies.
180
181The get/set calls have no error returns because "invalid GPIO" should have
182been reported earlier from gpio_direction_*(). However, note that not all
183platforms can read the value of output pins; those that can't should always
184return zero. Also, using these calls for GPIOs that can't safely be accessed
185without sleeping (see below) is an error.
186
187Platform-specific implementations are encouraged to optimize the two
188calls to access the GPIO value in cases where the GPIO number (and for
189output, value) are constant. It's normal for them to need only a couple
190of instructions in such cases (reading or writing a hardware register),
191and not to need spinlocks. Such optimized calls can make bitbanging
192applications a lot more efficient (in both space and time) than spending
193dozens of instructions on subroutine calls.
194
195
196GPIO access that may sleep
197--------------------------
198Some GPIO controllers must be accessed using message based busses like I2C
199or SPI. Commands to read or write those GPIO values require waiting to
200get to the head of a queue to transmit a command and get its response.
201This requires sleeping, which can't be done from inside IRQ handlers.
202To access such GPIOs, a different set of accessors is defined::
203
204 /* GPIO INPUT: return zero or nonzero, might sleep */
205 int gpio_get_value_cansleep(unsigned gpio);
206
207 /* GPIO OUTPUT, might sleep */
208 void gpio_set_value_cansleep(unsigned gpio, int value);
209
210Accessing such GPIOs requires a context which may sleep, for example
211a threaded IRQ handler, and those accessors must be used instead of
212spinlock-safe accessors without the cansleep() name suffix.
213
214Other than the fact that these accessors might sleep, and will work
215on GPIOs that can't be accessed from hardIRQ handlers, these calls act
216the same as the spinlock-safe calls.
217
218**IN ADDITION** calls to setup and configure such GPIOs must be made
219from contexts which may sleep, since they may need to access the GPIO
220controller chip too (These setup calls are usually made from board
221setup or driver probe/teardown code, so this is an easy constraint.)::
222
223 gpio_direction_input()
224 gpio_direction_output()
225 gpio_request()
226
227 ## gpio_request_one()
228 ## gpio_request_array()
229 ## gpio_free_array()
230
231 gpio_free()
232
233
234Claiming and Releasing GPIOs
235----------------------------
236To help catch system configuration errors, two calls are defined::
237
238 /* request GPIO, returning 0 or negative errno.
239 * non-null labels may be useful for diagnostics.
240 */
241 int gpio_request(unsigned gpio, const char *label);
242
243 /* release previously-claimed GPIO */
244 void gpio_free(unsigned gpio);
245
246Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
247GPIOs that have already been claimed with that call. The return value of
248gpio_request() must be checked. You should normally issue these calls from
249a task context. However, for spinlock-safe GPIOs it's OK to request GPIOs
250before tasking is enabled, as part of early board setup.
251
252These calls serve two basic purposes. One is marking the signals which
253are actually in use as GPIOs, for better diagnostics; systems may have
254several hundred potential GPIOs, but often only a dozen are used on any
255given board. Another is to catch conflicts, identifying errors when
256(a) two or more drivers wrongly think they have exclusive use of that
257signal, or (b) something wrongly believes it's safe to remove drivers
258needed to manage a signal that's in active use. That is, requesting a
259GPIO can serve as a kind of lock.
260
261Some platforms may also use knowledge about what GPIOs are active for
262power management, such as by powering down unused chip sectors and, more
263easily, gating off unused clocks.
264
265For GPIOs that use pins known to the pinctrl subsystem, that subsystem should
266be informed of their use; a gpiolib driver's .request() operation may call
267pinctrl_gpio_request(), and a gpiolib driver's .free() operation may call
268pinctrl_gpio_free(). The pinctrl subsystem allows a pinctrl_gpio_request()
269to succeed concurrently with a pin or pingroup being "owned" by a device for
270pin multiplexing.
271
272Any programming of pin multiplexing hardware that is needed to route the
273GPIO signal to the appropriate pin should occur within a GPIO driver's
274.direction_input() or .direction_output() operations, and occur after any
275setup of an output GPIO's value. This allows a glitch-free migration from a
276pin's special function to GPIO. This is sometimes required when using a GPIO
277to implement a workaround on signals typically driven by a non-GPIO HW block.
278
279Some platforms allow some or all GPIO signals to be routed to different pins.
280Similarly, other aspects of the GPIO or pin may need to be configured, such as
281pullup/pulldown. Platform software should arrange that any such details are
282configured prior to gpio_request() being called for those GPIOs, e.g. using
283the pinctrl subsystem's mapping table, so that GPIO users need not be aware
284of these details.
285
286Also note that it's your responsibility to have stopped using a GPIO
287before you free it.
288
289Considering in most cases GPIOs are actually configured right after they
290are claimed, three additional calls are defined::
291
292 /* request a single GPIO, with initial configuration specified by
293 * 'flags', identical to gpio_request() wrt other arguments and
294 * return value
295 */
296 int gpio_request_one(unsigned gpio, unsigned long flags, const char *label);
297
298 /* request multiple GPIOs in a single call
299 */
300 int gpio_request_array(struct gpio *array, size_t num);
301
302 /* release multiple GPIOs in a single call
303 */
304 void gpio_free_array(struct gpio *array, size_t num);
305
306where 'flags' is currently defined to specify the following properties:
307
308 * GPIOF_DIR_IN - to configure direction as input
309 * GPIOF_DIR_OUT - to configure direction as output
310
311 * GPIOF_INIT_LOW - as output, set initial level to LOW
312 * GPIOF_INIT_HIGH - as output, set initial level to HIGH
313
314since GPIOF_INIT_* are only valid when configured as output, so group valid
315combinations as:
316
317 * GPIOF_IN - configure as input
318 * GPIOF_OUT_INIT_LOW - configured as output, initial level LOW
319 * GPIOF_OUT_INIT_HIGH - configured as output, initial level HIGH
320
321Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is
322introduced to encapsulate all three fields as::
323
324 struct gpio {
325 unsigned gpio;
326 unsigned long flags;
327 const char *label;
328 };
329
330A typical example of usage::
331
332 static struct gpio leds_gpios[] = {
333 { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */
334 { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* default to OFF */
335 { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* default to OFF */
336 { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* default to OFF */
337 { ... },
338 };
339
340 err = gpio_request_one(31, GPIOF_IN, "Reset Button");
341 if (err)
342 ...
343
344 err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios));
345 if (err)
346 ...
347
348 gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios));
349
350
351GPIOs mapped to IRQs
352--------------------
353GPIO numbers are unsigned integers; so are IRQ numbers. These make up
354two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can
355map between them using calls like::
356
357 /* map GPIO numbers to IRQ numbers */
358 int gpio_to_irq(unsigned gpio);
359
360Those return either the corresponding number in the other namespace, or
361else a negative errno code if the mapping can't be done. (For example,
362some GPIOs can't be used as IRQs.) It is an unchecked error to use a GPIO
363number that wasn't set up as an input using gpio_direction_input(), or
364to use an IRQ number that didn't originally come from gpio_to_irq().
365
366These two mapping calls are expected to cost on the order of a single
367addition or subtraction. They're not allowed to sleep.
368
369Non-error values returned from gpio_to_irq() can be passed to request_irq()
370or free_irq(). They will often be stored into IRQ resources for platform
371devices, by the board-specific initialization code. Note that IRQ trigger
372options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are
373system wakeup capabilities.
374
375
376Emulating Open Drain Signals
377----------------------------
378Sometimes shared signals need to use "open drain" signaling, where only the
379low signal level is actually driven. (That term applies to CMOS transistors;
380"open collector" is used for TTL.) A pullup resistor causes the high signal
381level. This is sometimes called a "wire-AND"; or more practically, from the
382negative logic (low=true) perspective this is a "wire-OR".
383
384One common example of an open drain signal is a shared active-low IRQ line.
385Also, bidirectional data bus signals sometimes use open drain signals.
386
387Some GPIO controllers directly support open drain outputs; many don't. When
388you need open drain signaling but your hardware doesn't directly support it,
389there's a common idiom you can use to emulate it with any GPIO pin that can
390be used as either an input or an output:
391
392 LOW: gpio_direction_output(gpio, 0) ... this drives the signal
393 and overrides the pullup.
394
395 HIGH: gpio_direction_input(gpio) ... this turns off the output,
396 so the pullup (or some other device) controls the signal.
397
398If you are "driving" the signal high but gpio_get_value(gpio) reports a low
399value (after the appropriate rise time passes), you know some other component
400is driving the shared signal low. That's not necessarily an error. As one
401common example, that's how I2C clocks are stretched: a slave that needs a
402slower clock delays the rising edge of SCK, and the I2C master adjusts its
403signaling rate accordingly.
404
405
406GPIO controllers and the pinctrl subsystem
407------------------------------------------
408
409A GPIO controller on a SOC might be tightly coupled with the pinctrl
410subsystem, in the sense that the pins can be used by other functions
411together with an optional gpio feature. We have already covered the
412case where e.g. a GPIO controller need to reserve a pin or set the
413direction of a pin by calling any of::
414
415 pinctrl_gpio_request()
416 pinctrl_gpio_free()
417 pinctrl_gpio_direction_input()
418 pinctrl_gpio_direction_output()
419
420But how does the pin control subsystem cross-correlate the GPIO
421numbers (which are a global business) to a certain pin on a certain
422pin controller?
423
424This is done by registering "ranges" of pins, which are essentially
425cross-reference tables. These are described in
426Documentation/driver-api/pin-control.rst
427
428While the pin allocation is totally managed by the pinctrl subsystem,
429gpio (under gpiolib) is still maintained by gpio drivers. It may happen
430that different pin ranges in a SoC is managed by different gpio drivers.
431
432This makes it logical to let gpio drivers announce their pin ranges to
433the pin ctrl subsystem before it will call 'pinctrl_gpio_request' in order
434to request the corresponding pin to be prepared by the pinctrl subsystem
435before any gpio usage.
436
437For this, the gpio controller can register its pin range with pinctrl
438subsystem. There are two ways of doing it currently: with or without DT.
439
440For with DT support refer to Documentation/devicetree/bindings/gpio/gpio.txt.
441
442For non-DT support, user can call gpiochip_add_pin_range() with appropriate
443parameters to register a range of gpio pins with a pinctrl driver. For this
444exact name string of pinctrl device has to be passed as one of the
445argument to this routine.
446
447
448What do these conventions omit?
449===============================
450One of the biggest things these conventions omit is pin multiplexing, since
451this is highly chip-specific and nonportable. One platform might not need
452explicit multiplexing; another might have just two options for use of any
453given pin; another might have eight options per pin; another might be able
454to route a given GPIO to any one of several pins. (Yes, those examples all
455come from systems that run Linux today.)
456
457Related to multiplexing is configuration and enabling of the pullups or
458pulldowns integrated on some platforms. Not all platforms support them,
459or support them in the same way; and any given board might use external
460pullups (or pulldowns) so that the on-chip ones should not be used.
461(When a circuit needs 5 kOhm, on-chip 100 kOhm resistors won't do.)
462Likewise drive strength (2 mA vs 20 mA) and voltage (1.8V vs 3.3V) is a
463platform-specific issue, as are models like (not) having a one-to-one
464correspondence between configurable pins and GPIOs.
465
466There are other system-specific mechanisms that are not specified here,
467like the aforementioned options for input de-glitching and wire-OR output.
468Hardware may support reading or writing GPIOs in gangs, but that's usually
469configuration dependent: for GPIOs sharing the same bank. (GPIOs are
470commonly grouped in banks of 16 or 32, with a given SOC having several such
471banks.) Some systems can trigger IRQs from output GPIOs, or read values
472from pins not managed as GPIOs. Code relying on such mechanisms will
473necessarily be nonportable.
474
475Dynamic definition of GPIOs is not currently standard; for example, as
476a side effect of configuring an add-on board with some GPIO expanders.
477
478
479GPIO implementor's framework (OPTIONAL)
480=======================================
481As noted earlier, there is an optional implementation framework making it
482easier for platforms to support different kinds of GPIO controller using
483the same programming interface. This framework is called "gpiolib".
484
485As a debugging aid, if debugfs is available a /sys/kernel/debug/gpio file
486will be found there. That will list all the controllers registered through
487this framework, and the state of the GPIOs currently in use.
488
489
490Controller Drivers: gpio_chip
491-----------------------------
492In this framework each GPIO controller is packaged as a "struct gpio_chip"
493with information common to each controller of that type:
494
495 - methods to establish GPIO direction
496 - methods used to access GPIO values
497 - flag saying whether calls to its methods may sleep
498 - optional debugfs dump method (showing extra state like pullup config)
499 - label for diagnostics
500
501There is also per-instance data, which may come from device.platform_data:
502the number of its first GPIO, and how many GPIOs it exposes.
503
504The code implementing a gpio_chip should support multiple instances of the
505controller, possibly using the driver model. That code will configure each
506gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be
507rare; use gpiochip_remove() when it is unavoidable.
508
509Most often a gpio_chip is part of an instance-specific structure with state
510not exposed by the GPIO interfaces, such as addressing, power management,
511and more. Chips such as codecs will have complex non-GPIO state.
512
513Any debugfs dump method should normally ignore signals which haven't been
514requested as GPIOs. They can use gpiochip_is_requested(), which returns
515either NULL or the label associated with that GPIO when it was requested.
516
517
518Platform Support
519----------------
520To force-enable this framework, a platform's Kconfig will "select" GPIOLIB,
521else it is up to the user to configure support for GPIO.
522
523If neither of these options are selected, the platform does not support
524GPIOs through GPIO-lib and the code cannot be enabled by the user.
525
526Trivial implementations of those functions can directly use framework
527code, which always dispatches through the gpio_chip::
528
529 #define gpio_get_value __gpio_get_value
530 #define gpio_set_value __gpio_set_value
531
532Fancier implementations could instead define those as inline functions with
533logic optimizing access to specific SOC-based GPIOs. For example, if the
534referenced GPIO is the constant "12", getting or setting its value could
535cost as little as two or three instructions, never sleeping. When such an
536optimization is not possible those calls must delegate to the framework
537code, costing at least a few dozen instructions. For bitbanged I/O, such
538instruction savings can be significant.
539
540For SOCs, platform-specific code defines and registers gpio_chip instances
541for each bank of on-chip GPIOs. Those GPIOs should be numbered/labeled to
542match chip vendor documentation, and directly match board schematics. They
543may well start at zero and go up to a platform-specific limit. Such GPIOs
544are normally integrated into platform initialization to make them always be
545available, from arch_initcall() or earlier; they can often serve as IRQs.
546
547
548Board Support
549-------------
550For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi
551function devices, FPGAs or CPLDs -- most often board-specific code handles
552registering controller devices and ensures that their drivers know what GPIO
553numbers to use with gpiochip_add(). Their numbers often start right after
554platform-specific GPIOs.
555
556For example, board setup code could create structures identifying the range
557of GPIOs that chip will expose, and passes them to each GPIO expander chip
558using platform_data. Then the chip driver's probe() routine could pass that
559data to gpiochip_add().
560
561Initialization order can be important. For example, when a device relies on
562an I2C-based GPIO, its probe() routine should only be called after that GPIO
563becomes available. That may mean the device should not be registered until
564calls for that GPIO can work. One way to address such dependencies is for
565such gpio_chip controllers to provide setup() and teardown() callbacks to
566board specific code; those board specific callbacks would register devices
567once all the necessary resources are available, and remove them later when
568the GPIO controller device becomes unavailable.
569
570
571Sysfs Interface for Userspace (OPTIONAL)
572========================================
573Platforms which use the "gpiolib" implementors framework may choose to
574configure a sysfs user interface to GPIOs. This is different from the
575debugfs interface, since it provides control over GPIO direction and
576value instead of just showing a gpio state summary. Plus, it could be
577present on production systems without debugging support.
578
579Given appropriate hardware documentation for the system, userspace could
580know for example that GPIO #23 controls the write protect line used to
581protect boot loader segments in flash memory. System upgrade procedures
582may need to temporarily remove that protection, first importing a GPIO,
583then changing its output state, then updating the code before re-enabling
584the write protection. In normal use, GPIO #23 would never be touched,
585and the kernel would have no need to know about it.
586
587Again depending on appropriate hardware documentation, on some systems
588userspace GPIO can be used to determine system configuration data that
589standard kernels won't know about. And for some tasks, simple userspace
590GPIO drivers could be all that the system really needs.
591
592Note that standard kernel drivers exist for common "LEDs and Buttons"
593GPIO tasks: "leds-gpio" and "gpio_keys", respectively. Use those
594instead of talking directly to the GPIOs; they integrate with kernel
595frameworks better than your userspace code could.
596
597
598Paths in Sysfs
599--------------
600There are three kinds of entry in /sys/class/gpio:
601
602 - Control interfaces used to get userspace control over GPIOs;
603
604 - GPIOs themselves; and
605
606 - GPIO controllers ("gpio_chip" instances).
607
608That's in addition to standard files including the "device" symlink.
609
610The control interfaces are write-only:
611
612 /sys/class/gpio/
613
614 "export" ... Userspace may ask the kernel to export control of
615 a GPIO to userspace by writing its number to this file.
616
617 Example: "echo 19 > export" will create a "gpio19" node
618 for GPIO #19, if that's not requested by kernel code.
619
620 "unexport" ... Reverses the effect of exporting to userspace.
621
622 Example: "echo 19 > unexport" will remove a "gpio19"
623 node exported using the "export" file.
624
625GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
626and have the following read/write attributes:
627
628 /sys/class/gpio/gpioN/
629
630 "direction" ... reads as either "in" or "out". This value may
631 normally be written. Writing as "out" defaults to
632 initializing the value as low. To ensure glitch free
633 operation, values "low" and "high" may be written to
634 configure the GPIO as an output with that initial value.
635
636 Note that this attribute *will not exist* if the kernel
637 doesn't support changing the direction of a GPIO, or
638 it was exported by kernel code that didn't explicitly
639 allow userspace to reconfigure this GPIO's direction.
640
641 "value" ... reads as either 0 (low) or 1 (high). If the GPIO
642 is configured as an output, this value may be written;
643 any nonzero value is treated as high.
644
645 If the pin can be configured as interrupt-generating interrupt
646 and if it has been configured to generate interrupts (see the
647 description of "edge"), you can poll(2) on that file and
648 poll(2) will return whenever the interrupt was triggered. If
649 you use poll(2), set the events POLLPRI. If you use select(2),
650 set the file descriptor in exceptfds. After poll(2) returns,
651 either lseek(2) to the beginning of the sysfs file and read the
652 new value or close the file and re-open it to read the value.
653
654 "edge" ... reads as either "none", "rising", "falling", or
655 "both". Write these strings to select the signal edge(s)
656 that will make poll(2) on the "value" file return.
657
658 This file exists only if the pin can be configured as an
659 interrupt generating input pin.
660
661 "active_low" ... reads as either 0 (false) or 1 (true). Write
662 any nonzero value to invert the value attribute both
663 for reading and writing. Existing and subsequent
664 poll(2) support configuration via the edge attribute
665 for "rising" and "falling" edges will follow this
666 setting.
667
668GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
669controller implementing GPIOs starting at #42) and have the following
670read-only attributes:
671
672 /sys/class/gpio/gpiochipN/
673
674 "base" ... same as N, the first GPIO managed by this chip
675
676 "label" ... provided for diagnostics (not always unique)
677
678 "ngpio" ... how many GPIOs this manges (N to N + ngpio - 1)
679
680Board documentation should in most cases cover what GPIOs are used for
681what purposes. However, those numbers are not always stable; GPIOs on
682a daughtercard might be different depending on the base board being used,
683or other cards in the stack. In such cases, you may need to use the
684gpiochip nodes (possibly in conjunction with schematics) to determine
685the correct GPIO number to use for a given signal.
686
687
688API Reference
689=============
690
691The functions listed in this section are deprecated. The GPIO descriptor based
692API should be used in new code.
693
694.. kernel-doc:: drivers/gpio/gpiolib-legacy.c
695 :export:
1======================
2Legacy GPIO Interfaces
3======================
4
5This provides an overview of GPIO access conventions on Linux.
6
7These calls use the gpio_* naming prefix. No other calls should use that
8prefix, or the related __gpio_* prefix.
9
10
11What is a GPIO?
12===============
13A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
14digital signal. They are provided from many kinds of chip, and are familiar
15to Linux developers working with embedded and custom hardware. Each GPIO
16represents a bit connected to a particular pin, or "ball" on Ball Grid Array
17(BGA) packages. Board schematics show which external hardware connects to
18which GPIOs. Drivers can be written generically, so that board setup code
19passes such pin configuration data to drivers.
20
21System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
22non-dedicated pin can be configured as a GPIO; and most chips have at least
23several dozen of them. Programmable logic devices (like FPGAs) can easily
24provide GPIOs; multifunction chips like power managers, and audio codecs
25often have a few such pins to help with pin scarcity on SOCs; and there are
26also "GPIO Expander" chips that connect using the I2C or SPI serial busses.
27Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
28firmware knowing how they're used).
29
30The exact capabilities of GPIOs vary between systems. Common options:
31
32 - Output values are writable (high=1, low=0). Some chips also have
33 options about how that value is driven, so that for example only one
34 value might be driven ... supporting "wire-OR" and similar schemes
35 for the other value (notably, "open drain" signaling).
36
37 - Input values are likewise readable (1, 0). Some chips support readback
38 of pins configured as "output", which is very useful in such "wire-OR"
39 cases (to support bidirectional signaling). GPIO controllers may have
40 input de-glitch/debounce logic, sometimes with software controls.
41
42 - Inputs can often be used as IRQ signals, often edge triggered but
43 sometimes level triggered. Such IRQs may be configurable as system
44 wakeup events, to wake the system from a low power state.
45
46 - Usually a GPIO will be configurable as either input or output, as needed
47 by different product boards; single direction ones exist too.
48
49 - Most GPIOs can be accessed while holding spinlocks, but those accessed
50 through a serial bus normally can't. Some systems support both types.
51
52On a given board each GPIO is used for one specific purpose like monitoring
53MMC/SD card insertion/removal, detecting card writeprotect status, driving
54a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware
55watchdog, sensing a switch, and so on.
56
57
58GPIO conventions
59================
60Note that this is called a "convention" because you don't need to do it this
61way, and it's no crime if you don't. There **are** cases where portability
62is not the main issue; GPIOs are often used for the kind of board-specific
63glue logic that may even change between board revisions, and can't ever be
64used on a board that's wired differently. Only least-common-denominator
65functionality can be very portable. Other features are platform-specific,
66and that can be critical for glue logic.
67
68Plus, this doesn't require any implementation framework, just an interface.
69One platform might implement it as simple inline functions accessing chip
70registers; another might implement it by delegating through abstractions
71used for several very different kinds of GPIO controller. (There is some
72optional code supporting such an implementation strategy, described later
73in this document, but drivers acting as clients to the GPIO interface must
74not care how it's implemented.)
75
76That said, if the convention is supported on their platform, drivers should
77use it when possible. Platforms must select GPIOLIB if GPIO functionality
78is strictly required. Drivers that can't work without
79standard GPIO calls should have Kconfig entries which depend on GPIOLIB. The
80GPIO calls are available, either as "real code" or as optimized-away stubs,
81when drivers use the include file:
82
83 #include <linux/gpio.h>
84
85If you stick to this convention then it'll be easier for other developers to
86see what your code is doing, and help maintain it.
87
88Note that these operations include I/O barriers on platforms which need to
89use them; drivers don't need to add them explicitly.
90
91
92Identifying GPIOs
93-----------------
94GPIOs are identified by unsigned integers in the range 0..MAX_INT. That
95reserves "negative" numbers for other purposes like marking signals as
96"not available on this board", or indicating faults. Code that doesn't
97touch the underlying hardware treats these integers as opaque cookies.
98
99Platforms define how they use those integers, and usually #define symbols
100for the GPIO lines so that board-specific setup code directly corresponds
101to the relevant schematics. In contrast, drivers should only use GPIO
102numbers passed to them from that setup code, using platform_data to hold
103board-specific pin configuration data (along with other board specific
104data they need). That avoids portability problems.
105
106So for example one platform uses numbers 32-159 for GPIOs; while another
107uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
108type of GPIO controller, and on one particular board 80-95 with an FPGA.
109The numbers need not be contiguous; either of those platforms could also
110use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.
111
112If you want to initialize a structure with an invalid GPIO number, use
113some negative number (perhaps "-EINVAL"); that will never be valid. To
114test if such number from such a structure could reference a GPIO, you
115may use this predicate:
116
117 int gpio_is_valid(int number);
118
119A number that's not valid will be rejected by calls which may request
120or free GPIOs (see below). Other numbers may also be rejected; for
121example, a number might be valid but temporarily unused on a given board.
122
123Whether a platform supports multiple GPIO controllers is a platform-specific
124implementation issue, as are whether that support can leave "holes" in the space
125of GPIO numbers, and whether new controllers can be added at runtime. Such issues
126can affect things including whether adjacent GPIO numbers are both valid.
127
128Using GPIOs
129-----------
130The first thing a system should do with a GPIO is allocate it, using
131the gpio_request() call; see later.
132
133One of the next things to do with a GPIO, often in board setup code when
134setting up a platform_device using the GPIO, is mark its direction::
135
136 /* set as input or output, returning 0 or negative errno */
137 int gpio_direction_input(unsigned gpio);
138 int gpio_direction_output(unsigned gpio, int value);
139
140The return value is zero for success, else a negative errno. It should
141be checked, since the get/set calls don't have error returns and since
142misconfiguration is possible. You should normally issue these calls from
143a task context. However, for spinlock-safe GPIOs it's OK to use them
144before tasking is enabled, as part of early board setup.
145
146For output GPIOs, the value provided becomes the initial output value.
147This helps avoid signal glitching during system startup.
148
149For compatibility with legacy interfaces to GPIOs, setting the direction
150of a GPIO implicitly requests that GPIO (see below) if it has not been
151requested already. That compatibility is being removed from the optional
152gpiolib framework.
153
154Setting the direction can fail if the GPIO number is invalid, or when
155that particular GPIO can't be used in that mode. It's generally a bad
156idea to rely on boot firmware to have set the direction correctly, since
157it probably wasn't validated to do more than boot Linux. (Similarly,
158that board setup code probably needs to multiplex that pin as a GPIO,
159and configure pullups/pulldowns appropriately.)
160
161
162Spinlock-Safe GPIO access
163-------------------------
164Most GPIO controllers can be accessed with memory read/write instructions.
165Those don't need to sleep, and can safely be done from inside hard
166(nonthreaded) IRQ handlers and similar contexts.
167
168Use the following calls to access such GPIOs,
169for which gpio_cansleep() will always return false (see below)::
170
171 /* GPIO INPUT: return zero or nonzero */
172 int gpio_get_value(unsigned gpio);
173
174 /* GPIO OUTPUT */
175 void gpio_set_value(unsigned gpio, int value);
176
177The values are boolean, zero for low, nonzero for high. When reading the
178value of an output pin, the value returned should be what's seen on the
179pin ... that won't always match the specified output value, because of
180issues including open-drain signaling and output latencies.
181
182The get/set calls have no error returns because "invalid GPIO" should have
183been reported earlier from gpio_direction_*(). However, note that not all
184platforms can read the value of output pins; those that can't should always
185return zero. Also, using these calls for GPIOs that can't safely be accessed
186without sleeping (see below) is an error.
187
188Platform-specific implementations are encouraged to optimize the two
189calls to access the GPIO value in cases where the GPIO number (and for
190output, value) are constant. It's normal for them to need only a couple
191of instructions in such cases (reading or writing a hardware register),
192and not to need spinlocks. Such optimized calls can make bitbanging
193applications a lot more efficient (in both space and time) than spending
194dozens of instructions on subroutine calls.
195
196
197GPIO access that may sleep
198--------------------------
199Some GPIO controllers must be accessed using message based busses like I2C
200or SPI. Commands to read or write those GPIO values require waiting to
201get to the head of a queue to transmit a command and get its response.
202This requires sleeping, which can't be done from inside IRQ handlers.
203
204Platforms that support this type of GPIO distinguish them from other GPIOs
205by returning nonzero from this call (which requires a valid GPIO number,
206which should have been previously allocated with gpio_request)::
207
208 int gpio_cansleep(unsigned gpio);
209
210To access such GPIOs, a different set of accessors is defined::
211
212 /* GPIO INPUT: return zero or nonzero, might sleep */
213 int gpio_get_value_cansleep(unsigned gpio);
214
215 /* GPIO OUTPUT, might sleep */
216 void gpio_set_value_cansleep(unsigned gpio, int value);
217
218
219Accessing such GPIOs requires a context which may sleep, for example
220a threaded IRQ handler, and those accessors must be used instead of
221spinlock-safe accessors without the cansleep() name suffix.
222
223Other than the fact that these accessors might sleep, and will work
224on GPIOs that can't be accessed from hardIRQ handlers, these calls act
225the same as the spinlock-safe calls.
226
227**IN ADDITION** calls to setup and configure such GPIOs must be made
228from contexts which may sleep, since they may need to access the GPIO
229controller chip too (These setup calls are usually made from board
230setup or driver probe/teardown code, so this is an easy constraint.)::
231
232 gpio_direction_input()
233 gpio_direction_output()
234 gpio_request()
235
236 ## gpio_request_one()
237 ## gpio_request_array()
238 ## gpio_free_array()
239
240 gpio_free()
241 gpio_set_debounce()
242
243
244
245Claiming and Releasing GPIOs
246----------------------------
247To help catch system configuration errors, two calls are defined::
248
249 /* request GPIO, returning 0 or negative errno.
250 * non-null labels may be useful for diagnostics.
251 */
252 int gpio_request(unsigned gpio, const char *label);
253
254 /* release previously-claimed GPIO */
255 void gpio_free(unsigned gpio);
256
257Passing invalid GPIO numbers to gpio_request() will fail, as will requesting
258GPIOs that have already been claimed with that call. The return value of
259gpio_request() must be checked. You should normally issue these calls from
260a task context. However, for spinlock-safe GPIOs it's OK to request GPIOs
261before tasking is enabled, as part of early board setup.
262
263These calls serve two basic purposes. One is marking the signals which
264are actually in use as GPIOs, for better diagnostics; systems may have
265several hundred potential GPIOs, but often only a dozen are used on any
266given board. Another is to catch conflicts, identifying errors when
267(a) two or more drivers wrongly think they have exclusive use of that
268signal, or (b) something wrongly believes it's safe to remove drivers
269needed to manage a signal that's in active use. That is, requesting a
270GPIO can serve as a kind of lock.
271
272Some platforms may also use knowledge about what GPIOs are active for
273power management, such as by powering down unused chip sectors and, more
274easily, gating off unused clocks.
275
276For GPIOs that use pins known to the pinctrl subsystem, that subsystem should
277be informed of their use; a gpiolib driver's .request() operation may call
278pinctrl_gpio_request(), and a gpiolib driver's .free() operation may call
279pinctrl_gpio_free(). The pinctrl subsystem allows a pinctrl_gpio_request()
280to succeed concurrently with a pin or pingroup being "owned" by a device for
281pin multiplexing.
282
283Any programming of pin multiplexing hardware that is needed to route the
284GPIO signal to the appropriate pin should occur within a GPIO driver's
285.direction_input() or .direction_output() operations, and occur after any
286setup of an output GPIO's value. This allows a glitch-free migration from a
287pin's special function to GPIO. This is sometimes required when using a GPIO
288to implement a workaround on signals typically driven by a non-GPIO HW block.
289
290Some platforms allow some or all GPIO signals to be routed to different pins.
291Similarly, other aspects of the GPIO or pin may need to be configured, such as
292pullup/pulldown. Platform software should arrange that any such details are
293configured prior to gpio_request() being called for those GPIOs, e.g. using
294the pinctrl subsystem's mapping table, so that GPIO users need not be aware
295of these details.
296
297Also note that it's your responsibility to have stopped using a GPIO
298before you free it.
299
300Considering in most cases GPIOs are actually configured right after they
301are claimed, three additional calls are defined::
302
303 /* request a single GPIO, with initial configuration specified by
304 * 'flags', identical to gpio_request() wrt other arguments and
305 * return value
306 */
307 int gpio_request_one(unsigned gpio, unsigned long flags, const char *label);
308
309 /* request multiple GPIOs in a single call
310 */
311 int gpio_request_array(struct gpio *array, size_t num);
312
313 /* release multiple GPIOs in a single call
314 */
315 void gpio_free_array(struct gpio *array, size_t num);
316
317where 'flags' is currently defined to specify the following properties:
318
319 * GPIOF_DIR_IN - to configure direction as input
320 * GPIOF_DIR_OUT - to configure direction as output
321
322 * GPIOF_INIT_LOW - as output, set initial level to LOW
323 * GPIOF_INIT_HIGH - as output, set initial level to HIGH
324 * GPIOF_OPEN_DRAIN - gpio pin is open drain type.
325 * GPIOF_OPEN_SOURCE - gpio pin is open source type.
326
327 * GPIOF_EXPORT_DIR_FIXED - export gpio to sysfs, keep direction
328 * GPIOF_EXPORT_DIR_CHANGEABLE - also export, allow changing direction
329
330since GPIOF_INIT_* are only valid when configured as output, so group valid
331combinations as:
332
333 * GPIOF_IN - configure as input
334 * GPIOF_OUT_INIT_LOW - configured as output, initial level LOW
335 * GPIOF_OUT_INIT_HIGH - configured as output, initial level HIGH
336
337When setting the flag as GPIOF_OPEN_DRAIN then it will assume that pins is
338open drain type. Such pins will not be driven to 1 in output mode. It is
339require to connect pull-up on such pins. By enabling this flag, gpio lib will
340make the direction to input when it is asked to set value of 1 in output mode
341to make the pin HIGH. The pin is make to LOW by driving value 0 in output mode.
342
343When setting the flag as GPIOF_OPEN_SOURCE then it will assume that pins is
344open source type. Such pins will not be driven to 0 in output mode. It is
345require to connect pull-down on such pin. By enabling this flag, gpio lib will
346make the direction to input when it is asked to set value of 0 in output mode
347to make the pin LOW. The pin is make to HIGH by driving value 1 in output mode.
348
349In the future, these flags can be extended to support more properties.
350
351Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is
352introduced to encapsulate all three fields as::
353
354 struct gpio {
355 unsigned gpio;
356 unsigned long flags;
357 const char *label;
358 };
359
360A typical example of usage::
361
362 static struct gpio leds_gpios[] = {
363 { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */
364 { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* default to OFF */
365 { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* default to OFF */
366 { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* default to OFF */
367 { ... },
368 };
369
370 err = gpio_request_one(31, GPIOF_IN, "Reset Button");
371 if (err)
372 ...
373
374 err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios));
375 if (err)
376 ...
377
378 gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios));
379
380
381GPIOs mapped to IRQs
382--------------------
383GPIO numbers are unsigned integers; so are IRQ numbers. These make up
384two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can
385map between them using calls like::
386
387 /* map GPIO numbers to IRQ numbers */
388 int gpio_to_irq(unsigned gpio);
389
390 /* map IRQ numbers to GPIO numbers (avoid using this) */
391 int irq_to_gpio(unsigned irq);
392
393Those return either the corresponding number in the other namespace, or
394else a negative errno code if the mapping can't be done. (For example,
395some GPIOs can't be used as IRQs.) It is an unchecked error to use a GPIO
396number that wasn't set up as an input using gpio_direction_input(), or
397to use an IRQ number that didn't originally come from gpio_to_irq().
398
399These two mapping calls are expected to cost on the order of a single
400addition or subtraction. They're not allowed to sleep.
401
402Non-error values returned from gpio_to_irq() can be passed to request_irq()
403or free_irq(). They will often be stored into IRQ resources for platform
404devices, by the board-specific initialization code. Note that IRQ trigger
405options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are
406system wakeup capabilities.
407
408Non-error values returned from irq_to_gpio() would most commonly be used
409with gpio_get_value(), for example to initialize or update driver state
410when the IRQ is edge-triggered. Note that some platforms don't support
411this reverse mapping, so you should avoid using it.
412
413
414Emulating Open Drain Signals
415----------------------------
416Sometimes shared signals need to use "open drain" signaling, where only the
417low signal level is actually driven. (That term applies to CMOS transistors;
418"open collector" is used for TTL.) A pullup resistor causes the high signal
419level. This is sometimes called a "wire-AND"; or more practically, from the
420negative logic (low=true) perspective this is a "wire-OR".
421
422One common example of an open drain signal is a shared active-low IRQ line.
423Also, bidirectional data bus signals sometimes use open drain signals.
424
425Some GPIO controllers directly support open drain outputs; many don't. When
426you need open drain signaling but your hardware doesn't directly support it,
427there's a common idiom you can use to emulate it with any GPIO pin that can
428be used as either an input or an output:
429
430 LOW: gpio_direction_output(gpio, 0) ... this drives the signal
431 and overrides the pullup.
432
433 HIGH: gpio_direction_input(gpio) ... this turns off the output,
434 so the pullup (or some other device) controls the signal.
435
436If you are "driving" the signal high but gpio_get_value(gpio) reports a low
437value (after the appropriate rise time passes), you know some other component
438is driving the shared signal low. That's not necessarily an error. As one
439common example, that's how I2C clocks are stretched: a slave that needs a
440slower clock delays the rising edge of SCK, and the I2C master adjusts its
441signaling rate accordingly.
442
443
444GPIO controllers and the pinctrl subsystem
445------------------------------------------
446
447A GPIO controller on a SOC might be tightly coupled with the pinctrl
448subsystem, in the sense that the pins can be used by other functions
449together with an optional gpio feature. We have already covered the
450case where e.g. a GPIO controller need to reserve a pin or set the
451direction of a pin by calling any of::
452
453 pinctrl_gpio_request()
454 pinctrl_gpio_free()
455 pinctrl_gpio_direction_input()
456 pinctrl_gpio_direction_output()
457
458But how does the pin control subsystem cross-correlate the GPIO
459numbers (which are a global business) to a certain pin on a certain
460pin controller?
461
462This is done by registering "ranges" of pins, which are essentially
463cross-reference tables. These are described in
464Documentation/driver-api/pin-control.rst
465
466While the pin allocation is totally managed by the pinctrl subsystem,
467gpio (under gpiolib) is still maintained by gpio drivers. It may happen
468that different pin ranges in a SoC is managed by different gpio drivers.
469
470This makes it logical to let gpio drivers announce their pin ranges to
471the pin ctrl subsystem before it will call 'pinctrl_gpio_request' in order
472to request the corresponding pin to be prepared by the pinctrl subsystem
473before any gpio usage.
474
475For this, the gpio controller can register its pin range with pinctrl
476subsystem. There are two ways of doing it currently: with or without DT.
477
478For with DT support refer to Documentation/devicetree/bindings/gpio/gpio.txt.
479
480For non-DT support, user can call gpiochip_add_pin_range() with appropriate
481parameters to register a range of gpio pins with a pinctrl driver. For this
482exact name string of pinctrl device has to be passed as one of the
483argument to this routine.
484
485
486What do these conventions omit?
487===============================
488One of the biggest things these conventions omit is pin multiplexing, since
489this is highly chip-specific and nonportable. One platform might not need
490explicit multiplexing; another might have just two options for use of any
491given pin; another might have eight options per pin; another might be able
492to route a given GPIO to any one of several pins. (Yes, those examples all
493come from systems that run Linux today.)
494
495Related to multiplexing is configuration and enabling of the pullups or
496pulldowns integrated on some platforms. Not all platforms support them,
497or support them in the same way; and any given board might use external
498pullups (or pulldowns) so that the on-chip ones should not be used.
499(When a circuit needs 5 kOhm, on-chip 100 kOhm resistors won't do.)
500Likewise drive strength (2 mA vs 20 mA) and voltage (1.8V vs 3.3V) is a
501platform-specific issue, as are models like (not) having a one-to-one
502correspondence between configurable pins and GPIOs.
503
504There are other system-specific mechanisms that are not specified here,
505like the aforementioned options for input de-glitching and wire-OR output.
506Hardware may support reading or writing GPIOs in gangs, but that's usually
507configuration dependent: for GPIOs sharing the same bank. (GPIOs are
508commonly grouped in banks of 16 or 32, with a given SOC having several such
509banks.) Some systems can trigger IRQs from output GPIOs, or read values
510from pins not managed as GPIOs. Code relying on such mechanisms will
511necessarily be nonportable.
512
513Dynamic definition of GPIOs is not currently standard; for example, as
514a side effect of configuring an add-on board with some GPIO expanders.
515
516
517GPIO implementor's framework (OPTIONAL)
518=======================================
519As noted earlier, there is an optional implementation framework making it
520easier for platforms to support different kinds of GPIO controller using
521the same programming interface. This framework is called "gpiolib".
522
523As a debugging aid, if debugfs is available a /sys/kernel/debug/gpio file
524will be found there. That will list all the controllers registered through
525this framework, and the state of the GPIOs currently in use.
526
527
528Controller Drivers: gpio_chip
529-----------------------------
530In this framework each GPIO controller is packaged as a "struct gpio_chip"
531with information common to each controller of that type:
532
533 - methods to establish GPIO direction
534 - methods used to access GPIO values
535 - flag saying whether calls to its methods may sleep
536 - optional debugfs dump method (showing extra state like pullup config)
537 - label for diagnostics
538
539There is also per-instance data, which may come from device.platform_data:
540the number of its first GPIO, and how many GPIOs it exposes.
541
542The code implementing a gpio_chip should support multiple instances of the
543controller, possibly using the driver model. That code will configure each
544gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be
545rare; use gpiochip_remove() when it is unavoidable.
546
547Most often a gpio_chip is part of an instance-specific structure with state
548not exposed by the GPIO interfaces, such as addressing, power management,
549and more. Chips such as codecs will have complex non-GPIO state.
550
551Any debugfs dump method should normally ignore signals which haven't been
552requested as GPIOs. They can use gpiochip_is_requested(), which returns
553either NULL or the label associated with that GPIO when it was requested.
554
555
556Platform Support
557----------------
558To force-enable this framework, a platform's Kconfig will "select" GPIOLIB,
559else it is up to the user to configure support for GPIO.
560
561If neither of these options are selected, the platform does not support
562GPIOs through GPIO-lib and the code cannot be enabled by the user.
563
564Trivial implementations of those functions can directly use framework
565code, which always dispatches through the gpio_chip::
566
567 #define gpio_get_value __gpio_get_value
568 #define gpio_set_value __gpio_set_value
569 #define gpio_cansleep __gpio_cansleep
570
571Fancier implementations could instead define those as inline functions with
572logic optimizing access to specific SOC-based GPIOs. For example, if the
573referenced GPIO is the constant "12", getting or setting its value could
574cost as little as two or three instructions, never sleeping. When such an
575optimization is not possible those calls must delegate to the framework
576code, costing at least a few dozen instructions. For bitbanged I/O, such
577instruction savings can be significant.
578
579For SOCs, platform-specific code defines and registers gpio_chip instances
580for each bank of on-chip GPIOs. Those GPIOs should be numbered/labeled to
581match chip vendor documentation, and directly match board schematics. They
582may well start at zero and go up to a platform-specific limit. Such GPIOs
583are normally integrated into platform initialization to make them always be
584available, from arch_initcall() or earlier; they can often serve as IRQs.
585
586
587Board Support
588-------------
589For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi
590function devices, FPGAs or CPLDs -- most often board-specific code handles
591registering controller devices and ensures that their drivers know what GPIO
592numbers to use with gpiochip_add(). Their numbers often start right after
593platform-specific GPIOs.
594
595For example, board setup code could create structures identifying the range
596of GPIOs that chip will expose, and passes them to each GPIO expander chip
597using platform_data. Then the chip driver's probe() routine could pass that
598data to gpiochip_add().
599
600Initialization order can be important. For example, when a device relies on
601an I2C-based GPIO, its probe() routine should only be called after that GPIO
602becomes available. That may mean the device should not be registered until
603calls for that GPIO can work. One way to address such dependencies is for
604such gpio_chip controllers to provide setup() and teardown() callbacks to
605board specific code; those board specific callbacks would register devices
606once all the necessary resources are available, and remove them later when
607the GPIO controller device becomes unavailable.
608
609
610Sysfs Interface for Userspace (OPTIONAL)
611========================================
612Platforms which use the "gpiolib" implementors framework may choose to
613configure a sysfs user interface to GPIOs. This is different from the
614debugfs interface, since it provides control over GPIO direction and
615value instead of just showing a gpio state summary. Plus, it could be
616present on production systems without debugging support.
617
618Given appropriate hardware documentation for the system, userspace could
619know for example that GPIO #23 controls the write protect line used to
620protect boot loader segments in flash memory. System upgrade procedures
621may need to temporarily remove that protection, first importing a GPIO,
622then changing its output state, then updating the code before re-enabling
623the write protection. In normal use, GPIO #23 would never be touched,
624and the kernel would have no need to know about it.
625
626Again depending on appropriate hardware documentation, on some systems
627userspace GPIO can be used to determine system configuration data that
628standard kernels won't know about. And for some tasks, simple userspace
629GPIO drivers could be all that the system really needs.
630
631Note that standard kernel drivers exist for common "LEDs and Buttons"
632GPIO tasks: "leds-gpio" and "gpio_keys", respectively. Use those
633instead of talking directly to the GPIOs; they integrate with kernel
634frameworks better than your userspace code could.
635
636
637Paths in Sysfs
638--------------
639There are three kinds of entry in /sys/class/gpio:
640
641 - Control interfaces used to get userspace control over GPIOs;
642
643 - GPIOs themselves; and
644
645 - GPIO controllers ("gpio_chip" instances).
646
647That's in addition to standard files including the "device" symlink.
648
649The control interfaces are write-only:
650
651 /sys/class/gpio/
652
653 "export" ... Userspace may ask the kernel to export control of
654 a GPIO to userspace by writing its number to this file.
655
656 Example: "echo 19 > export" will create a "gpio19" node
657 for GPIO #19, if that's not requested by kernel code.
658
659 "unexport" ... Reverses the effect of exporting to userspace.
660
661 Example: "echo 19 > unexport" will remove a "gpio19"
662 node exported using the "export" file.
663
664GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
665and have the following read/write attributes:
666
667 /sys/class/gpio/gpioN/
668
669 "direction" ... reads as either "in" or "out". This value may
670 normally be written. Writing as "out" defaults to
671 initializing the value as low. To ensure glitch free
672 operation, values "low" and "high" may be written to
673 configure the GPIO as an output with that initial value.
674
675 Note that this attribute *will not exist* if the kernel
676 doesn't support changing the direction of a GPIO, or
677 it was exported by kernel code that didn't explicitly
678 allow userspace to reconfigure this GPIO's direction.
679
680 "value" ... reads as either 0 (low) or 1 (high). If the GPIO
681 is configured as an output, this value may be written;
682 any nonzero value is treated as high.
683
684 If the pin can be configured as interrupt-generating interrupt
685 and if it has been configured to generate interrupts (see the
686 description of "edge"), you can poll(2) on that file and
687 poll(2) will return whenever the interrupt was triggered. If
688 you use poll(2), set the events POLLPRI. If you use select(2),
689 set the file descriptor in exceptfds. After poll(2) returns,
690 either lseek(2) to the beginning of the sysfs file and read the
691 new value or close the file and re-open it to read the value.
692
693 "edge" ... reads as either "none", "rising", "falling", or
694 "both". Write these strings to select the signal edge(s)
695 that will make poll(2) on the "value" file return.
696
697 This file exists only if the pin can be configured as an
698 interrupt generating input pin.
699
700 "active_low" ... reads as either 0 (false) or 1 (true). Write
701 any nonzero value to invert the value attribute both
702 for reading and writing. Existing and subsequent
703 poll(2) support configuration via the edge attribute
704 for "rising" and "falling" edges will follow this
705 setting.
706
707GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
708controller implementing GPIOs starting at #42) and have the following
709read-only attributes:
710
711 /sys/class/gpio/gpiochipN/
712
713 "base" ... same as N, the first GPIO managed by this chip
714
715 "label" ... provided for diagnostics (not always unique)
716
717 "ngpio" ... how many GPIOs this manges (N to N + ngpio - 1)
718
719Board documentation should in most cases cover what GPIOs are used for
720what purposes. However, those numbers are not always stable; GPIOs on
721a daughtercard might be different depending on the base board being used,
722or other cards in the stack. In such cases, you may need to use the
723gpiochip nodes (possibly in conjunction with schematics) to determine
724the correct GPIO number to use for a given signal.
725
726
727Exporting from Kernel code
728--------------------------
729Kernel code can explicitly manage exports of GPIOs which have already been
730requested using gpio_request()::
731
732 /* export the GPIO to userspace */
733 int gpio_export(unsigned gpio, bool direction_may_change);
734
735 /* reverse gpio_export() */
736 void gpio_unexport();
737
738 /* create a sysfs link to an exported GPIO node */
739 int gpio_export_link(struct device *dev, const char *name,
740 unsigned gpio)
741
742After a kernel driver requests a GPIO, it may only be made available in
743the sysfs interface by gpio_export(). The driver can control whether the
744signal direction may change. This helps drivers prevent userspace code
745from accidentally clobbering important system state.
746
747This explicit exporting can help with debugging (by making some kinds
748of experiments easier), or can provide an always-there interface that's
749suitable for documenting as part of a board support package.
750
751After the GPIO has been exported, gpio_export_link() allows creating
752symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
753use this to provide the interface under their own device in sysfs with
754a descriptive name.
755
756
757API Reference
758=============
759
760The functions listed in this section are deprecated. The GPIO descriptor based
761API should be used in new code.
762
763.. kernel-doc:: drivers/gpio/gpiolib-legacy.c
764 :export: