diff options
author | Jonathan Neuschäfer <j.neuschaefer@gmx.net> | 2018-03-09 00:40:19 +0100 |
---|---|---|
committer | Linus Walleij <linus.walleij@linaro.org> | 2018-03-23 04:20:30 +0100 |
commit | 02bf219d2f627dc962b43975433dcd6ce8f02c85 (patch) | |
tree | 3f61206ee49104f016aa2c9f18eec76f4b6fd039 /Documentation/gpio | |
parent | 7e6332592bbcdc446b4984efab78a6c471b14fa6 (diff) |
Documentation: gpio: Move introduction to driver-api
Move gpio/intro.txt to driver-api/gpio/intro.rst and make sure it builds
cleanly as ReST.
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
Diffstat (limited to 'Documentation/gpio')
-rw-r--r-- | Documentation/gpio/00-INDEX | 2 | ||||
-rw-r--r-- | Documentation/gpio/gpio.txt | 119 |
2 files changed, 0 insertions, 121 deletions
diff --git a/Documentation/gpio/00-INDEX b/Documentation/gpio/00-INDEX index 179beb234f98..52fe0fa6c964 100644 --- a/Documentation/gpio/00-INDEX +++ b/Documentation/gpio/00-INDEX @@ -1,7 +1,5 @@ 00-INDEX - This file -gpio.txt - - Introduction to GPIOs and their kernel interfaces consumer.txt - How to obtain and use GPIOs in a driver driver.txt diff --git a/Documentation/gpio/gpio.txt b/Documentation/gpio/gpio.txt deleted file mode 100644 index cd9b356e88cd..000000000000 --- a/Documentation/gpio/gpio.txt +++ /dev/null @@ -1,119 +0,0 @@ -GPIO Interfaces -=============== - -The documents in this directory give detailed instructions on how to access -GPIOs in drivers, and how to write a driver for a device that provides GPIOs -itself. - -Due to the history of GPIO interfaces in the kernel, there are two different -ways to obtain and use GPIOs: - - - The descriptor-based interface is the preferred way to manipulate GPIOs, -and is described by all the files in this directory excepted gpio-legacy.txt. - - The legacy integer-based interface which is considered deprecated (but still -usable for compatibility reasons) is documented in gpio-legacy.txt. - -The remainder of this document applies to the new descriptor-based interface. -gpio-legacy.txt contains the same information applied to the legacy -integer-based interface. - - -What is a GPIO? -=============== - -A "General Purpose Input/Output" (GPIO) is a flexible software-controlled -digital signal. They are provided from many kinds of chip, and are familiar -to Linux developers working with embedded and custom hardware. Each GPIO -represents a bit connected to a particular pin, or "ball" on Ball Grid Array -(BGA) packages. Board schematics show which external hardware connects to -which GPIOs. Drivers can be written generically, so that board setup code -passes such pin configuration data to drivers. - -System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every -non-dedicated pin can be configured as a GPIO; and most chips have at least -several dozen of them. Programmable logic devices (like FPGAs) can easily -provide GPIOs; multifunction chips like power managers, and audio codecs -often have a few such pins to help with pin scarcity on SOCs; and there are -also "GPIO Expander" chips that connect using the I2C or SPI serial buses. -Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS -firmware knowing how they're used). - -The exact capabilities of GPIOs vary between systems. Common options: - - - Output values are writable (high=1, low=0). Some chips also have - options about how that value is driven, so that for example only one - value might be driven, supporting "wire-OR" and similar schemes for the - other value (notably, "open drain" signaling). - - - Input values are likewise readable (1, 0). Some chips support readback - of pins configured as "output", which is very useful in such "wire-OR" - cases (to support bidirectional signaling). GPIO controllers may have - input de-glitch/debounce logic, sometimes with software controls. - - - Inputs can often be used as IRQ signals, often edge triggered but - sometimes level triggered. Such IRQs may be configurable as system - wakeup events, to wake the system from a low power state. - - - Usually a GPIO will be configurable as either input or output, as needed - by different product boards; single direction ones exist too. - - - Most GPIOs can be accessed while holding spinlocks, but those accessed - through a serial bus normally can't. Some systems support both types. - -On a given board each GPIO is used for one specific purpose like monitoring -MMC/SD card insertion/removal, detecting card write-protect status, driving -a LED, configuring a transceiver, bit-banging a serial bus, poking a hardware -watchdog, sensing a switch, and so on. - - -Common GPIO Properties -====================== - -These properties are met through all the other documents of the GPIO interface -and it is useful to understand them, especially if you need to define GPIO -mappings. - -Active-High and Active-Low --------------------------- -It is natural to assume that a GPIO is "active" when its output signal is 1 -("high"), and inactive when it is 0 ("low"). However in practice the signal of a -GPIO may be inverted before is reaches its destination, or a device could decide -to have different conventions about what "active" means. Such decisions should -be transparent to device drivers, therefore it is possible to define a GPIO as -being either active-high ("1" means "active", the default) or active-low ("0" -means "active") so that drivers only need to worry about the logical signal and -not about what happens at the line level. - -Open Drain and Open Source --------------------------- -Sometimes shared signals need to use "open drain" (where only the low signal -level is actually driven), or "open source" (where only the high signal level is -driven) signaling. That term applies to CMOS transistors; "open collector" is -used for TTL. A pullup or pulldown resistor causes the high or low signal level. -This is sometimes called a "wire-AND"; or more practically, from the negative -logic (low=true) perspective this is a "wire-OR". - -One common example of an open drain signal is a shared active-low IRQ line. -Also, bidirectional data bus signals sometimes use open drain signals. - -Some GPIO controllers directly support open drain and open source outputs; many -don't. When you need open drain signaling but your hardware doesn't directly -support it, there's a common idiom you can use to emulate it with any GPIO pin -that can be used as either an input or an output: - - LOW: gpiod_direction_output(gpio, 0) ... this drives the signal and overrides - the pullup. - - HIGH: gpiod_direction_input(gpio) ... this turns off the output, so the pullup - (or some other device) controls the signal. - -The same logic can be applied to emulate open source signaling, by driving the -high signal and configuring the GPIO as input for low. This open drain/open -source emulation can be handled transparently by the GPIO framework. - -If you are "driving" the signal high but gpiod_get_value(gpio) reports a low -value (after the appropriate rise time passes), you know some other component is -driving the shared signal low. That's not necessarily an error. As one common -example, that's how I2C clocks are stretched: a slave that needs a slower clock -delays the rising edge of SCK, and the I2C master adjusts its signaling rate -accordingly. |