as usual, reading through these things multiple times means one spots a couple of different things. sorry about that. On Fri, Mar 24, 2017 at 12:34:59AM -0300, Marcos Paulo de Souza wrote: > Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@xxxxxxxxx> > --- > Documentation/input/uinput.rst | 196 +++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 196 insertions(+) > create mode 100644 Documentation/input/uinput.rst > > diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst > new file mode 100644 > index 0000000..eb79b77 > --- /dev/null > +++ b/Documentation/input/uinput.rst > @@ -0,0 +1,196 @@ > +============= > +uinput module > +============= > + > +Introduction > +============ > + > +uinput is a kernel module that makes possible to create and handle input devices typo: makes *it* possible. replace "to create and handle" with "to emulate", the rest is in the next sentence anyway > +from userspace. By writing to the module's /dev/uinput (or /dev/input/uinput), a > +process can create a virtual device with specific capabilities. > +Once created, the process can send events through that virtual device. > + > +Interface > +========= > + > +:: > + > + linux/uinput.h > + > +The uinput header defines ioctls to create, setup and destroy virtual devices. > + > +libevdev > +======== > + > +libevdev is a wrapper library for evdev devices, making uinput setup easier > +by skipping a lot of ioctl calls. When dealing with uinput, libevdev is the best > +alternative over accessing uinput directly, and it is less error prone. "libevdev is a wrapper library for evdev devices that provides interfaces to create uinput devices and send events. libevdev is less error-prone than accessing uinput directly and should be considered for new software". > + > +For examples and more information about libevdev: > +https://cgit.freedesktop.org/libevdev > + Please use https://www.freedesktop.org/software/libevdev/doc/latest/ (which needs a link to the git repo, I'll fix that in a minute) > +Examples > +======== > + > +1.0 Keyboard events > +------------------- > + > +This first example shows how to create a new virtual device and how to send a > +key event. All default imports and error handlers were removed for the sake of > +simplicity. > + > +.. code-block:: c > + > + #include <linux/uinput.h> > + > + int fd; > + > + void emit(int type, int code, int val) > + { > + struct input_event ie; > + > + ie.type = type; > + ie.code = code; > + ie.value = val; > + /* below timestamp values are ignored */ > + ie.time.tv_sec = 0; > + ie.time.tv_usec = 0; > + > + write(fd, &ie, sizeof(ie)); > + } > + > + int main() { > + struct uinput_setup usetup; > + > + fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK); > + > + /* the ioctls below enables the to be created device to key > + * events, in this case the space key > + **/ the comment terminator doesn't look right > + ioctl(fd, UI_SET_EVBIT, EV_KEY); > + ioctl(fd, UI_SET_KEYBIT, KEY_SPACE); > + > + memset(&usetup, 0, sizeof(usetup)); > + usetup.id.bustype = BUS_USB; > + usetup.id.vendor = 0x1234; /* sample vendor */ add a sample product id too please > + strcpy(usetup.name, "Example device"); > + > + ioctl(fd, UI_DEV_SETUP, &usetup); > + ioctl(fd, UI_DEV_CREATE); > + > + /* UI_DEV_CREATE causes the kernel to create the device nodes for this "On UI_DEV_CREATE the kernel creates the device nodes..." > + * device. Insert a pause so that userspace has time to detect, > + * initialize the new device, and can start to listen to events from > + * this device > + **/ the comment terminator doesn't look right note: the actual pause is missing now :) > + > + /* key press, report the event, send key release, and report again */ > + emit(EV_KEY, KEY_SPACE, 1); > + emit(EV_SYN, SYN_REPORT, 0); > + emit(EV_KEY, KEY_SPACE, 0); > + emit(EV_SYN, SYN_REPORT, 0); come to think of it, you probably need a pause here too, iirc a caller may get ENODEV before reading the key events otherwise. > + > + ioctl(fd, UI_DEV_DESTROY); > + close(fd); > + > + return 0; > + } > + > +2.0 Mouse movements > +------------------- > + > +This example shows how to create a virtual device that behaves like a physical > +mouse. > + > +.. code-block:: c > + > + #include <linux/uinput.h> > + > + /* emit function is identical to of the first example */ > + > + struct uinput_setup usetup; > + int i = 50; > + > + fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK); > + > + /* enable mouse button left and relative events */ > + ioctl(fd, UI_SET_EVBIT, EV_KEY); > + ioctl(fd, UI_SET_KEYBIT, BTN_LEFT); > + > + ioctl(fd, UI_SET_EVBIT, EV_REL); > + ioctl(fd, UI_SET_RELBIT, REL_X); > + ioctl(fd, UI_SET_RELBIT, REL_Y); > + > + memset(&usetup, 0, sizeof(usetup)); > + usetup.id.bustype = BUS_USB; > + usetup.id.vendor = 0x1234; /* sample vendor */ > + strcpy(usetup.name, "Example device"); > + > + ioctl(fd, UI_DEV_SETUP, &usetup); > + ioctl(fd, UI_DEV_CREATE); > + > + /* UI_DEV_CREATE causes the kernel to create the device nodes for this > + * device. Insert a pause so that userspace has time to detect, > + * initialize the new device, and can start to listen to events from > + * this device > + **/ > + > + /* moves the mouse diagonally, 5 units per axis */ > + while (i--) { > + emit(EV_REL, REL_X, 5); > + emit(EV_REL, REL_Y, 5); > + emit(EV_SYN, SYN_REPORT, 0); > + usleep(15000); > + } > + > + ioctl(fd, UI_DEV_DESTROY); > + close(fd); > + > + return 0; > + > +3.0 uinput old interface > +------------------------ > + > +Before kernel 4.5, uinput didn't have an ioctl to setup a virtual device. When > +running a version prior to 4.5, the user needs to fill a different struct and > +call write on the uinput file descriptor. I think this should really include the version check. Cheers, Peter > + > +.. code-block:: c > + > + #include <linux/uinput.h> > + > + /* emit function is identical to of the first example */ > + > + struct uinput_user_dev uud; > + > + fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK); > + > + /* the ioctls below enables the to be created device to key > + * events, in this case the space key > + **/ > + ioctl(fd, UI_SET_EVBIT, EV_KEY); > + ioctl(fd, UI_SET_KEYBIT, KEY_SPACE); > + > + memset(&uud, 0, sizeof(uud)); > + snprintf(uud.name, UINPUT_MAX_NAME_SIZE, "uinput old interface"); > + write(fd, &uud, sizeof(uud)); > + > + ioctl(fd, UI_DEV_CREATE); > + > + /* UI_DEV_CREATE causes the kernel to create the device nodes for this > + * device. Insert a pause so that userspace has time to detect, > + * initialize the new device, and can start to listen to events from > + * this device > + **/ > + > + /* key press, report the event, send key release, and report again */ > + emit(EV_KEY, KEY_SPACE, 1); > + emit(EV_SYN, SYN_REPORT, 0); > + emit(EV_KEY, KEY_SPACE, 0); > + emit(EV_SYN, SYN_REPORT, 0); > + > + ioctl(fd, UI_DEV_DESTROY); > + close(fd); > + > + return 0; > + > -- > 2.9.3 > -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
