@ -0,0 +1,54 @@ | |||
* TI MMC host controller for OMAP1 and 2420 | |||
The MMC Host Controller on TI OMAP1 and 2420 family provides | |||
an interface for MMC, SD, and SDIO types of memory cards. | |||
This file documents differences between the core properties described | |||
by mmc.txt and the properties used by the omap mmc driver. | |||
Note that this driver will not work with omap2430 or later omaps, | |||
please see the omap hsmmc driver for the current omaps. | |||
Required properties: | |||
- compatible: Must be "ti,omap2420-mmc", for OMAP2420 controllers | |||
- ti,hwmods: For 2420, must be "msdi<n>", where n is controller | |||
instance starting 1 | |||
Examples: | |||
msdi1: mmc@4809c000 { | |||
compatible = "ti,omap2420-mmc"; | |||
ti,hwmods = "msdi1"; | |||
reg = <0x4809c000 0x80>; | |||
interrupts = <83>; | |||
dmas = <&sdma 61 &sdma 62>; | |||
dma-names = "tx", "rx"; | |||
}; | |||
* TI MMC host controller for OMAP1 and 2420 | |||
The MMC Host Controller on TI OMAP1 and 2420 family provides | |||
an interface for MMC, SD, and SDIO types of memory cards. | |||
This file documents differences between the core properties described | |||
by mmc.txt and the properties used by the omap mmc driver. | |||
Note that this driver will not work with omap2430 or later omaps, | |||
please see the omap hsmmc driver for the current omaps. | |||
Required properties: | |||
- compatible: Must be "ti,omap2420-mmc", for OMAP2420 controllers | |||
- ti,hwmods: For 2420, must be "msdi<n>", where n is controller | |||
instance starting 1 | |||
Examples: | |||
msdi1: mmc@4809c000 { | |||
compatible = "ti,omap2420-mmc"; | |||
ti,hwmods = "msdi1"; | |||
reg = <0x4809c000 0x80>; | |||
interrupts = <83>; | |||
dmas = <&sdma 61 &sdma 62>; | |||
dma-names = "tx", "rx"; | |||
}; | |||
@ -0,0 +1,17 @@ | |||
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 | |||
Example: | |||
rng@f9bff000 { | |||
compatible = "qcom,prng"; | |||
reg = <0xf9bff000 0x200>; | |||
clocks = <&clock GCC_PRNG_AHB_CLK>; | |||
clock-names = "core"; | |||
}; |
@ -1,5 +0,0 @@ | |||
NVIDIA Tegra 2 SPI device | |||
Required properties: | |||
- compatible : should be "nvidia,tegra20-spi". | |||
- gpios : should specify GPIOs used for chipselect. |
@ -0,0 +1,14 @@ | |||
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 | |||
- How to write a GPIO driver | |||
board.txt | |||
- How to assign GPIOs to a consumer device and a function | |||
sysfs.txt | |||
- Information about the GPIO sysfs interface | |||
gpio-legacy.txt | |||
- Historical documentation of the deprecated GPIO integer interface |
@ -0,0 +1,115 @@ | |||
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. |
@ -0,0 +1,197 @@ | |||
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. |
@ -0,0 +1,75 @@ | |||
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) |
@ -0,0 +1,119 @@ | |||
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. |
@ -0,0 +1,155 @@ | |||
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). | |||
That's in addition to standard files including the "device" symlink. | |||
The control interfaces are write-only: | |||
/sys/class/gpio/ | |||
"export" ... Userspace may ask the kernel to export control of | |||
a GPIO to userspace by writing its number to this file. | |||
Example: "echo 19 > export" will create a "gpio19" node | |||
for GPIO #19, if that's not requested by kernel code. | |||
"unexport" ... Reverses the effect of exporting to userspace. | |||
Example: "echo 19 > unexport" will remove a "gpio19" | |||
node exported using the "export" file. | |||
GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42) | |||
and have the following read/write attributes: | |||
/sys/class/gpio/gpioN/ | |||
"direction" ... reads as either "in" or "out". This value may | |||
normally be written. Writing as "out" defaults to | |||
initializing the value as low. To ensure glitch free | |||
operation, values "low" and "high" may be written to | |||
configure the GPIO as an output with that initial value. | |||
Note that this attribute *will not exist* if the kernel | |||
doesn't support changing the direction of a GPIO, or | |||
it was exported by kernel code that didn't explicitly | |||
allow userspace to reconfigure this GPIO's direction. | |||
"value" ... reads as either 0 (low) or 1 (high). If the GPIO | |||
is configured as an output, this value may be written; | |||
any nonzero value is treated as high. | |||
If the pin can be configured as interrupt-generating interrupt | |||
and if it has been configured to generate interrupts (see the | |||
description of "edge"), you can poll(2) on that file and | |||
poll(2) will return whenever the interrupt was triggered. If | |||
you use poll(2), set the events POLLPRI and POLLERR. If you | |||
use select(2), set the file descriptor in exceptfds. After | |||
poll(2) returns, either lseek(2) to the beginning of the sysfs | |||
file and read the new value or close the file and re-open it | |||
to read the value. | |||
"edge" ... reads as either "none", "rising", "falling", or | |||
"both". Write these strings to select the signal edge(s) | |||
that will make poll(2) on the "value" file return. | |||
This file exists only if the pin can be configured as an | |||
interrupt generating input pin. | |||
"active_low" ... reads as either 0 (false) or 1 (true). Write | |||
any nonzero value to invert the value attribute both | |||
for reading and writing. Existing and subsequent | |||
poll(2) support configuration via the edge attribute | |||
for "rising" and "falling" edges will follow this | |||
setting. | |||
GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the | |||
controller implementing GPIOs starting at #42) and have the following | |||
read-only attributes: | |||
/sys/class/gpio/gpiochipN/ | |||
"base" ... same as N, the first GPIO managed by this chip | |||
"label" ... provided for diagnostics (not always unique) | |||
"ngpio" ... how many GPIOs this manges (N to N + ngpio - 1) | |||
Board documentation should in most cases cover what GPIOs are used for | |||
what purposes. However, those numbers are not always stable; GPIOs on | |||
a daughtercard might be different depending on the base board being used, | |||
or other cards in the stack. In such cases, you may need to use the | |||
gpiochip nodes (possibly in conjunction with schematics) to determine | |||
the correct GPIO number to use for a given signal. | |||
Exporting from Kernel code | |||
-------------------------- | |||
Kernel code can explicitly manage exports of GPIOs which have already been | |||
requested using gpio_request(): | |||
/* export the GPIO to userspace */ | |||
int gpiod_export(struct gpio_desc *desc, bool direction_may_change); | |||
/* reverse gpio_export() */ | |||
void gpiod_unexport(struct gpio_desc *desc); | |||
/* create a sysfs link to an exported GPIO node */ | |||
int gpiod_export_link(struct device *dev, const char *name, | |||
struct gpio_desc *desc); | |||
/* change the polarity of a GPIO node in sysfs */ | |||
int gpiod_sysfs_set_active_low(struct gpio_desc *desc, int value); | |||
After a kernel driver requests a GPIO, it may only be made available in | |||
the sysfs interface by gpiod_export(). The driver can control whether the | |||
signal direction may change. This helps drivers prevent userspace code | |||
from accidentally clobbering important system state. | |||
This explicit exporting can help with debugging (by making some kinds | |||
of experiments easier), or can provide an always-there interface that's | |||
suitable for documenting as part of a board support package. | |||
After the GPIO has been exported, gpiod_export_link() allows creating | |||
symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can | |||
use this to provide the interface under their own device in sysfs with | |||
a descriptive name. | |||
Drivers can use gpiod_sysfs_set_active_low() to hide GPIO line polarity | |||
differences between boards from user space. Polarity change can be done both | |||
before and after gpiod_export(), and previously enabled poll(2) support for | |||
either rising or falling edge will be reconfigured to follow this setting. |