projects/linux·blob master · refs

245 lines · 6.6 KiB

1=============
2uinput module
3=============
4
5Introduction
6============
7
8uinput is a kernel module that makes it possible to emulate input devices
9from userspace. By writing to /dev/uinput (or /dev/input/uinput) device, a
10process can create a virtual input device with specific capabilities. Once
11this virtual device is created, the process can send events through it,
12that will be delivered to userspace and in-kernel consumers.
13
14Interface
15=========
16
17::
18
19 linux/uinput.h
20
21The uinput header defines ioctls to create, set up, and destroy virtual
22devices.
23
24libevdev
25========
26
27libevdev is a wrapper library for evdev devices that provides interfaces to
28create uinput devices and send events. libevdev is less error-prone than
29accessing uinput directly, and should be considered for new software.
30
31For examples and more information about libevdev:
32https://www.freedesktop.org/software/libevdev/doc/latest/
33
34Examples
35========
36
37Keyboard events
38---------------
39
40This first example shows how to create a new virtual device, and how to
41send a key event. All default imports and error handlers were removed for
42the sake of simplicity.
43
44.. code-block:: c
45
46 #include <linux/uinput.h>
47
48 void emit(int fd, int type, int code, int val)
49 {
50 struct input_event ie;
51
52 ie.type = type;
53 ie.code = code;
54 ie.value = val;
55 /* timestamp values below are ignored */
56 ie.time.tv_sec = 0;
57 ie.time.tv_usec = 0;
58
59 write(fd, &ie, sizeof(ie));
60 }
61
62 int main(void)
63 {
64 struct uinput_setup usetup;
65
66 int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
67
68
69 /*
70 * The ioctls below will enable the device that is about to be
71 * created, to pass key events, in this case the space key.
72 */
73 ioctl(fd, UI_SET_EVBIT, EV_KEY);
74 ioctl(fd, UI_SET_KEYBIT, KEY_SPACE);
75
76 memset(&usetup, 0, sizeof(usetup));
77 usetup.id.bustype = BUS_USB;
78 usetup.id.vendor = 0x1234; /* sample vendor */
79 usetup.id.product = 0x5678; /* sample product */
80 strcpy(usetup.name, "Example device");
81
82 ioctl(fd, UI_DEV_SETUP, &usetup);
83 ioctl(fd, UI_DEV_CREATE);
84
85 /*
86 * On UI_DEV_CREATE the kernel will create the device node for this
87 * device. We are inserting a pause here so that userspace has time
88 * to detect, initialize the new device, and can start listening to
89 * the event, otherwise it will not notice the event we are about
90 * to send. This pause is only needed in our example code!
91 */
92 sleep(1);
93
94 /* Key press, report the event, send key release, and report again */
95 emit(fd, EV_KEY, KEY_SPACE, 1);
96 emit(fd, EV_SYN, SYN_REPORT, 0);
97 emit(fd, EV_KEY, KEY_SPACE, 0);
98 emit(fd, EV_SYN, SYN_REPORT, 0);
99
100 /*
101 * Give userspace some time to read the events before we destroy the
102 * device with UI_DEV_DESTROY.
103 */
104 sleep(1);
105
106 ioctl(fd, UI_DEV_DESTROY);
107 close(fd);
108
109 return 0;
110 }
111
112Mouse movements
113---------------
114
115This example shows how to create a virtual device that behaves like a physical
116mouse.
117
118.. code-block:: c
119
120 #include <linux/uinput.h>
121
122 /* emit function is identical to of the first example */
123
124 int main(void)
125 {
126 struct uinput_setup usetup;
127 int i = 50;
128
129 int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
130
131 /* enable mouse button left and relative events */
132 ioctl(fd, UI_SET_EVBIT, EV_KEY);
133 ioctl(fd, UI_SET_KEYBIT, BTN_LEFT);
134
135 ioctl(fd, UI_SET_EVBIT, EV_REL);
136 ioctl(fd, UI_SET_RELBIT, REL_X);
137 ioctl(fd, UI_SET_RELBIT, REL_Y);
138
139 memset(&usetup, 0, sizeof(usetup));
140 usetup.id.bustype = BUS_USB;
141 usetup.id.vendor = 0x1234; /* sample vendor */
142 usetup.id.product = 0x5678; /* sample product */
143 strcpy(usetup.name, "Example device");
144
145 ioctl(fd, UI_DEV_SETUP, &usetup);
146 ioctl(fd, UI_DEV_CREATE);
147
148 /*
149 * On UI_DEV_CREATE the kernel will create the device node for this
150 * device. We are inserting a pause here so that userspace has time
151 * to detect, initialize the new device, and can start listening to
152 * the event, otherwise it will not notice the event we are about
153 * to send. This pause is only needed in our example code!
154 */
155 sleep(1);
156
157 /* Move the mouse diagonally, 5 units per axis */
158 while (i--) {
159 emit(fd, EV_REL, REL_X, 5);
160 emit(fd, EV_REL, REL_Y, 5);
161 emit(fd, EV_SYN, SYN_REPORT, 0);
162 usleep(15000);
163 }
164
165 /*
166 * Give userspace some time to read the events before we destroy the
167 * device with UI_DEV_DESTROY.
168 */
169 sleep(1);
170
171 ioctl(fd, UI_DEV_DESTROY);
172 close(fd);
173
174 return 0;
175 }
176
177
178uinput old interface
179--------------------
180
181Before uinput version 5, there wasn't a dedicated ioctl to set up a virtual
182device. Programs supporting older versions of uinput interface need to fill
183a uinput_user_dev structure and write it to the uinput file descriptor to
184configure the new uinput device. New code should not use the old interface
185but interact with uinput via ioctl calls, or use libevdev.
186
187.. code-block:: c
188
189 #include <linux/uinput.h>
190
191 /* emit function is identical to of the first example */
192
193 int main(void)
194 {
195 struct uinput_user_dev uud;
196 int version, rc, fd;
197
198 fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
199 rc = ioctl(fd, UI_GET_VERSION, &version);
200
201 if (rc == 0 && version >= 5) {
202 /* use UI_DEV_SETUP */
203 return 0;
204 }
205
206 /*
207 * The ioctls below will enable the device that is about to be
208 * created, to pass key events, in this case the space key.
209 */
210 ioctl(fd, UI_SET_EVBIT, EV_KEY);
211 ioctl(fd, UI_SET_KEYBIT, KEY_SPACE);
212
213 memset(&uud, 0, sizeof(uud));
214 snprintf(uud.name, UINPUT_MAX_NAME_SIZE, "uinput old interface");
215 write(fd, &uud, sizeof(uud));
216
217 ioctl(fd, UI_DEV_CREATE);
218
219 /*
220 * On UI_DEV_CREATE the kernel will create the device node for this
221 * device. We are inserting a pause here so that userspace has time
222 * to detect, initialize the new device, and can start listening to
223 * the event, otherwise it will not notice the event we are about
224 * to send. This pause is only needed in our example code!
225 */
226 sleep(1);
227
228 /* Key press, report the event, send key release, and report again */
229 emit(fd, EV_KEY, KEY_SPACE, 1);
230 emit(fd, EV_SYN, SYN_REPORT, 0);
231 emit(fd, EV_KEY, KEY_SPACE, 0);
232 emit(fd, EV_SYN, SYN_REPORT, 0);
233
234 /*
235 * Give userspace some time to read the events before we destroy the
236 * device with UI_DEV_DESTROY.
237 */
238 sleep(1);
239
240 ioctl(fd, UI_DEV_DESTROY);
241
242 close(fd);
243 return 0;
244 }
245