Re: [PATCH v6] Documentation: Input: Add uinput documentation

[Dmitry Torokhov]

On Sun, Apr 23, 2017 at 03:40:50PM -0300, Marcos Paulo de Souza wrote:
> Signed-off-by: Marcos Paulo de Souza 
> ---

I adjusted wording a bit here and there and applied, thank you.

> 
>  v5 -> v6:
>  Resend v5, but now include a change into input_uapi.rst (added by Dmitry and
>  Mauro) to include the newly added uinput documentation.
> 
>  v4 -> v5:
>  Fixed the way we detect the old interface of uinput (suggested by Peter)
> 
>  v3 -> v4:
>  Add comment and a sleep call before UI_DEV_DESTROY (suggested by Peter)
>  On emit function, add an fd parameter, avoiding global variables
>  Check return of ioctl related to older kernels that don't have UI_GET_VERSION
>  Fix typos
> 
>  v2 -> v3
>  Changes in libevdev's description (suggested by Peter)
>  Added uinput version check when using the old interface (suggested by Peter)
>  Removed section numbers from sections, sphinx creates these indexes
> (suggestion by Jon)
> 
>  v1 -> v2:
>  Changes all over the place, including better descriptions (suggested by 
> Peter)
>  Added comments about the need of a sleep call (suggested by Peter)
> 
>  Documentation/input/input_uapi.rst |   1 +
>  Documentation/input/uinput.rst | 231 
> +
>  2 files changed, 232 insertions(+)
>  create mode 100644 Documentation/input/uinput.rst
> 
> diff --git a/Documentation/input/input_uapi.rst 
> b/Documentation/input/input_uapi.rst
> index 12ef897..089fe4e 100644
> --- a/Documentation/input/input_uapi.rst
> +++ b/Documentation/input/input_uapi.rst
> @@ -13,6 +13,7 @@ Linux Input Subsystem userspace API
> :numbered:
>  
> input
> +   uinput
> event-codes
> multi-touch-protocol
> gamepad
> diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst
> new file mode 100644
> index 000..688cf87
> --- /dev/null
> +++ b/Documentation/input/uinput.rst
> @@ -0,0 +1,231 @@
> +=
> +uinput module
> +=
> +
> +Introduction
> +
> +
> +uinput is a kernel module that makes it possible to emulate input devices 
> 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 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://www.freedesktop.org/software/libevdev/doc/latest/
> +
> +Examples
> +
> +
> +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 
> +
> +   void emit(int fd, 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, , sizeof(ie));
> +   }
> +
> +   int main(void)
> +   {
> +  struct uinput_setup usetup;
> +
> +  int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
> +
> +  /* the ioctls below enables the to be created device to send key
> +   * events, in this case the space key
> +   */
> +  ioctl(fd, UI_SET_EVBIT, EV_KEY);
> +  ioctl(fd, UI_SET_KEYBIT, KEY_SPACE);
> +
> +  memset(, 0, sizeof(usetup));
> +  usetup.id.bustype = BUS_USB;
> +  usetup.id.vendor = 0x1234; /* sample vendor */
> +  usetup.id.product = 0x5678; /* sample product */
> +  strcpy(usetup.name, "Example device");
> +
> +  ioctl(fd, UI_DEV_SETUP, );
> +  ioctl(fd, UI_DEV_CREATE);
> +
> +  /*
> +   * On UI_DEV_CREATE the kernel creates 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
> +   */
> +  sleep(1);
> +
> +  /* key press, report the event, send key release, and report again */
> +  emit(fd, EV_KEY, KEY_SPACE, 1);
> +  emit(fd, EV_SYN, SYN_REPORT, 0);
> +  emit(fd, EV_KEY, KEY_SPACE, 0);
> +  emit(fd, EV_SYN, SYN_REPORT, 0);
> +
> +  /* Give userspace some time to read the events before we destroy the
> +   * device with UI_DEV_DESTOY
> +   */
> +  sleep(1);
> +
> +  ioctl(fd, UI_DEV_DESTROY);
> +  close(fd);
> +
> +  return 0;
> +   }
> +
> +Mouse movements
> +---
> +
> 

