From 02bf219d2f627dc962b43975433dcd6ce8f02c85 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Fri, 9 Mar 2018 00:40:19 +0100 Subject: Documentation: gpio: Move introduction to driver-api MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move gpio/intro.txt to driver-api/gpio/intro.rst and make sure it builds cleanly as ReST. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Linus Walleij --- Documentation/driver-api/gpio/index.rst | 7 ++ Documentation/driver-api/gpio/intro.rst | 124 ++++++++++++++++++++++++++++++++ Documentation/gpio/00-INDEX | 2 - Documentation/gpio/gpio.txt | 119 ------------------------------ 4 files changed, 131 insertions(+), 121 deletions(-) create mode 100644 Documentation/driver-api/gpio/intro.rst delete mode 100644 Documentation/gpio/gpio.txt diff --git a/Documentation/driver-api/gpio/index.rst b/Documentation/driver-api/gpio/index.rst index 6dd4aa647f27..db47d845f473 100644 --- a/Documentation/driver-api/gpio/index.rst +++ b/Documentation/driver-api/gpio/index.rst @@ -2,6 +2,13 @@ General Purpose Input/Output (GPIO) =================================== +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + Core ==== diff --git a/Documentation/driver-api/gpio/intro.rst b/Documentation/driver-api/gpio/intro.rst new file mode 100644 index 000000000000..74591489d0b5 --- /dev/null +++ b/Documentation/driver-api/gpio/intro.rst @@ -0,0 +1,124 @@ +============ +Introduction +============ + + +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. 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. -- cgit v1.2.3-59-g8ed1b