1 ============ 1 ============
2 Introduction 2 Introduction
3 ============ 3 ============
4 4
5 5
6 GPIO Interfaces 6 GPIO Interfaces
7 =============== 7 ===============
8 8
9 The documents in this directory give detailed 9 The documents in this directory give detailed instructions on how to access
10 GPIOs in drivers, and how to write a driver fo 10 GPIOs in drivers, and how to write a driver for a device that provides GPIOs
11 itself. 11 itself.
12 12
>> 13 Due to the history of GPIO interfaces in the kernel, there are two different
>> 14 ways to obtain and use GPIOs:
>> 15
>> 16 - The descriptor-based interface is the preferred way to manipulate GPIOs,
>> 17 and is described by all the files in this directory excepted legacy.rst.
>> 18 - The legacy integer-based interface which is considered deprecated (but still
>> 19 usable for compatibility reasons) is documented in legacy.rst.
>> 20
>> 21 The remainder of this document applies to the new descriptor-based interface.
>> 22 legacy.rst contains the same information applied to the legacy
>> 23 integer-based interface.
>> 24
13 25
14 What is a GPIO? 26 What is a GPIO?
15 =============== 27 ===============
16 28
17 A "General Purpose Input/Output" (GPIO) is a f 29 A "General Purpose Input/Output" (GPIO) is a flexible software-controlled
18 digital signal. They are provided from many ki 30 digital signal. They are provided from many kinds of chips, and are familiar
19 to Linux developers working with embedded and 31 to Linux developers working with embedded and custom hardware. Each GPIO
20 represents a bit connected to a particular pin 32 represents a bit connected to a particular pin, or "ball" on Ball Grid Array
21 (BGA) packages. Board schematics show which ex 33 (BGA) packages. Board schematics show which external hardware connects to
22 which GPIOs. Drivers can be written genericall 34 which GPIOs. Drivers can be written generically, so that board setup code
23 passes such pin configuration data to drivers. 35 passes such pin configuration data to drivers.
24 36
25 System-on-Chip (SOC) processors heavily rely o 37 System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every
26 non-dedicated pin can be configured as a GPIO; 38 non-dedicated pin can be configured as a GPIO; and most chips have at least
27 several dozen of them. Programmable logic devi 39 several dozen of them. Programmable logic devices (like FPGAs) can easily
28 provide GPIOs; multifunction chips like power 40 provide GPIOs; multifunction chips like power managers, and audio codecs
29 often have a few such pins to help with pin sc 41 often have a few such pins to help with pin scarcity on SOCs; and there are
30 also "GPIO Expander" chips that connect using 42 also "GPIO Expander" chips that connect using the I2C or SPI serial buses.
31 Most PC southbridges have a few dozen GPIO-cap 43 Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS
32 firmware knowing how they're used). 44 firmware knowing how they're used).
33 45
34 The exact capabilities of GPIOs vary between s 46 The exact capabilities of GPIOs vary between systems. Common options:
35 47
36 - Output values are writable (high=1, low=0) 48 - Output values are writable (high=1, low=0). Some chips also have
37 options about how that value is driven, so 49 options about how that value is driven, so that for example only one
38 value might be driven, supporting "wire-OR 50 value might be driven, supporting "wire-OR" and similar schemes for the
39 other value (notably, "open drain" signali 51 other value (notably, "open drain" signaling).
40 52
41 - Input values are likewise readable (1, 0). 53 - Input values are likewise readable (1, 0). Some chips support readback
42 of pins configured as "output", which is v 54 of pins configured as "output", which is very useful in such "wire-OR"
43 cases (to support bidirectional signaling) 55 cases (to support bidirectional signaling). GPIO controllers may have
44 input de-glitch/debounce logic, sometimes 56 input de-glitch/debounce logic, sometimes with software controls.
45 57
46 - Inputs can often be used as IRQ signals, o 58 - Inputs can often be used as IRQ signals, often edge triggered but
47 sometimes level triggered. Such IRQs may b 59 sometimes level triggered. Such IRQs may be configurable as system
48 wakeup events, to wake the system from a l 60 wakeup events, to wake the system from a low power state.
49 61
50 - Usually a GPIO will be configurable as eit 62 - Usually a GPIO will be configurable as either input or output, as needed
51 by different product boards; single direct 63 by different product boards; single direction ones exist too.
52 64
53 - Most GPIOs can be accessed while holding s 65 - Most GPIOs can be accessed while holding spinlocks, but those accessed
54 through a serial bus normally can't. Some 66 through a serial bus normally can't. Some systems support both types.
55 67
56 On a given board each GPIO is used for one spe 68 On a given board each GPIO is used for one specific purpose like monitoring
57 MMC/SD card insertion/removal, detecting card 69 MMC/SD card insertion/removal, detecting card write-protect status, driving
58 a LED, configuring a transceiver, bit-banging 70 a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware
59 watchdog, sensing a switch, and so on. 71 watchdog, sensing a switch, and so on.
60 72
61 73
62 Common GPIO Properties 74 Common GPIO Properties
63 ====================== 75 ======================
64 76
65 These properties are met through all the other 77 These properties are met through all the other documents of the GPIO interface
66 and it is useful to understand them, especiall 78 and it is useful to understand them, especially if you need to define GPIO
67 mappings. 79 mappings.
68 80
69 Active-High and Active-Low 81 Active-High and Active-Low
70 -------------------------- 82 --------------------------
71 It is natural to assume that a GPIO is "active 83 It is natural to assume that a GPIO is "active" when its output signal is 1
72 ("high"), and inactive when it is 0 ("low"). H 84 ("high"), and inactive when it is 0 ("low"). However in practice the signal of a
73 GPIO may be inverted before is reaches its des 85 GPIO may be inverted before is reaches its destination, or a device could decide
74 to have different conventions about what "acti 86 to have different conventions about what "active" means. Such decisions should
75 be transparent to device drivers, therefore it 87 be transparent to device drivers, therefore it is possible to define a GPIO as
76 being either active-high ("1" means "active", 88 being either active-high ("1" means "active", the default) or active-low ("0"
77 means "active") so that drivers only need to w 89 means "active") so that drivers only need to worry about the logical signal and
78 not about what happens at the line level. 90 not about what happens at the line level.
79 91
80 Open Drain and Open Source 92 Open Drain and Open Source
81 -------------------------- 93 --------------------------
82 Sometimes shared signals need to use "open dra 94 Sometimes shared signals need to use "open drain" (where only the low signal
83 level is actually driven), or "open source" (w 95 level is actually driven), or "open source" (where only the high signal level is
84 driven) signaling. That term applies to CMOS t 96 driven) signaling. That term applies to CMOS transistors; "open collector" is
85 used for TTL. A pullup or pulldown resistor ca 97 used for TTL. A pullup or pulldown resistor causes the high or low signal level.
86 This is sometimes called a "wire-AND"; or more 98 This is sometimes called a "wire-AND"; or more practically, from the negative
87 logic (low=true) perspective this is a "wire-O 99 logic (low=true) perspective this is a "wire-OR".
88 100
89 One common example of an open drain signal is 101 One common example of an open drain signal is a shared active-low IRQ line.
90 Also, bidirectional data bus signals sometimes 102 Also, bidirectional data bus signals sometimes use open drain signals.
91 103
92 Some GPIO controllers directly support open dr 104 Some GPIO controllers directly support open drain and open source outputs; many
93 don't. When you need open drain signaling but 105 don't. When you need open drain signaling but your hardware doesn't directly
94 support it, there's a common idiom you can use 106 support it, there's a common idiom you can use to emulate it with any GPIO pin
95 that can be used as either an input or an outp 107 that can be used as either an input or an output:
96 108
97 **LOW**: ``gpiod_direction_output(gpio, 0)`` 109 **LOW**: ``gpiod_direction_output(gpio, 0)`` ... this drives the signal and
98 overrides the pullup. 110 overrides the pullup.
99 111
100 **HIGH**: ``gpiod_direction_input(gpio)`` ... 112 **HIGH**: ``gpiod_direction_input(gpio)`` ... this turns off the output, so
101 the pullup (or some other device) controls th 113 the pullup (or some other device) controls the signal.
102 114
103 The same logic can be applied to emulate open 115 The same logic can be applied to emulate open source signaling, by driving the
104 high signal and configuring the GPIO as input 116 high signal and configuring the GPIO as input for low. This open drain/open
105 source emulation can be handled transparently 117 source emulation can be handled transparently by the GPIO framework.
106 118
107 If you are "driving" the signal high but gpiod 119 If you are "driving" the signal high but gpiod_get_value(gpio) reports a low
108 value (after the appropriate rise time passes) 120 value (after the appropriate rise time passes), you know some other component is
109 driving the shared signal low. That's not nece 121 driving the shared signal low. That's not necessarily an error. As one common
110 example, that's how I2C clocks are stretched: 122 example, that's how I2C clocks are stretched: a slave that needs a slower clock
111 delays the rising edge of SCK, and the I2C mas 123 delays the rising edge of SCK, and the I2C master adjusts its signaling rate
112 accordingly. 124 accordingly.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.