driver-api/gpio/legacy.rst

13 A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
21 System-on-Chip (SOC) processors heavily rely on GPIOs.  In some cases, every
22 non-dedicated pin can be configured as a GPIO; and most chips have at least
27 Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
32   - Output values are writable (high=1, low=0).  Some chips also have
34     value might be driven ... supporting "wire-OR" and similar schemes
35     for the other value (notably, "open drain" signaling).
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"
40     input de-glitch/debounce logic, sometimes with software controls.
42   - Inputs can often be used as IRQ signals, often edge triggered but
46   - Usually a GPIO will be configurable as either input or output, as needed
49   - Most GPIOs can be accessed while holding spinlocks, but those accessed
54 a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware
62 is not the main issue; GPIOs are often used for the kind of board-specific
64 used on a board that's wired differently.  Only least-common-denominator
65 functionality can be very portable.  Other features are platform-specific,
80 GPIO calls are available, either as "real code" or as optimized-away stubs,
93 -----------------
100 for the GPIO lines so that board-specific setup code directly corresponds
103 board-specific pin configuration data (along with other board specific
106 So for example one platform uses numbers 32-159 for GPIOs; while another
107 uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
108 type of GPIO controller, and on one particular board 80-95 with an FPGA.
110 use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.
113 some negative number (perhaps "-EINVAL"); that will never be valid.  To
123 Whether a platform supports multiple GPIO controllers is a platform-specific
129 -----------
143 a task context.  However, for spinlock-safe GPIOs it's OK to use them
162 Spinlock-Safe GPIO access
163 -------------------------
179 issues including open-drain signaling and output latencies.
187 Platform-specific implementations are encouraged to optimize the two
197 --------------------------
212 spinlock-safe accessors without the cansleep() name suffix.
216 the same as the spinlock-safe calls.
235 ----------------------------
239 	 * non-null labels may be useful for diagnostics.
243 	/* release previously-claimed GPIO */
249 a task context.  However, for spinlock-safe GPIOs it's OK to request GPIOs
275 setup of an output GPIO's value. This allows a glitch-free migration from a
277 to implement a workaround on signals typically driven by a non-GPIO HW block.
308 	* GPIOF_DIR_IN		- to configure direction as input
309 	* GPIOF_DIR_OUT		- to configure direction as output
311 	* GPIOF_INIT_LOW	- as output, set initial level to LOW
312 	* GPIOF_INIT_HIGH	- as output, set initial level to HIGH
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
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 */
352 --------------------
369 Non-error values returned from gpio_to_irq() can be passed to request_irq()
371 devices, by the board-specific initialization code.  Note that IRQ trigger
376 Emulating Open Drain Signals
377 ----------------------------
378 Sometimes shared signals need to use "open drain" signaling, where only the
380 "open collector" is used for TTL.)  A pullup resistor causes the high signal
381 level.  This is sometimes called a "wire-AND"; or more practically, from the
382 negative logic (low=true) perspective this is a "wire-OR".
384 One common example of an open drain signal is a shared active-low IRQ line.
385 Also, bidirectional data bus signals sometimes use open drain signals.
387 Some GPIO controllers directly support open drain outputs; many don't.  When
388 you need open drain signaling but your hardware doesn't directly support it,
407 ------------------------------------------
420 But how does the pin control subsystem cross-correlate the GPIO
425 cross-reference tables. These are described in
426 Documentation/driver-api/pin-control.rst
442 For non-DT support, user can call gpiochip_add_pin_range() with appropriate
451 this is highly chip-specific and nonportable.  One platform might not need
460 pullups (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.)
463 platform-specific issue, as are models like (not) having a one-to-one
466 There are other system-specific mechanisms that are not specified here,
467 like the aforementioned options for input de-glitching and wire-OR output.
476 a side effect of configuring an add-on board with some GPIO expanders.
491 -----------------------------
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
501 There is also per-instance data, which may come from device.platform_data:
509 Most often a gpio_chip is part of an instance-specific structure with state
511 and more.  Chips such as codecs will have complex non-GPIO state.
519 ----------------
520 To force-enable this framework, a platform's Kconfig will "select" GPIOLIB,
524 GPIOs through GPIO-lib and the code cannot be enabled by the user.
533 logic optimizing access to specific SOC-based GPIOs.  For example, if the
540 For SOCs, platform-specific code defines and registers gpio_chip instances
541 for each bank of on-chip GPIOs.  Those GPIOs should be numbered/labeled to
543 may well start at zero and go up to a platform-specific limit.  Such GPIOs
549 -------------
550 For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi
551 function devices, FPGAs or CPLDs -- most often board-specific code handles
554 platform-specific GPIOs.
562 an I2C-based GPIO, its probe() routine should only be called after that GPIO
583 then changing its output state, then updating the code before re-enabling
593 GPIO tasks:  "leds-gpio" and "gpio_keys", respectively.  Use those
599 --------------
602    -	Control interfaces used to get userspace control over GPIOs;
604    -	GPIOs themselves; and
606    -	GPIO controllers ("gpio_chip" instances).
610 The control interfaces are write-only:
645 		If the pin can be configured as interrupt-generating interrupt
652 		new value or close the file and re-open it to read the value.
670 read-only attributes:
678     	"ngpio" ... how many GPIOs this manges (N to N + ngpio - 1)
694 .. kernel-doc:: drivers/gpio/gpiolib-legacy.c