1 GPIO Sysfs Interface for Userspace
2 ==================================
3
4 .. warning::
5 This API is obsoleted by the chardev.rst an
6 been moved to Documentation/ABI/obsolete/sy
7
8 New developments should use the chardev.rst
9 encouraged to migrate as soon as possible,
10 in the future.
11
12 This interface will continue to be maintain
13 but new features will only be added to the
14
15 The obsolete sysfs ABI
16 ----------------------
17 Platforms which use the "gpiolib" implementors
18 configure a sysfs user interface to GPIOs. Thi
19 debugfs interface, since it provides control o
20 value instead of just showing a gpio state sum
21 present on production systems without debuggin
22
23 Given appropriate hardware documentation for t
24 know for example that GPIO #23 controls the wr
25 protect boot loader segments in flash memory.
26 may need to temporarily remove that protection
27 then changing its output state, then updating
28 the write protection. In normal use, GPIO #23
29 and the kernel would have no need to know abou
30
31 Again depending on appropriate hardware docume
32 userspace GPIO can be used to determine system
33 standard kernels won't know about. And for som
34 GPIO drivers could be all that the system real
35
36 .. note::
37 Do NOT abuse sysfs to control hardware that
38 Please read Documentation/driver-api/gpio/d
39 to avoid reinventing kernel wheels in users
40
41 I MEAN IT. REALLY.
42
43 Paths in Sysfs
44 --------------
45 There are three kinds of entries in /sys/class
46
47 - Control interfaces used to get userspa
48
49 - GPIOs themselves; and
50
51 - GPIO controllers ("gpio_chip" instance
52
53 That's in addition to standard files including
54
55 The control interfaces are write-only:
56
57 /sys/class/gpio/
58
59 "export" ...
60 Userspace may ask the kernel t
61 a GPIO to userspace by writing
62
63 Example: "echo 19 > export" w
64 for GPIO #19, if that's not re
65
66 "unexport" ...
67 Reverses the effect of exporti
68
69 Example: "echo 19 > unexport"
70 node exported using the "expor
71
72 GPIO signals have paths like /sys/class/gpio/g
73 and have the following read/write attributes:
74
75 /sys/class/gpio/gpioN/
76
77 "direction" ...
78 reads as either "in" or "out".
79 normally be written. Writing a
80 initializing the value as low.
81 operation, values "low" and "h
82 configure the GPIO as an outpu
83
84 Note that this attribute *will
85 doesn't support changing the d
86 it was exported by kernel code
87 allow userspace to reconfigure
88
89 "value" ...
90 reads as either 0 (inactive) o
91 is configured as an output, th
92 any nonzero value is treated a
93
94 If the pin can be configured a
95 and if it has been configured
96 description of "edge"), you ca
97 poll(2) will return whenever t
98 you use poll(2), set the event
99 use select(2), set the file de
100 poll(2) returns, use pread(2)
101 zero. Alternatively, either ls
102 sysfs file and read the new va
103 re-open it to read the value.
104
105 "edge" ...
106 reads as either "none", "risin
107 "both". Write these strings to
108 that will make poll(2) on the
109
110 This file exists only if the p
111 interrupt generating input pin
112
113 "active_low" ...
114 reads as either 0 (false) or 1
115 any nonzero value to invert th
116 for reading and writing. Exist
117 poll(2) support configuration
118 for "rising" and "falling" edg
119 setting.
120
121 GPIO controllers have paths like /sys/class/gp
122 controller implementing GPIOs starting at #42)
123 read-only attributes:
124
125 /sys/class/gpio/gpiochipN/
126
127 "base" ...
128 same as N, the first GPIO mana
129
130 "label" ...
131 provided for diagnostics (not
132
133 "ngpio" ...
134 how many GPIOs this manages (N
135
136 Board documentation should in most cases cover
137 what purposes. However, those numbers are not
138 a daughtercard might be different depending on
139 or other cards in the stack. In such cases, yo
140 gpiochip nodes (possibly in conjunction with s
141 the correct GPIO number to use for a given sig
142
143
144 Exporting from Kernel code
145 --------------------------
146 Kernel code can explicitly manage exports of G
147 requested using gpio_request()::
148
149 /* export the GPIO to userspace */
150 int gpiod_export(struct gpio_desc *des
151
152 /* reverse gpiod_export() */
153 void gpiod_unexport(struct gpio_desc *
154
155 /* create a sysfs link to an exported
156 int gpiod_export_link(struct device *d
157 struct gpio_desc *desc);
158
159 After a kernel driver requests a GPIO, it may
160 the sysfs interface by gpiod_export(). The dri
161 signal direction may change. This helps driver
162 from accidentally clobbering important system
163
164 This explicit exporting can help with debuggin
165 of experiments easier), or can provide an alwa
166 suitable for documenting as part of a board su
167
168 After the GPIO has been exported, gpiod_export
169 symlinks from elsewhere in sysfs to the GPIO s
170 use this to provide the interface under their
171 a descriptive name.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.