Re: [PATCH v6] Documentation: Input: Add uinput documentation

[Dmitry Torokhov]

On Sun, Apr 23, 2017 at 03:40:50PM -0300, Marcos Paulo de Souza wrote:
> Signed-off-by: Marcos Paulo de Souza 
> ---

I adjusted wording a bit here and there and applied, thank you.

> 
>  v5 -> v6:
>  Resend v5, but now include a change into input_uapi.rst (added by Dmitry and
>  Mauro) to include the newly added uinput documentation.
> 
>  v4 -> v5:
>  Fixed the way we detect the old interface of uinput (suggested by Peter)
> 
>  v3 -> v4:
>  Add comment and a sleep call before UI_DEV_DESTROY (suggested by Peter)
>  On emit function, add an fd parameter, avoiding global variables
>  Check return of ioctl related to older kernels that don't have UI_GET_VERSION
>  Fix typos
> 
>  v2 -> v3
>  Changes in libevdev's description (suggested by Peter)
>  Added uinput version check when using the old interface (suggested by Peter)
>  Removed section numbers from sections, sphinx creates these indexes
> (suggestion by Jon)
> 
>  v1 -> v2:
>  Changes all over the place, including better descriptions (suggested by 
> Peter)
>  Added comments about the need of a sleep call (suggested by Peter)
> 
>  Documentation/input/input_uapi.rst |   1 +
>  Documentation/input/uinput.rst | 231 
> +
>  2 files changed, 232 insertions(+)
>  create mode 100644 Documentation/input/uinput.rst
> 
> diff --git a/Documentation/input/input_uapi.rst 
> b/Documentation/input/input_uapi.rst
> index 12ef897..089fe4e 100644
> --- a/Documentation/input/input_uapi.rst
> +++ b/Documentation/input/input_uapi.rst
> @@ -13,6 +13,7 @@ Linux Input Subsystem userspace API
> :numbered:
>  
> input
> +   uinput
> event-codes
> multi-touch-protocol
> gamepad
> diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst
> new file mode 100644
> index 000..688cf87
> --- /dev/null
> +++ b/Documentation/input/uinput.rst
> @@ -0,0 +1,231 @@
> +=
> +uinput module
> +=
> +
> +Introduction
> +
> +
> +uinput is a kernel module that makes it possible to emulate input devices 
> 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 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://www.freedesktop.org/software/libevdev/doc/latest/
> +
> +Examples
> +
> +
> +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 
> +
> +   void emit(int fd, 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, , sizeof(ie));
> +   }
> +
> +   int main(void)
> +   {
> +  struct uinput_setup usetup;
> +
> +  int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
> +
> +  /* the ioctls below enables the to be created device to send key
> +   * events, in this case the space key
> +   */
> +  ioctl(fd, UI_SET_EVBIT, EV_KEY);
> +  ioctl(fd, UI_SET_KEYBIT, KEY_SPACE);
> +
> +  memset(, 0, sizeof(usetup));
> +  usetup.id.bustype = BUS_USB;
> +  usetup.id.vendor = 0x1234; /* sample vendor */
> +  usetup.id.product = 0x5678; /* sample product */
> +  strcpy(usetup.name, "Example device");
> +
> +  ioctl(fd, UI_DEV_SETUP, );
> +  ioctl(fd, UI_DEV_CREATE);
> +
> +  /*
> +   * On UI_DEV_CREATE the kernel creates 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
> +   */
> +  sleep(1);
> +
> +  /* key press, report the event, send key release, and report again */
> +  emit(fd, EV_KEY, KEY_SPACE, 1);
> +  emit(fd, EV_SYN, SYN_REPORT, 0);
> +  emit(fd, EV_KEY, KEY_SPACE, 0);
> +  emit(fd, EV_SYN, SYN_REPORT, 0);
> +
> +  /* Give userspace some time to read the events before we destroy the
> +   * device with UI_DEV_DESTOY
> +   */
> +  sleep(1);
> +
> +  ioctl(fd, UI_DEV_DESTROY);
> +  close(fd);
> +
> +  return 0;
> +   }
> +
> +Mouse movements
> +---
> +
> +This example shows how to 

