Merge tag 'gpio-v3.13-2' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio

GPIO Mappings

=============

This document explains how GPIOs can be assigned to given devices and functions.

Note that it only applies to the new descriptor-based interface. For a

description of the deprecated integer-based GPIO interface please refer to

gpio-legacy.txt (actually, there is no real mapping possible with the old

interface; you just fetch an integer from somewhere and request the

corresponding GPIO.

Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage

is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in

their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to

describe its hardware layout. Currently, mappings can be defined through device

tree, ACPI, and platform data.

Device Tree

-----------

GPIOs can easily be mapped to devices and functions in the device tree. The

exact way to do it depends on the GPIO controller providing the GPIOs, see the

device tree bindings for your controller.

GPIOs mappings are defined in the consumer device's node, in a property named

<function>-gpios, where <function> is the function the driver will request

through gpiod_get(). For example:

	foo_device {

		compatible = "acme,foo";

		...

		led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */

			    <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */

			    <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */

		power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>;

	};

This property will make GPIOs 15, 16 and 17 available to the driver under the

"led" function, and GPIO 1 as the "power" GPIO:

	struct gpio_desc *red, *green, *blue, *power;

	red = gpiod_get_index(dev, "led", 0);

	green = gpiod_get_index(dev, "led", 1);

	blue = gpiod_get_index(dev, "led", 2);

	power = gpiod_get(dev, "power");

The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.

gpiod_is_active_low(power) will be true).

ACPI

----

ACPI does not support function names for GPIOs. Therefore, only the "idx"

argument of gpiod_get_index() is useful to discriminate between GPIOs assigned

to a device. The "con_id" argument can still be set for debugging purposes (it

will appear under error messages as well as debug and sysfs nodes).

Platform Data

-------------

Finally, GPIOs can be bound to devices and functions using platform data. Board

files that desire to do so need to include the following header:

	#include <linux/gpio/driver.h>

GPIOs are mapped by the means of tables of lookups, containing instances of the

gpiod_lookup structure. Two macros are defined to help declaring such mappings:

	GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags)

	GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags)

where

  - chip_label is the label of the gpiod_chip instance providing the GPIO

  - chip_hwnum is the hardware number of the GPIO within the chip

  - dev_id is the identifier of the device that will make use of this GPIO. If

	NULL, the GPIO will be available to all devices.

  - con_id is the name of the GPIO function from the device point of view. It

	can be NULL.

  - idx is the index of the GPIO within the function.

  - flags is defined to specify the following properties:

	* GPIOF_ACTIVE_LOW	- to configure the GPIO as active-low

	* GPIOF_OPEN_DRAIN	- GPIO pin is open drain type.

	* GPIOF_OPEN_SOURCE	- GPIO pin is open source type.

In the future, these flags might be extended to support more properties.

Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.

A lookup table can then be defined as follows:

	struct gpiod_lookup gpios_table[] = {

	GPIO_LOOKUP_IDX("gpio.0", 15, "foo.0", "led", 0, GPIO_ACTIVE_HIGH),

	GPIO_LOOKUP_IDX("gpio.0", 16, "foo.0", "led", 1, GPIO_ACTIVE_HIGH),

	GPIO_LOOKUP_IDX("gpio.0", 17, "foo.0", "led", 2, GPIO_ACTIVE_HIGH),

	GPIO_LOOKUP("gpio.0", 1, "foo.0", "power", GPIO_ACTIVE_LOW),

	};

And the table can be added by the board code as follows:

	gpiod_add_table(gpios_table, ARRAY_SIZE(gpios_table));

The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:

	struct gpio_desc *red, *green, *blue, *power;

	red = gpiod_get_index(dev, "led", 0);

	green = gpiod_get_index(dev, "led", 1);

	blue = gpiod_get_index(dev, "led", 2);

	power = gpiod_get(dev, "power");

	gpiod_direction_output(power, 1);

Since the "power" GPIO is mapped as active-low, its actual signal will be 0

after this code. Contrary to the legacy integer GPIO interface, the active-low

property is handled during mapping and is thus transparent to GPIO consumers.

GPIO Descriptor Consumer Interface

==================================

This document describes the consumer interface of the GPIO framework. Note that

it describes the new descriptor-based interface. For a description of the

deprecated integer-based GPIO interface please refer to gpio-legacy.txt.

Guidelines for GPIOs consumers

==============================

Drivers that can't work without standard GPIO calls should have Kconfig entries

