| 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.
|