[PATCH v6] Documentation: Input: Add uinput documentation

[Marcos Paulo de Souza]

Signed-off-by: Marcos Paulo de Souza 
---

 v5 -> v6:
 Resend v5, but now include a change into input_uapi.rst (added by Dmitry and
 Mauro) to include the newly added uinput documentation.

 v4 -> v5:
 Fixed the way we detect the old interface of uinput (suggested by Peter)

 v3 -> v4:
 Add comment and a sleep call before UI_DEV_DESTROY (suggested by Peter)
 On emit function, add an fd parameter, avoiding global variables
 Check return of ioctl related to older kernels that don't have UI_GET_VERSION
 Fix typos

 v2 -> v3
 Changes in libevdev's description (suggested by Peter)
 Added uinput version check when using the old interface (suggested by Peter)
 Removed section numbers from sections, sphinx creates these indexes
(suggestion by Jon)

 v1 -> v2:
 Changes all over the place, including better descriptions (suggested by Peter)
 Added comments about the need of a sleep call (suggested by Peter)

 Documentation/input/input_uapi.rst |   1 +
 Documentation/input/uinput.rst | 231 +
 2 files changed, 232 insertions(+)
 create mode 100644 Documentation/input/uinput.rst

diff --git a/Documentation/input/input_uapi.rst 
b/Documentation/input/input_uapi.rst
index 12ef897..089fe4e 100644
--- a/Documentation/input/input_uapi.rst
+++ b/Documentation/input/input_uapi.rst
@@ -13,6 +13,7 @@ Linux Input Subsystem userspace API
:numbered:
 