that depend on GPIOLIB. The functions that allow a driver to obtain and use

GPIOs are available by including the following file:

	#include <linux/gpio/consumer.h>

All the functions that work with the descriptor-based GPIO interface are

prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No

other function in the kernel should use these prefixes.

Obtaining and Disposing GPIOs

=============================

With the descriptor-based interface, GPIOs are identified with an opaque,

non-forgeable handler that must be obtained through a call to one of the

gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the

device that will use the GPIO and the function the requested GPIO is supposed to

fulfill:

	struct gpio_desc *gpiod_get(struct device *dev, const char *con_id)

If a function is implemented by using several GPIOs together (e.g. a simple LED

device that displays digits), an additional index argument can be specified:

	struct gpio_desc *gpiod_get_index(struct device *dev,

					  const char *con_id, unsigned int idx)

Both functions return either a valid GPIO descriptor, or an error code checkable

with IS_ERR(). They will never return a NULL pointer.

Device-managed variants of these functions are also defined:

	struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id)

	struct gpio_desc *devm_gpiod_get_index(struct device *dev,

					       const char *con_id,

					       unsigned int idx)

A GPIO descriptor can be disposed of using the gpiod_put() function:

	void gpiod_put(struct gpio_desc *desc)

It is strictly forbidden to use a descriptor after calling this function. The

device-managed variant is, unsurprisingly:

	void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)

Using GPIOs

===========

Setting Direction

-----------------

The first thing a driver must do with a GPIO is setting its direction. This is

done by invoking one of the gpiod_direction_*() functions:

	int gpiod_direction_input(struct gpio_desc *desc)

	int gpiod_direction_output(struct gpio_desc *desc, int value)

The return value is zero for success, else a negative errno. It should be

checked, since the get/set calls don't return errors and since misconfiguration

is possible. You should normally issue these calls from a task context. However,

for spinlock-safe GPIOs it is OK to use them before tasking is enabled, as part

of early board setup.

For output GPIOs, the value provided becomes the initial output value. This

helps avoid signal glitching during system startup.

A driver can also query the current direction of a GPIO:

	int gpiod_get_direction(const struct gpio_desc *desc)

This function will return either GPIOF_DIR_IN or GPIOF_DIR_OUT.

Be aware that there is no default direction for GPIOs. Therefore, **using a GPIO

without setting its direction first is illegal and will result in undefined

behavior!**

Spinlock-Safe GPIO Access

-------------------------

Most GPIO controllers can be accessed with memory read/write instructions. Those

don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ

handlers and similar contexts.

Use the following calls to access GPIOs from an atomic context:

	int gpiod_get_value(const struct gpio_desc *desc);

	void gpiod_set_value(struct gpio_desc *desc, int value);

The values are boolean, zero for low, nonzero for high. When reading the value

of an output pin, the value returned should be what's seen on the pin. That

won't always match the specified output value, because of issues including

open-drain signaling and output latencies.

The get/set calls do not return errors because "invalid GPIO" should have been

reported earlier from gpiod_direction_*(). However, note that not all platforms

can read the value of output pins; those that can't should always return zero.

Also, using these calls for GPIOs that can't safely be accessed without sleeping

(see below) is an error.

GPIO Access That May Sleep

--------------------------

Some GPIO controllers must be accessed using message based buses like I2C or

SPI. Commands to read or write those GPIO values require waiting to get to the

head of a queue to transmit a command and get its response. This requires

sleeping, which can't be done from inside IRQ handlers.

Platforms that support this type of GPIO distinguish them from other GPIOs by

returning nonzero from this call:

	int gpiod_cansleep(const struct gpio_desc *desc)

To access such GPIOs, a different set of accessors is defined:

	int gpiod_get_value_cansleep(const struct gpio_desc *desc)

	void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)

Accessing such GPIOs requires a context which may sleep, for example a threaded

IRQ handler, and those accessors must be used instead of spinlock-safe

accessors without the cansleep() name suffix.

Other than the fact that these accessors might sleep, and will work on GPIOs

that can't be accessed from hardIRQ handlers, these calls act the same as the

spinlock-safe calls.

Active-low State and Raw GPIO Values

------------------------------------

Device drivers like to manage the logical state of a GPIO, i.e. the value their

device will actually receive, no matter what lies between it and the GPIO line.

In some cases, it might make sense to control the actual GPIO line value. The

following set of calls ignore the active-low property of a GPIO and work on the

