Commit | Line | Data |
---|---|---|
fd8e198c AC |
1 | GPIO Sysfs Interface for Userspace |
2 | ================================== | |
3 | ||
7358a821 MCC |
4 | .. warning:: |
5 | ||
6 | THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO | |
7 | Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS | |
8 | ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL | |
9 | NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. | |
adbf0299 LW |
10 | |
11 | Refer to the examples in tools/gpio/* for an introduction to the new | |
12 | character device ABI. Also see the userspace header in | |
13 | include/uapi/linux/gpio.h | |
14 | ||
15 | The deprecated sysfs ABI | |
16 | ------------------------ | |
fd8e198c AC |
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 | ||
0ea1563b | 36 | DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS. |
4784e710 JN |
37 | PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst |
38 | TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY. | |
fd8e198c AC |
39 | |
40 | Paths in Sysfs | |
41 | -------------- | |
0ea1563b | 42 | There are three kinds of entries in /sys/class/gpio: |
fd8e198c AC |
43 | |
44 | - Control interfaces used to get userspace control over GPIOs; | |
45 | ||
46 | - GPIOs themselves; and | |
47 | ||
48 | - GPIO controllers ("gpio_chip" instances). | |
49 | ||
50 | That's in addition to standard files including the "device" symlink. | |
51 | ||
52 | The control interfaces are write-only: | |
53 | ||
54 | /sys/class/gpio/ | |
55 | ||
7358a821 MCC |
56 | "export" ... |
57 | Userspace may ask the kernel to export control of | |
fd8e198c AC |
58 | a GPIO to userspace by writing its number to this file. |
59 | ||
60 | Example: "echo 19 > export" will create a "gpio19" node | |
61 | for GPIO #19, if that's not requested by kernel code. | |
62 | ||
7358a821 MCC |
63 | "unexport" ... |
64 | Reverses the effect of exporting to userspace. | |
fd8e198c AC |
65 | |
66 | Example: "echo 19 > unexport" will remove a "gpio19" | |
67 | node exported using the "export" file. | |
68 | ||
69 | GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42) | |
70 | and have the following read/write attributes: | |
71 | ||
72 | /sys/class/gpio/gpioN/ | |
73 | ||
7358a821 MCC |
74 | "direction" ... |
75 | reads as either "in" or "out". This value may | |
fd8e198c AC |
76 | normally be written. Writing as "out" defaults to |
77 | initializing the value as low. To ensure glitch free | |
78 | operation, values "low" and "high" may be written to | |
79 | configure the GPIO as an output with that initial value. | |
80 | ||
81 | Note that this attribute *will not exist* if the kernel | |
82 | doesn't support changing the direction of a GPIO, or | |
83 | it was exported by kernel code that didn't explicitly | |
84 | allow userspace to reconfigure this GPIO's direction. | |
85 | ||
7358a821 MCC |
86 | "value" ... |
87 | reads as either 0 (low) or 1 (high). If the GPIO | |
fd8e198c AC |
88 | is configured as an output, this value may be written; |
89 | any nonzero value is treated as high. | |
90 | ||
91 | If the pin can be configured as interrupt-generating interrupt | |
92 | and if it has been configured to generate interrupts (see the | |
93 | description of "edge"), you can poll(2) on that file and | |
94 | poll(2) will return whenever the interrupt was triggered. If | |
95 | you use poll(2), set the events POLLPRI and POLLERR. If you | |
96 | use select(2), set the file descriptor in exceptfds. After | |
97 | poll(2) returns, either lseek(2) to the beginning of the sysfs | |
98 | file and read the new value or close the file and re-open it | |
99 | to read the value. | |
100 | ||
7358a821 MCC |
101 | "edge" ... |
102 | reads as either "none", "rising", "falling", or | |
fd8e198c AC |
103 | "both". Write these strings to select the signal edge(s) |
104 | that will make poll(2) on the "value" file return. | |
105 | ||
106 | This file exists only if the pin can be configured as an | |
107 | interrupt generating input pin. | |
108 | ||
7358a821 MCC |
109 | "active_low" ... |
110 | reads as either 0 (false) or 1 (true). Write | |
fd8e198c AC |
111 | any nonzero value to invert the value attribute both |
112 | for reading and writing. Existing and subsequent | |
113 | poll(2) support configuration via the edge attribute | |
114 | for "rising" and "falling" edges will follow this | |
115 | setting. | |
116 | ||
117 | GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the | |
118 | controller implementing GPIOs starting at #42) and have the following | |
119 | read-only attributes: | |
120 | ||
121 | /sys/class/gpio/gpiochipN/ | |
122 | ||
7358a821 MCC |
123 | "base" ... |
124 | same as N, the first GPIO managed by this chip | |
fd8e198c | 125 | |
7358a821 MCC |
126 | "label" ... |
127 | provided for diagnostics (not always unique) | |
fd8e198c | 128 | |
7358a821 MCC |
129 | "ngpio" ... |
130 | how many GPIOs this manages (N to N + ngpio - 1) | |
fd8e198c AC |
131 | |
132 | Board documentation should in most cases cover what GPIOs are used for | |
133 | what purposes. However, those numbers are not always stable; GPIOs on | |
134 | a daughtercard might be different depending on the base board being used, | |
135 | or other cards in the stack. In such cases, you may need to use the | |
136 | gpiochip nodes (possibly in conjunction with schematics) to determine | |
137 | the correct GPIO number to use for a given signal. | |
138 | ||
139 | ||
140 | Exporting from Kernel code | |
141 | -------------------------- | |
142 | Kernel code can explicitly manage exports of GPIOs which have already been | |
7358a821 | 143 | requested using gpio_request():: |
fd8e198c AC |
144 | |
145 | /* export the GPIO to userspace */ | |
146 | int gpiod_export(struct gpio_desc *desc, bool direction_may_change); | |
147 | ||
d74e3166 | 148 | /* reverse gpiod_export() */ |
fd8e198c AC |
149 | void gpiod_unexport(struct gpio_desc *desc); |
150 | ||
151 | /* create a sysfs link to an exported GPIO node */ | |
152 | int gpiod_export_link(struct device *dev, const char *name, | |
153 | struct gpio_desc *desc); | |
154 | ||
fd8e198c AC |
155 | After a kernel driver requests a GPIO, it may only be made available in |
156 | the sysfs interface by gpiod_export(). The driver can control whether the | |
157 | signal direction may change. This helps drivers prevent userspace code | |
158 | from accidentally clobbering important system state. | |
159 | ||
160 | This explicit exporting can help with debugging (by making some kinds | |
161 | of experiments easier), or can provide an always-there interface that's | |
162 | suitable for documenting as part of a board support package. | |
163 | ||
164 | After the GPIO has been exported, gpiod_export_link() allows creating | |
165 | symlinks from elsewhere in sysfs to the GPIO sysfs node. Drivers can | |
166 | use this to provide the interface under their own device in sysfs with | |
167 | a descriptive name. |