Commit 45b45393 authored by Greg Kroah-Hartman's avatar Greg Kroah-Hartman

Merge 3.13-rc2 into driver-core-next

We want those fixes in here as well.
Signed-off-by: default avatarGreg Kroah-Hartman <>
parents 44c3eea6 dc1ccc48
......@@ -196,13 +196,6 @@ chmod 0644 /dev/cpu/microcode
as root before you can use this. You'll probably also want to
get the user-space microcode_ctl utility to use with this.
If you are running v0.1.17 or earlier, you should upgrade to
version v0.99.0 or higher. Running old versions may cause problems
with programs using shared memory.
udev is a userspace application for populating /dev dynamically with
......@@ -366,10 +359,6 @@ Intel P6 microcode
o <>
o <>
o <>
......@@ -58,7 +58,7 @@
<sect1><title>Wait queues and Wake events</title>
<sect1><title>High-resolution timers</title>
I2C for OMAP platforms
Required properties :
- compatible : Must be "ti,omap3-i2c" or "ti,omap4-i2c"
- compatible : Must be "ti,omap2420-i2c", "ti,omap2430-i2c", "ti,omap3-i2c"
or "ti,omap4-i2c"
- ti,hwmods : Must be "i2c<n>", n being the instance number (1-based)
- #address-cells = <1>;
- #size-cells = <0>;
Qualcomm MSM pseudo random number generator.
Required properties:
- compatible : should be "qcom,prng"
- reg : specifies base physical address and size of the registers map
- clocks : phandle to clock-controller plus clock-specifier pair
- clock-names : "core" clocks all registers, FIFO and circuits in PRNG IP block
rng@f9bff000 {
compatible = "qcom,prng";
reg = <0xf9bff000 0x200>;
clocks = <&clock GCC_PRNG_AHB_CLK>;
clock-names = "core";
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 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)
- 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
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
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
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
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
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
GPIO Sysfs Interface for Userspace
Platforms which use the "gpiolib" implementors framework may choose to
configure a sysfs user interface to GPIOs. This is different from the
debugfs interface, since it provides control over GPIO direction and
value instead of just showing a gpio state summary. Plus, it could be
present on production systems without debugging support.
Given appropriate hardware documentation for the system, userspace could
know for example that GPIO #23 controls the write protect line used to
protect boot loader segments in flash memory. System upgrade procedures
may need to temporarily remove that protection, first importing a GPIO,
then changing its output state, then updating the code before re-enabling
the write protection. In normal use, GPIO #23 would never be touched,
and the kernel would have no need to know about it.
Again depending on appropriate hardware documentation, on some systems
userspace GPIO can be used to determine system configuration data that
standard kernels won't know about. And for some tasks, simple userspace
GPIO drivers could be all that the system really needs.
Note that standard kernel drivers exist for common "LEDs and Buttons"
GPIO tasks: "leds-gpio" and "gpio_keys", respectively. Use those
instead of talking directly to the GPIOs; they integrate with kernel
frameworks better than your userspace code could.
Paths in Sysfs
There are three kinds of entry in /sys/class/gpio:
- Control interfaces used to get userspace control over GPIOs;
- GPIOs themselves; and
- GPIO controllers ("gpio_chip" instances).