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