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