GPIO Interfaces on Linux

/LA.UM.7.6.2/LINUX/android/kernel/msm-4.9/Documentation/gpio/gpio-legacy.txt

This provides an overview of GPIO access conventions on Linux.

These calls use the gpio_* naming prefix.  No other calls should use that
prefix, or the related __gpio_* prefix.


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 busses.
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 writeprotect status, driving
a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware
watchdog, sensing a switch, and so on.


GPIO conventions
================
Note that this is called a "convention" because you don't need to do it this
way, and it's no crime if you don't.  There **are** cases where portability
is not the main issue; GPIOs are often used for the kind of board-specific
glue logic that may even change between board revisions, and can't ever be
used on a board that's wired differently.  Only least-common-denominator
functionality can be very portable.  Other features are platform-specific,
and that can be critical for glue logic.

Plus, this doesn't require any implementation framework, just an interface.
One platform might implement it as simple inline functions accessing chip
registers; another might implement it by delegating through abstractions
used for several very different kinds of GPIO controller.  (There is some
optional code supporting such an implementation strategy, described later
in this document, but drivers acting as clients to the GPIO interface must
not care how it's implemented.)

That said, if the convention is supported on their platform, drivers should
use it when possible.  Platforms must select GPIOLIB if GPIO functionality
is strictly required.  Drivers that can't work without
standard GPIO calls should have Kconfig entries which depend on GPIOLIB.  The
GPIO calls are available, either as "real code" or as optimized-away stubs,
when drivers use the include file:

	#include <linux/gpio.h>

If you stick to this convention then it'll be easier for other developers to
see what your code is doing, and help maintain it.

Note that these operations include I/O barriers on platforms which need to
use them; drivers don't need to add them explicitly.


Identifying GPIOs
-----------------
GPIOs are identified by unsigned integers in the range 0..MAX_INT.  That
reserves "negative" numbers for other purposes like marking signals as
"not available on this board", or indicating faults.  Code that doesn't
touch the underlying hardware treats these integers as opaque cookies.

Platforms define how they use those integers, and usually #define symbols
for the GPIO lines so that board-specific setup code directly corresponds
to the relevant schematics.  In contrast, drivers should only use GPIO
numbers passed to them from that setup code, using platform_data to hold
board-specific pin configuration data (along with other board specific
data they need).  That avoids portability problems.

So for example one platform uses numbers 32-159 for GPIOs; while another
uses numbers 0..63 with one set of GPIO controllers, 64-79 with another
type of GPIO controller, and on one particular board 80-95 with an FPGA.
The numbers need not be contiguous; either of those platforms could also
use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders.

If you want to initialize a structure with an invalid GPIO number, use
some negative number (perhaps "-EINVAL"); that will never be valid.  To
test if such number from such a structure could reference a GPIO, you
may use this predicate:

	int gpio_is_valid(int number);

A number that's not valid will be rejected by calls which may request
or free GPIOs (see below).  Other numbers may also be rejected; for
example, a number might be valid but temporarily unused on a g