0001 GPIO Sysfs Interface for Userspace
0002 ==================================
0003
0004 .. warning::
0005
0006 THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
0007 Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
0008 ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
0009 NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
0010
0011 Refer to the examples in tools/gpio/* for an introduction to the new
0012 character device ABI. Also see the userspace header in
0013 include/uapi/linux/gpio.h
0014
0015 The deprecated sysfs ABI
0016 ------------------------
0017 Platforms which use the "gpiolib" implementors framework may choose to
0018 configure a sysfs user interface to GPIOs. This is different from the
0019 debugfs interface, since it provides control over GPIO direction and
0020 value instead of just showing a gpio state summary. Plus, it could be
0021 present on production systems without debugging support.
0022
0023 Given appropriate hardware documentation for the system, userspace could
0024 know for example that GPIO #23 controls the write protect line used to
0025 protect boot loader segments in flash memory. System upgrade procedures
0026 may need to temporarily remove that protection, first importing a GPIO,
0027 then changing its output state, then updating the code before re-enabling
0028 the write protection. In normal use, GPIO #23 would never be touched,
0029 and the kernel would have no need to know about it.
0030
0031 Again depending on appropriate hardware documentation, on some systems
0032 userspace GPIO can be used to determine system configuration data that
0033 standard kernels won't know about. And for some tasks, simple userspace
0034 GPIO drivers could be all that the system really needs.
0035
0036 DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS.
0037 PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst
0038 TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY.
0039
0040 Paths in Sysfs
0041 --------------
0042 There are three kinds of entries in /sys/class/gpio:
0043
0044 - Control interfaces used to get userspace control over GPIOs;
0045
0046 - GPIOs themselves; and
0047
0048 - GPIO controllers ("gpio_chip" instances).
0049
0050 That's in addition to standard files including the "device" symlink.
0051
0052 The control interfaces are write-only:
0053
0054 /sys/class/gpio/
0055
0056 "export" ...
0057 Userspace may ask the kernel to export control of
0058 a GPIO to userspace by writing its number to this file.
0059
0060 Example: "echo 19 > export" will create a "gpio19" node
0061 for GPIO #19, if that's not requested by kernel code.
0062
0063 "unexport" ...
0064 Reverses the effect of exporting to userspace.
0065
0066 Example: "echo 19 > unexport" will remove a "gpio19"
0067 node exported using the "export" file.
0068
0069 GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42)
0070 and have the following read/write attributes:
0071
0072 /sys/class/gpio/gpioN/
0073
0074 "direction" ...
0075 reads as either "in" or "out". This value may
0076 normally be written. Writing as "out" defaults to
0077 initializing the value as low. To ensure glitch free
0078 operation, values "low" and "high" may be written to
0079 configure the GPIO as an output with that initial value.
0080
0081 Note that this attribute *will not exist* if the kernel
0082 doesn't support changing the direction of a GPIO, or
0083 it was exported by kernel code that didn't explicitly
0084 allow userspace to reconfigure this GPIO's direction.
0085
0086 "value" ...
0087 reads as either 0 (low) or 1 (high). If the GPIO
0088 is configured as an output, this value may be written;
0089 any nonzero value is treated as high.
0090
0091 If the pin can be configured as interrupt-generating interrupt
0092 and if it has been configured to generate interrupts (see the
0093 description of "edge"), you can poll(2) on that file and
0094 poll(2) will return whenever the interrupt was triggered. If
0095 you use poll(2), set the events POLLPRI and POLLERR. If you
0096 use select(2), set the file descriptor in exceptfds. After
0097 poll(2) returns, either lseek(2) to the beginning of the sysfs
0098 file and read the new value or close the file and re-open it
0099 to read the value.
0100
0101 "edge" ...
0102 reads as either "none", "rising", "falling", or
0103 "both". Write these strings to select the signal edge(s)
0104 that will make poll(2) on the "value" file return.
0105
0106 This file exists only if the pin can be configured as an
0107 interrupt generating input pin.
0108
0109 "active_low" ...
0110 reads as either 0 (false) or 1 (true). Write
0111 any nonzero value to invert the value attribute both
0112 for reading and writing. Existing and subsequent
0113 poll(2) support configuration via the edge attribute
0114 for "rising" and "falling" edges will follow this
0115 setting.
0116
0117 GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the
0118 controller implementing GPIOs starting at #42) and have the following
0119 read-only attributes:
0120
0121 /sys/class/gpio/gpiochipN/
0122
0123 "base" ...
0124 same as N, the first GPIO managed by this chip
0125
0126 "label" ...
0127 provided for diagnostics (not always unique)
0128
0129 "ngpio" ...
0130 how many GPIOs this manages (N to N + ngpio - 1)
0131
0132 Board documentation should in most cases cover what GPIOs are used for
0133 what purposes. However, those numbers are not always stable; GPIOs on
0134 a daughtercard might be different depending on the base board being used,
0135 or other cards in the stack. In such cases, you may need to use the
0136 gpiochip nodes (possibly in conjunction with schematics) to determine
0137 the correct GPIO number to use for a given signal.
0138
0139
0140 Exporting from Kernel code
0141 --------------------------
0142 Kernel code can explicitly manage exports of GPIOs which have already been
0143 requested using gpio_request()::
0144
0145 /* export the GPIO to userspace */
0146 int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
0147
0148 /* reverse gpio_export() */
0149 void gpiod_unexport(struct gpio_desc *desc);
0150
0151 /* create a sysfs link to an exported GPIO node */
0152 int gpiod_export_link(struct device *dev, const char *name,
0153 struct gpio_desc *desc);
0154
0155 After a kernel driver requests a GPIO, it may only be made available in
0156 the sysfs interface by gpiod_export(). The driver can control whether the
0157 signal direction may change. This helps drivers prevent userspace code
0158 from accidentally clobbering important system state.
0159
0160 This explicit exporting can help with debugging (by making some kinds
0161 of experiments easier), or can provide an always-there interface that's
0162 suitable for documenting as part of a board support package.
0163
0164 After the GPIO has been exported, gpiod_export_link() allows creating
0165 symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can
0166 use this to provide the interface under their own device in sysfs with
0167 a descriptive name.