input
+   uinput
event-codes
multi-touch-protocol
gamepad
diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst
new file mode 100644
index 000..688cf87
--- /dev/null
+++ b/Documentation/input/uinput.rst
@@ -0,0 +1,231 @@
+=
+uinput module
+=
+
+Introduction
+
+
+uinput is a kernel module that makes it possible to emulate input devices 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 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://www.freedesktop.org/software/libevdev/doc/latest/
+
+Examples
+
+
+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 
+
+   void emit(int fd, 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, , sizeof(ie));
+   }
+
+   int main(void)
+   {
+  struct uinput_setup usetup;
+
+  int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
+
+  /* the ioctls below enables the to be created device to send key
+   * events, in this case the space key
+   */
+  ioctl(fd, UI_SET_EVBIT, EV_KEY);
+  ioctl(fd, UI_SET_KEYBIT, KEY_SPACE);
+
+  memset(, 0, sizeof(usetup));
+  usetup.id.bustype = BUS_USB;
+  usetup.id.vendor = 0x1234; /* sample vendor */
+  usetup.id.product = 0x5678; /* sample product */
+  strcpy(usetup.name, "Example device");
+
+  ioctl(fd, UI_DEV_SETUP, );
+  ioctl(fd, UI_DEV_CREATE);
+
+  /*
+   * On UI_DEV_CREATE the kernel creates 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
+   */
+  sleep(1);
+
+  /* key press, report the event, send key release, and report again */
+  emit(fd, EV_KEY, KEY_SPACE, 1);
+  emit(fd, EV_SYN, SYN_REPORT, 0);
+  emit(fd, EV_KEY, KEY_SPACE, 0);
+  emit(fd, EV_SYN, SYN_REPORT, 0);
+
+  /* Give userspace some time to read the events before we destroy the
+   * device with UI_DEV_DESTOY
+   */
+  sleep(1);
+
+  ioctl(fd, UI_DEV_DESTROY);
+  close(fd);
+
+  return 0;
+   }
+
+Mouse movements
+---
+
+This example shows how to create a virtual device that behaves like a physical
+mouse.
+
+.. code-block:: c
+
+   #include 
+
+   /* emit function is identical to of the first example */
+
+   int main(void)
+   {
+  struct uinput_setup usetup;
+  int i = 50;
+
+  int 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, 

[PATCH v6] Documentation: Input: Add uinput documentation

[Marcos Paulo de Souza]

Signed-off-by: Marcos Paulo de Souza 
---

 v5 -> v6:
 Resend v5, but now include a change into input_uapi.rst (added by Dmitry and
 Mauro) to include the newly added uinput documentation.

 v4 -> v5:
 Fixed the way we detect the old interface of uinput (suggested by Peter)

 v3 -> v4:
 Add comment and a sleep call before UI_DEV_DESTROY (suggested by Peter)
 On emit function, add an fd parameter, avoiding global variables
 Check return of ioctl related to older kernels that don't have UI_GET_VERSION
 Fix typos

 v2 -> v3
 Changes in libevdev's description (suggested by Peter)
 Added uinput version check when using the old interface (suggested by Peter)
 Removed section numbers from sections, sphinx creates these indexes
(suggestion by Jon)

 v1 -> v2:
 Changes all over the place, including better descriptions (suggested by Peter)
 Added comments about the need of a sleep call (suggested by Peter)

 Documentation/input/input_uapi.rst |   1 +
 Documentation/input/uinput.rst | 231 +
 2 files changed, 232 insertions(+)
 create mode 100644 Documentation/input/uinput.rst

diff --git a/Documentation/input/input_uapi.rst 
b/Documentation/input/input_uapi.rst
index 12ef897..089fe4e 100644
--- a/Documentation/input/input_uapi.rst
+++ b/Documentation/input/input_uapi.rst
@@ -13,6 +13,7 @@ Linux Input Subsystem userspace API
:numbered:
 
input
+   uinput
event-codes
multi-touch-protocol
gamepad
diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst
new file mode 100644
index 000..688cf87
--- /dev/null
+++ b/Documentation/input/uinput.rst
@@ -0,0 +1,231 @@
+=
+uinput module
+=
+
+Introduction
+
+
+uinput is a kernel module that makes it possible to emulate input devices 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 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://www.freedesktop.org/software/libevdev/doc/latest/
+
+Examples
+
+
+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 
+
+   void emit(int fd, 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, , sizeof(ie));
+   }
+
+   int main(void)
+   {
+  struct uinput_setup usetup;
+
+  int fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
+
+  /* the ioctls below enables the to be created device to send key
+   * events, in this case the space key
+   */
+  ioctl(fd, UI_SET_EVBIT, EV_KEY);
+  ioctl(fd, UI_SET_KEYBIT, KEY_SPACE);
+
+  memset(, 0, sizeof(usetup));
+  usetup.id.bustype = BUS_USB;
+  usetup.id.vendor = 0x1234; /* sample vendor */
+  usetup.id.product = 0x5678; /* sample product */
+  strcpy(usetup.name, "Example device");
+
+  ioctl(fd, UI_DEV_SETUP, );
+  ioctl(fd, UI_DEV_CREATE);
+
+  /*
+   * On UI_DEV_CREATE the kernel creates 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
+   */
+  sleep(1);
+
+  /* key press, report the event, send key release, and report again */
+  emit(fd, EV_KEY, KEY_SPACE, 1);
+  emit(fd, EV_SYN, SYN_REPORT, 0);
+  emit(fd, EV_KEY, KEY_SPACE, 0);
+  emit(fd, EV_SYN, SYN_REPORT, 0);
+
+  /* Give userspace some time to read the events before we destroy the
+   * device with UI_DEV_DESTOY
+   */
+  sleep(1);
+
+  ioctl(fd, UI_DEV_DESTROY);
+  close(fd);
+
+  return 0;
+   }
+
+Mouse movements
+---
+
+This example shows how to create a virtual device that behaves like a physical
+mouse.
+
+.. code-block:: c
+
+   #include 
+
+   /* emit function is identical to of the first example */
+
+   int main(void)
+   {
+  struct uinput_setup usetup;
+  int i = 50;
+
+  int 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,