About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / gpio / gpio.txt

Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:55 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.