raw line value:

	int gpiod_get_raw_value(const struct gpio_desc *desc)

	void gpiod_set_raw_value(struct gpio_desc *desc, int value)

	int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)

	void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)

The active-low state of a GPIO can also be queried using the following call:

	int gpiod_is_active_low(const struct gpio_desc *desc)

Note that these functions should only be used with great moderation ; a driver

should not have to care about the physical line level.

GPIOs mapped to IRQs

--------------------

GPIO lines can quite often be used as IRQs. You can get the IRQ number

corresponding to a given GPIO using the following call:

	int gpiod_to_irq(const struct gpio_desc *desc)

It will return an IRQ number, or an negative errno code if the mapping can't be

done (most likely because that particular GPIO cannot be used as IRQ). It is an

unchecked error to use a GPIO that wasn't set up as an input using

gpiod_direction_input(), or to use an IRQ number that didn't originally come

from gpiod_to_irq(). gpiod_to_irq() is not allowed to sleep.

Non-error values returned from gpiod_to_irq() can be passed to request_irq() or

free_irq(). They will often be stored into IRQ resources for platform devices,

by the board-specific initialization code. Note that IRQ trigger options are

part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are system wakeup

capabilities.

Interacting With the Legacy GPIO Subsystem

==========================================

Many kernel subsystems still handle GPIOs using the legacy integer-based

interface. Although it is strongly encouraged to upgrade them to the safer

descriptor-based API, the following two functions allow you to convert a GPIO

descriptor into the GPIO integer namespace and vice-versa:

	int desc_to_gpio(const struct gpio_desc *desc)

	struct gpio_desc *gpio_to_desc(unsigned gpio)

The GPIO number returned by desc_to_gpio() can be safely used as long as the

GPIO descriptor has not been freed. All the same, a GPIO number passed to

gpio_to_desc() must have been properly acquired, and usage of the returned GPIO

descriptor is only possible after the GPIO number has been released.

Freeing a GPIO obtained by one API with the other API is forbidden and an

unchecked error.

GPIO Descriptor Driver Interface

================================

This document serves as a guide for GPIO chip drivers writers. Note that it

describes the new descriptor-based interface. For a description of the

deprecated integer-based GPIO interface please refer to gpio-legacy.txt.

Each GPIO controller driver needs to include the following header, which defines

the structures used to define a GPIO driver:

	#include <linux/gpio/driver.h>

Internal Representation of GPIOs

================================

Inside a GPIO driver, individual GPIOs are identified by their hardware number,

which is a unique number between 0 and n, n being the number of GPIOs managed by

the chip. This number is purely internal: the hardware number of a particular

GPIO descriptor is never made visible outside of the driver.

On top of this internal number, each GPIO also need to have a global number in

the integer GPIO namespace so that it can be used with the legacy GPIO

interface. Each chip must thus have a "base" number (which can be automatically

assigned), and for each GPIO the global number will be (base + hardware number).

Although the integer representation is considered deprecated, it still has many

users and thus needs to be maintained.

So for example one platform could use numbers 32-159 for GPIOs, with a

controller defining 128 GPIOs at a "base" of 32 ; while another platform 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.

Controller Drivers: gpio_chip

=============================

In the gpiolib framework each GPIO controller is packaged as a "struct

gpio_chip" (see linux/gpio/driver.h for its complete definition) with members

common to each controller of that type:

 - methods to establish GPIO direction

 - methods used to access GPIO values

 - method to return the IRQ number associated to a given GPIO

 - flag saying whether calls to its methods may sleep

 - optional debugfs dump method (showing extra state like pullup config)

 - optional base number (will be automatically assigned if omitted)

 - label for diagnostics and GPIOs mapping using platform data

The code implementing a gpio_chip should support multiple instances of the

controller, possibly using the driver model. That code will configure each

gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare;

use gpiochip_remove() when it is unavoidable.

Most often a gpio_chip is part of an instance-specific structure with state not

exposed by the GPIO interfaces, such as addressing, power management, and more.

Chips such as codecs will have complex non-GPIO state.

Any debugfs dump method should normally ignore signals which haven't been

requested as GPIOs. They can use gpiochip_is_requested(), which returns either

NULL or the label associated with that GPIO when it was requested.

Locking IRQ usage

-----------------

Input GPIOs can be used as IRQ signals. When this happens, a driver is requested

to mark the GPIO as being used as an IRQ:

	int gpiod_lock_as_irq(struct gpio_desc *desc)

This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock

is released:

	void gpiod_unlock_as_irq(struct gpio_desc *desc)

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.