| 1 |
GPIO Sysfs Interface for Userspace |
| 2 |
================================== |
| 3 |
|
| 4 |
.. warning:: |
| 5 |
This API is obsoleted by the chardev.rst and the ABI documentation has |
| 6 |
been moved to Documentation/ABI/obsolete/sysfs-gpio. |
| 7 |
|
| 8 |
New developments should use the chardev.rst, and existing developments are |
| 9 |
encouraged to migrate as soon as possible, as this API will be removed |
| 10 |
in the future. |
| 11 |
|
| 12 |
This interface will continue to be maintained for the migration period, |
| 13 |
but new features will only be added to the new API. |
| 14 |
|
| 15 |
The obsolete sysfs ABI |
| 16 |
---------------------- |
| 17 |
Platforms which use the "gpiolib" implementors framework may choose to |
| 18 |
configure a sysfs user interface to GPIOs. This is different from the |
| 19 |
debugfs interface, since it provides control over GPIO direction and |
| 20 |
value instead of just showing a gpio state summary. Plus, it could be |
| 21 |
present on production systems without debugging support. |
| 22 |
|
| 23 |
Given appropriate hardware documentation for the system, userspace could |
| 24 |
know for example that GPIO #23 controls the write protect line used to |
| 25 |
protect boot loader segments in flash memory. System upgrade procedures |
| 26 |
may need to temporarily remove that protection, first importing a GPIO, |
| 27 |
then changing its output state, then updating the code before re-enabling |
| 28 |
the write protection. In normal use, GPIO #23 would never be touched, |
| 29 |
and the kernel would have no need to know about it. |
| 30 |
|
| 31 |
Again depending on appropriate hardware documentation, on some systems |
| 32 |
userspace GPIO can be used to determine system configuration data that |
| 33 |
standard kernels won't know about. And for some tasks, simple userspace |
| 34 |
GPIO drivers could be all that the system really needs. |
| 35 |
|
| 36 |
.. note:: |
| 37 |
Do NOT abuse sysfs to control hardware that has proper kernel drivers. |
| 38 |
Please read Documentation/driver-api/gpio/drivers-on-gpio.rst |
| 39 |
to avoid reinventing kernel wheels in userspace. |
| 40 |
|
| 41 |
I MEAN IT. REALLY. |
| 42 |
|
| 43 |
Paths in Sysfs |
| 44 |
-------------- |
| 45 |
There are three kinds of entries in /sys/class/gpio: |
| 46 |
|
| 47 |
- Control interfaces used to get userspace control over GPIOs; |
| 48 |
|
| 49 |
- GPIOs themselves; and |
| 50 |
|
| 51 |
- GPIO controllers ("gpio_chip" instances). |
| 52 |
|
| 53 |
That's in addition to standard files including the "device" symlink. |
| 54 |
|
| 55 |
The control interfaces are write-only: |
| 56 |
|
| 57 |
/sys/class/gpio/ |
| 58 |
|
| 59 |
"export" ... |
| 60 |
Userspace may ask the kernel to export control of |
| 61 |
a GPIO to userspace by writing its number to this file. |
| 62 |
|
| 63 |
Example: "echo 19 > export" will create a "gpio19" node |
| 64 |
for GPIO #19, if that's not requested by kernel code. |
| 65 |
|
| 66 |
"unexport" ... |
| 67 |
Reverses the effect of exporting to userspace. |
| 68 |
|
| 69 |
Example: "echo 19 > unexport" will remove a "gpio19" |
| 70 |
node exported using the "export" file. |
| 71 |
|
| 72 |
GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42) |
| 73 |
and have the following read/write attributes: |
| 74 |
|
| 75 |
/sys/class/gpio/gpioN/ |
| 76 |
|
| 77 |
"direction" ... |
| 78 |
reads as either "in" or "out". This value may |
| 79 |
normally be written. Writing as "out" defaults to |
| 80 |
initializing the value as low. To ensure glitch free |
| 81 |
operation, values "low" and "high" may be written to |
| 82 |
configure the GPIO as an output with that initial value. |
| 83 |
|
| 84 |
Note that this attribute *will not exist* if the kernel |
| 85 |
doesn't support changing the direction of a GPIO, or |
| 86 |
it was exported by kernel code that didn't explicitly |
| 87 |
allow userspace to reconfigure this GPIO's direction. |
| 88 |
|
| 89 |
"value" ... |
| 90 |
reads as either 0 (inactive) or 1 (active). If the GPIO |
| 91 |
is configured as an output, this value may be written; |
| 92 |
any nonzero value is treated as active. |
| 93 |
|
| 94 |
If the pin can be configured as interrupt-generating interrupt |
| 95 |
and if it has been configured to generate interrupts (see the |
| 96 |
description of "edge"), you can poll(2) on that file and |
| 97 |
poll(2) will return whenever the interrupt was triggered. If |
| 98 |
you use poll(2), set the events POLLPRI and POLLERR. If you |
| 99 |
use select(2), set the file descriptor in exceptfds. After |
| 100 |
poll(2) returns, use pread(2) to read the value at offset |
| 101 |
zero. Alternatively, either lseek(2) to the beginning of the |
| 102 |
sysfs file and read the new value or close the file and |
| 103 |
re-open it to read the value. |
| 104 |
|
| 105 |
"edge" ... |
| 106 |
reads as either "none", "rising", "falling", or |
| 107 |
"both". Write these strings to select the signal edge(s) |
| 108 |
that will make poll(2) on the "value" file return. |
| 109 |
|
| 110 |
This file exists only if the pin can be configured as an |
| 111 |
interrupt generating input pin. |
| 112 |
|
| 113 |
"active_low" ... |
| 114 |
reads as either 0 (false) or 1 (true). Write |
| 115 |
any nonzero value to invert the value attribute both |
| 116 |
for reading and writing. Existing and subsequent |
| 117 |
poll(2) support configuration via the edge attribute |
| 118 |
for "rising" and "falling" edges will follow this |
| 119 |
setting. |
| 120 |
|
| 121 |
GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the |
| 122 |
controller implementing GPIOs starting at #42) and have the following |
| 123 |
read-only attributes: |
| 124 |
|
| 125 |
/sys/class/gpio/gpiochipN/ |
| 126 |
|
| 127 |
"base" ... |
| 128 |
same as N, the first GPIO managed by this chip |
| 129 |
|
| 130 |
"label" ... |
| 131 |
provided for diagnostics (not always unique) |
| 132 |
|
| 133 |
"ngpio" ... |
| 134 |
how many GPIOs this manages (N to N + ngpio - 1) |
| 135 |
|
| 136 |
Board documentation should in most cases cover what GPIOs are used for |
| 137 |
what purposes. However, those numbers are not always stable; GPIOs on |
| 138 |
a daughtercard might be different depending on the base board being used, |
| 139 |
or other cards in the stack. In such cases, you may need to use the |
| 140 |
gpiochip nodes (possibly in conjunction with schematics) to determine |
| 141 |
the correct GPIO number to use for a given signal. |
| 142 |
|
| 143 |
|
| 144 |
Exporting from Kernel code |
| 145 |
-------------------------- |
| 146 |
Kernel code can explicitly manage exports of GPIOs which have already been |
| 147 |
requested using gpio_request():: |
| 148 |
|
| 149 |
/* export the GPIO to userspace */ |
| 150 |
int gpiod_export(struct gpio_desc *desc, bool direction_may_change); |
| 151 |
|
| 152 |
/* reverse gpiod_export() */ |
| 153 |
void gpiod_unexport(struct gpio_desc *desc); |
| 154 |
|
| 155 |
/* create a sysfs link to an exported GPIO node */ |
| 156 |
int gpiod_export_link(struct device *dev, const char *name, |
| 157 |
struct gpio_desc *desc); |
| 158 |
|
| 159 |
After a kernel driver requests a GPIO, it may only be made available in |
| 160 |
the sysfs interface by gpiod_export(). The driver can control whether the |
| 161 |
signal direction may change. This helps drivers prevent userspace code |
| 162 |
from accidentally clobbering important system state. |
| 163 |
|
| 164 |
This explicit exporting can help with debugging (by making some kinds |
| 165 |
of experiments easier), or can provide an always-there interface that's |
| 166 |
suitable for documenting as part of a board support package. |
| 167 |
|
| 168 |
After the GPIO has been exported, gpiod_export_link() allows creating |
| 169 |
symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can |
| 170 |
use this to provide the interface under their own device in sysfs with |
| 171 |
a descriptive name. |