linux-3.3/Documentation/gpio.txt

11 A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
16 which GPIOs.  Drivers can be written generically, so that board setup code
19 System-on-Chip (SOC) processors heavily rely on GPIOs.  In some cases, every
20 non-dedicated pin can be configured as a GPIO; and most chips have at least
22 provide GPIOs; multifunction chips like power managers, and audio codecs
25 Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
28 The exact capabilities of GPIOs vary between systems.  Common options:
30   - Output values are writable (high=1, low=0).  Some chips also have
32     value might be driven ... supporting "wire-OR" and similar schemes
35   - Input values are likewise readable (1, 0).  Some chips support readback
36     of pins configured as "output", which is very useful in such "wire-OR"
38     input de-glitch/debounce logic, sometimes with software controls.
40   - Inputs can often be used as IRQ signals, often edge triggered but
44   - Usually a GPIO will be configurable as either input or output, as needed
47   - Most GPIOs can be accessed while holding spinlocks, but those accessed
60 is not the main issue; GPIOs are often used for the kind of board-specific
62 used on a board that's wired differently.  Only least-common-denominator
63 functionality can be very portable.  Other features are platform-specific,
79 optimized-away stubs, when drivers use the include file:
90 Identifying GPIOs
91 -----------------
92 GPIOs are identified by unsigned integers in the range 0..MAX_INT.  That
98 for the GPIO lines so that board-specific setup code directly corresponds
101 board-specific pin configuration data (along with other board specific
104 So for example one platform uses numbers 32-159 for GPIOs; while another
105 uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
106 type of GPIO controller, and on one particular board 80-95 with an FPGA.
108 use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.
111 some negative number (perhaps "-EINVAL"); that will never be valid.  To
118 or free GPIOs (see below).  Other numbers may also be rejected; for
121 Whether a platform supports multiple GPIO controllers is a platform-specific
126 Using GPIOs
127 -----------
141 a task context.  However, for spinlock-safe GPIOs it's OK to use them
144 For output GPIOs, the value provided becomes the initial output value.
147 For compatibility with legacy interfaces to GPIOs, setting the direction
160 Spinlock-Safe GPIO access
161 -------------------------
166 Use the following calls to access such GPIOs,
178 issues including open-drain signaling and output latencies.
183 return zero.  Also, using these calls for GPIOs that can't safely be accessed
186 Platform-specific implementations are encouraged to optimize the two
196 --------------------------
202 Platforms that support this type of GPIO distinguish them from other GPIOs
208 To access such GPIOs, a different set of accessors is defined:
217 Accessing such GPIOs requires a context which may sleep,  for example
219 spinlock-safe accessors without the cansleep() name suffix.
222 on GPIOs that can't be accessed from hardIRQ handlers, these calls act
223 the same as the spinlock-safe calls.
225   ** IN ADDITION ** calls to setup and configure such GPIOs must be made
243 Claiming and Releasing GPIOs
244 ----------------------------
248 	 * non-null labels may be useful for diagnostics.
252 	/* release previously-claimed GPIO */
256 GPIOs that have already been claimed with that call.  The return value of
258 a task context.  However, for spinlock-safe GPIOs it's OK to request GPIOs
262 are actually in use as GPIOs, for better diagnostics; systems may have
263 several hundred potential GPIOs, but often only a dozen are used on any
270 Some platforms may also use knowledge about what GPIOs are active for
281 Considering in most cases GPIOs are actually configured right after they
290 	/* request multiple GPIOs in a single call
294 	/* release multiple GPIOs in a single call
300 	* GPIOF_DIR_IN		- to configure direction as input
301 	* GPIOF_DIR_OUT		- to configure direction as output
303 	* GPIOF_INIT_LOW	- as output, set initial level to LOW
304 	* GPIOF_INIT_HIGH	- as output, set initial level to HIGH
309 	* GPIOF_IN		- configure as input
310 	* GPIOF_OUT_INIT_LOW	- configured as output, initial level LOW
311 	* GPIOF_OUT_INIT_HIGH	- configured as output, initial level HIGH
314 as open-drain status.
316 Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is
346 GPIOs mapped to IRQs
347 --------------------
360 some GPIOs can't be used as IRQs.)  It is an unchecked error to use a GPIO
367 Non-error values returned from gpio_to_irq() can be passed to request_irq()
369 devices, by the board-specific initialization code.  Note that IRQ trigger
373 Non-error values returned from irq_to_gpio() would most commonly be used
375 when the IRQ is edge-triggered.  Note that some platforms don't support
380 ----------------------------
384 level.  This is sometimes called a "wire-AND"; or more practically, from the
385 negative logic (low=true) perspective this is a "wire-OR".
387 One common example of an open drain signal is a shared active-low IRQ line.
412 this is highly chip-specific and nonportable.  One platform might not need
421 pullups (or pulldowns) so that the on-chip ones should not be used.
422 (When a circuit needs 5 kOhm, on-chip 100 kOhm resistors won't do.)
424 platform-specific issue, as are models like (not) having a one-to-one
425 correspondence between configurable pins and GPIOs.
427 There are other system-specific mechanisms that are not specified here,
428 like the aforementioned options for input de-glitching and wire-OR output.
429 Hardware may support reading or writing GPIOs in gangs, but that's usually
430 configuration dependent:  for GPIOs sharing the same bank.  (GPIOs are
432 banks.)  Some systems can trigger IRQs from output GPIOs, or read values
433 from pins not managed as GPIOs.  Code relying on such mechanisms will
436 Dynamic definition of GPIOs is not currently standard; for example, as
437 a side effect of configuring an add-on board with some GPIO expanders.
448 this framework, and the state of the GPIOs currently in use.
452 -----------------------------
456  - methods to establish GPIO direction
457  - methods used to access GPIO values
458  - flag saying whether calls to its methods may sleep
459  - optional debugfs dump method (showing extra state like pullup config)
460  - label for diagnostics
462 There is also per-instance data, which may come from device.platform_data:
463 the number of its first GPIO, and how many GPIOs it exposes.
470 Most often a gpio_chip is part of an instance-specific structure with state
472 and more.  Chips such as codecs will have complex non-GPIO state.
475 requested as GPIOs.  They can use gpiochip_is_requested(), which returns
480 ----------------
481 To support this framework, a platform's Kconfig will "select" either
483 and arrange that its <asm/gpio.h> includes <asm-generic/gpio.h> and defines
487 reflects the number of GPIOs in actual use on that platform, without
488 wasting static table space.  (It should count both built-in/SoC GPIOs and
498 GPIOs through GPIO-lib and the code cannot be enabled by the user.
508 logic optimizing access to specific SOC-based GPIOs.  For example, if the
515 For SOCs, platform-specific code defines and registers gpio_chip instances
516 for each bank of on-chip GPIOs.  Those GPIOs should be numbered/labeled to
518 may well start at zero and go up to a platform-specific limit.  Such GPIOs
524 -------------
525 For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi
526 function devices, FPGAs or CPLDs -- most often board-specific code handles
529 platform-specific GPIOs.
532 of GPIOs that chip will expose, and passes them to each GPIO expander chip
537 an I2C-based GPIO, its probe() routine should only be called after that GPIO
549 configure a sysfs user interface to GPIOs.  This is different from the
558 then changing its output state, then updating the code before re-enabling
568 GPIO tasks:  "leds-gpio" and "gpio_keys", respectively.  Use those
569 instead of talking directly to the GPIOs; they integrate with kernel
574 --------------
577    -	Control interfaces used to get userspace control over GPIOs;
579    -	GPIOs themselves; and
581    -	GPIO controllers ("gpio_chip" instances).
585 The control interfaces are write-only:
620 		If the pin can be configured as interrupt-generating interrupt
625 		use select(2), set the file descriptor in exceptfds. After
627 		file and read the new value or close the file and re-open it
631 		"both". Write these strings to select the signal edge(s)
645 controller implementing GPIOs starting at #42) and have the following
646 read-only attributes:
654     	"ngpio" ... how many GPIOs this manges (N to N + ngpio - 1)
656 Board documentation should in most cases cover what GPIOs are used for
657 what purposes.  However, those numbers are not always stable; GPIOs on
665 --------------------------
666 Kernel code can explicitly manage exports of GPIOs which have already been
688 of experiments easier), or can provide an always-there interface that's