Re: [PATCH v2 35/37] input: add a EV_SW event for ratchet switch

[Peter Hutterer]

On Thu, Apr 06, 2017 at 09:16:05PM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 5 Apr 2017 22:03:03 +1000
> Peter Hutterer <peter.hutte...@who-t.net> escreveu:
> 
> > On Tue, Apr 04, 2017 at 09:22:35AM -0300, Mauro Carvalho Chehab wrote:
> > > Some mouses have a switch on their wheel, allowing to switch  
> > 
> > isnt' the plural of mouse mice? (non-native english speaker myself)
> 
> Yeah, true. I'll fix on a next review.
> > 
> > > between ratchet or free wheel mode. Add support for it.  
> > 
> > s/or/and/
> > 
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
> > > ---
> > >  Documentation/input/event-codes.rst| 16 
> > >  include/linux/mod_devicetable.h|  2 +-
> > >  include/uapi/linux/input-event-codes.h |  4 +++-
> > >  3 files changed, 20 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/Documentation/input/event-codes.rst 
> > > b/Documentation/input/event-codes.rst
> > > index 0c8591d39bc6..93f14f0ddb3d 100644
> > > --- a/Documentation/input/event-codes.rst
> > > +++ b/Documentation/input/event-codes.rst
> > > @@ -239,6 +239,22 @@ Upon resume, if the switch state is the same as 
> > > before suspend, then the input
> > >  subsystem will filter out the duplicate switch state reports. The driver 
> > > does
> > >  not need to keep the state of the switch at any time.
> > >  
> > > +A few EV_SW codes have special meanings:
> > > +
> > > +* SW_RATCHET:
> > > +
> > > +  - Some mouses have a special switch at their wheel that allows to 
> > > change
> > > +from free wheel mode to ratchet mode.  
> > 
> > "between free wheel mode and ratchet mode"
> > 
> > > +
> > > +When such switch is ratchet mode (ON state), the wheel will offer 
> > > some  
> > 
> > s/such/the/
> > 
> > > +resistance for movements movement. It will also provide a tactile
> > > +feedback when scrolled.  
> > 
> > this is too specific, you cannot guarantee that all devices in the future
> > have exactly that behaviour. I would just skip the second sentence.
> 
> I just wanted to let it clear about what's the difference between ratchet
> and free wheel mode. As a non-native speaker, I had to research myself
> about what the heck "ratchet" means, as I never heard this word before ;)
> 
> To be frank, when I received this mouse, I had some troubles to adapt
> to it, as on other mice I have here, the wheel is used generate the
> mid button event. On this specific model, there's a small button on
> south of the wheel the mid button event.
> 
> > > +
> > > +When pressed while in ratchet mode, the wheel will switch to free 
> > > wheel
> > > +mode (OFF state). In this mode, it will offer no resistance to wheel
> > > +movements nor any tactile feedback. Pressing again returns to ratchet
> > > +mode.  
> > 
> > nack to this, this is your device but not all future devices will have this
> > behaviour. e.g. some devices have the ratchet switch below (i.e. south of)
> > the weel. Just describe the effect the switch has, not the physical
> > behaviour.
> 
> Ok, I'll remove it. What about this:
> 
> * SW_RATCHET:
> 
>   - Some mice have a special switch at their wheel that allows to change
> between free wheel mode and ratchet mode via a ratchet switch.
> 
> When the switch is ratchet mode (ON state), the wheel will offer some
> resistance for movements. It may also provide a tactile feedback when 
> scrolled.
 
yep, close, just a minor nitpick:

   - Some mice have a special switch for their wheel that allows to change
 between free wheel mode and ratchet mode. When the switch is ratchet
 mode (ON state), the wheel will offer some resistance for movements. It
 may also provide a tactile feedback when scrolled.


And maybe add something like:
 Note that some mice have a ratchet switch that does not generate a
 software event.

Cheers,
  Peter
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 35/37] input: add a EV_SW event for ratchet switch

[Peter Hutterer]

On Tue, Apr 04, 2017 at 09:22:35AM -0300, Mauro Carvalho Chehab wrote:
> Some mouses have a switch on their wheel, allowing to switch

isnt' the plural of mouse mice? (non-native english speaker myself)

> between ratchet or free wheel mode. Add support for it.

s/or/and/

> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/input/event-codes.rst| 16 
>  include/linux/mod_devicetable.h|  2 +-
>  include/uapi/linux/input-event-codes.h |  4 +++-
>  3 files changed, 20 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/input/event-codes.rst 
> b/Documentation/input/event-codes.rst
> index 0c8591d39bc6..93f14f0ddb3d 100644
> --- a/Documentation/input/event-codes.rst
> +++ b/Documentation/input/event-codes.rst
> @@ -239,6 +239,22 @@ Upon resume, if the switch state is the same as before 
> suspend, then the input
>  subsystem will filter out the duplicate switch state reports. The driver does
>  not need to keep the state of the switch at any time.
>  
> +A few EV_SW codes have special meanings:
> +
> +* SW_RATCHET:
> +
> +  - Some mouses have a special switch at their wheel that allows to change
> +from free wheel mode to ratchet mode.

"between free wheel mode and ratchet mode"

> +
> +When such switch is ratchet mode (ON state), the wheel will offer some

s/such/the/

> +resistance for movements movement. It will also provide a tactile
> +feedback when scrolled.

this is too specific, you cannot guarantee that all devices in the future
have exactly that behaviour. I would just skip the second sentence.

> +
> +When pressed while in ratchet mode, the wheel will switch to free wheel
> +mode (OFF state). In this mode, it will offer no resistance to wheel
> +movements nor any tactile feedback. Pressing again returns to ratchet
> +mode.

nack to this, this is your device but not all future devices will have this
behaviour. e.g. some devices have the ratchet switch below (i.e. south of)
the weel. Just describe the effect the switch has, not the physical
behaviour.

Cheers,
   Peter

> +
>  EV_MSC
>  --
>  
> diff --git a/include/linux/mod_devicetable.h b/include/linux/mod_devicetable.h
> index 8850fcaf50db..038cddf1436a 100644
> --- a/include/linux/mod_devicetable.h
> +++ b/include/linux/mod_devicetable.h
> @@ -292,7 +292,7 @@ struct pcmcia_device_id {
>  #define INPUT_DEVICE_ID_LED_MAX  0x0f
>  #define INPUT_DEVICE_ID_SND_MAX  0x07
>  #define INPUT_DEVICE_ID_FF_MAX   0x7f
> -#define INPUT_DEVICE_ID_SW_MAX   0x0f
> +#define INPUT_DEVICE_ID_SW_MAX   0x1f
>  
>  #define INPUT_DEVICE_ID_MATCH_BUS1
>  #define INPUT_DEVICE_ID_MATCH_VENDOR 2
> diff --git a/include/uapi/linux/input-event-codes.h 
> b/include/uapi/linux/input-event-codes.h
> index 23b2d377af59..a3eafd0527f1 100644
> --- a/include/uapi/linux/input-event-codes.h
> +++ b/include/uapi/linux/input-event-codes.h
> @@ -782,7 +782,9 @@
>  #define SW_LINEIN_INSERT 0x0d  /* set = inserted */
>  #define SW_MUTE_DEVICE   0x0e  /* set = device disabled */
>  #define SW_PEN_INSERTED  0x0f  /* set = pen inserted */
> -#define SW_MAX   0x0f
> +#define SW_RATCHET   0x10  /* set = ratchet mode,
> +  unset: free wheel */
> +#define SW_MAX   0x1f
>  #define SW_CNT   (SW_MAX+1)
>  
>  /*
> -- 
> 2.9.3
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 11/33] docs: input/event-codes: convert it to ReST format

[Peter Hutterer]

On Sat, Apr 01, 2017 at 11:42:05PM -0300, Mauro Carvalho Chehab wrote:
> Em Sun, 2 Apr 2017 11:16:35 +1000
> Peter Hutterer <peter.hutte...@who-t.net> escreveu:
> 
> > On Sat, Apr 01, 2017 at 03:15:54PM -0300, Mauro Carvalho Chehab wrote:
> > > This file require minimum adjustments to be a valid ReST file.
> > > Do it, in order to be able to parse it with Sphinx.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>  
> > 
> > there's a  conflict markerleft in this file, see below
> 
> 
> Gah! Sorry for that. The correct patch is enclosed.
> 
> I also updated the html for it:
>   http://www.infradead.org/~mchehab/kernel_docs/input/event-codes.html
> 
> Thanks,
> Mauro
> 
> [PATCH] docs: input/event-codes: convert it to ReST format
> 
> This file require minimum adjustments to be a valid ReST file.
> Do it, in order to be able to parse it with Sphinx.
> 
> Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>

Appears to do what it should, now :) Thanks for the update

Reviewed-by: Peter Hutterer <peter.hutte...@who-t.net>

Cheers,
   Peter

> 
> diff --git a/Documentation/input/event-codes.txt 
> b/Documentation/input/event-codes.txt
> index 36ea940e5bb9..92db50954169 100644
> --- a/Documentation/input/event-codes.txt
> +++ b/Documentation/input/event-codes.txt
> @@ -1,3 +1,8 @@
> +=
> +Input event codes
> +=
> +
> +
>  The input protocol uses a map of types and codes to express input device 
> values
>  to userspace. This document describes the types and codes and how and when 
> they
>  may be used.
> @@ -17,82 +22,102 @@ reports supported by a device are also provided by sysfs 
> in
>  class/input/event*/device/capabilities/, and the properties of a device are
>  provided in class/input/event*/device/properties.
>  
> -Event types:
> +Event types
>  ===
> +
>  Event types are groupings of codes under a logical input construct. Each
>  type has a set of applicable codes to be used in generating events. See the
>  Codes section for details on valid codes for each type.
>  
>  * EV_SYN:
> +
>- Used as markers to separate events. Events may be separated in time or in
>  space, such as with the multitouch protocol.
>  
>  * EV_KEY:
> +
>- Used to describe state changes of keyboards, buttons, or other key-like
>  devices.
>  
>  * EV_REL:
> +
>- Used to describe relative axis value changes, e.g. moving the mouse 5 
> units
>  to the left.
>  
>  * EV_ABS:
> +
>- Used to describe absolute axis value changes, e.g. describing the
>  coordinates of a touch on a touchscreen.
>  
>  * EV_MSC:
> +
>- Used to describe miscellaneous input data that do not fit into other 
> types.
>  
>  * EV_SW:
> +
>- Used to describe binary state input switches.
>  
>  * EV_LED:
> +
>- Used to turn LEDs on devices on and off.
>  
>  * EV_SND:
> +
>- Used to output sound to devices.
>  
>  * EV_REP:
> +
>- Used for autorepeating devices.
>  
>  * EV_FF:
> +
>- Used to send force feedback commands to an input device.
>  
>  * EV_PWR:
> +
>- A special type for power button and switch input.
>  
>  * EV_FF_STATUS:
> +
>- Used to receive force feedback device status.
>  
> -Event codes:
> +Event codes
>  ===
> +
>  Event codes define the precise type of event.
>  
> -EV_SYN:
> ---
> +EV_SYN
> +--
> +
>  EV_SYN event values are undefined. Their usage is defined only by when they 
> are
>  sent in the evdev event stream.
>  
>  * SYN_REPORT:
> +
>- Used to synchronize and separate events into packets of input data 
> changes
>  occurring at the same moment in time. For example, motion of a mouse may 
> set
>  the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The 
> next
>  motion will emit more REL_X and REL_Y values and send another SYN_REPORT.
>  
>  * SYN_CONFIG:
> +
>- TBD
>  
>  * SYN_MT_REPORT:
> +
>- Used to synchronize and separate touch events. See the
>  multi-touch-protocol.txt document for more information.
>  
>  * SYN_DROPPED:
> +
>- Used to indicate buffer overrun in the evdev client's event queue.
>  Client should ignore all events up to and including next SYN_REPORT
>  event and query the device (using EVIOCG* ioctls) to obtain its
>  current state.
>  
> -EV_KEY:
> ---
> +EV_KEY
> +--
> +
>  EV_KEY events take the form KEY_ or BTN_. For example, KEY_A is 
> u

Re: [PATCH 11/33] docs: input/event-codes: convert it to ReST format

[Peter Hutterer]

On Sat, Apr 01, 2017 at 03:15:54PM -0300, Mauro Carvalho Chehab wrote:
> This file require minimum adjustments to be a valid ReST file.
> Do it, in order to be able to parse it with Sphinx.
> 
> Signed-off-by: Mauro Carvalho Chehab 

there's a  conflict markerleft in this file, see below

Cheers,
   Peter

> @@ -195,14 +229,37 @@ Upon resume, if the switch state is the same as before 
> suspend, then the input
>  subsystem will filter out the duplicate switch state reports. The driver does
>  not need to keep the state of the switch at any time.
>  
> +<<< HEAD:Documentation/input/event-codes.txt
>  EV_MSC:
>  --
> +===
> +A few EV_SW codes have special meanings:
> +
> +* SW_RATCHET:
> +
> +  - Some mouses have a special switch at their wheel that allows to change
> +from free wheel mode to ratchet mode.
> +
> +When such switch is ratchet mode (ON state), the wheel will offer some
> +resistance for movements movement. It will also provide a tactile
> +feedback when scrolled.
> +
> +When pressed while in ratchet mode, the wheel will switch to free wheel
> +mode (OFF state). In this mode, it will offer no resistance to wheel
> +movements nor any tactile feedback. Pressing again returns to ratchet
> +mode.
> +
> +EV_MSC
> +--
> +
> +>>> 0b994c20db5f... docs: input/event-codes: convert it to ReST 
> format:Documentation/input/event-codes.rst
>  EV_MSC events are used for input and output events that do not fall under 
> other
>  categories.
>  
>  A few EV_MSC codes have special meaning:
>  
>  * MSC_TIMESTAMP:
> +
>- Used to report the number of microseconds since the last reset. This 
> event
>  should be coded as an uint32 value, which is allowed to wrap around with
>  no special consequence. It is assumed that the time difference between 
> two
> @@ -211,39 +268,46 @@ A few EV_MSC codes have special meaning:
>  unknown.  If the device does not provide this information, the driver 
> must
>  not provide it to user space.
>  
> -EV_LED:
> ---
> +EV_LED
> +--
> +
>  EV_LED events are used for input and output to set and query the state of
>  various LEDs on devices.
>  
> -EV_REP:
> ---
> +EV_REP
> +--
> +
>  EV_REP events are used for specifying autorepeating events.
>  
> -EV_SND:
> ---
> +EV_SND
> +--
> +
>  EV_SND events are used for sending sound commands to simple sound output
>  devices.
>  
> -EV_FF:
> ---
> +EV_FF
> +-
> +
>  EV_FF events are used to initialize a force feedback capable device and to 
> cause
>  such device to feedback.
>  
> -EV_PWR:
> ---
> +EV_PWR
> +--
> +
>  EV_PWR events are a special type of event used specifically for power
>  management. Its usage is not well defined. To be addressed later.
>  
> -Device properties:
> +Device properties
>  =
> +
>  Normally, userspace sets up an input device based on the data it emits,
>  i.e., the event types. In the case of two devices emitting the same event
>  types, additional information can be provided in the form of device
>  properties.
>  
> -INPUT_PROP_DIRECT + INPUT_PROP_POINTER:
> +INPUT_PROP_DIRECT + INPUT_PROP_POINTER
>  --
> +
>  The INPUT_PROP_DIRECT property indicates that device coordinates should be
>  directly mapped to screen coordinates (not taking into account trivial
>  transformations, such as scaling, flipping and rotating). Non-direct input
> @@ -260,8 +324,9 @@ If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are 
> set, the property is
>  considered undefined and the device type should be deduced in the
>  traditional way, using emitted event types.
>  
> -INPUT_PROP_BUTTONPAD:
> +INPUT_PROP_BUTTONPAD
>  
> +
>  For touchpads where the button is placed beneath the surface, such that
>  pressing down on the pad causes a button click, this property should be
>  set. Common in clickpad notebooks and macbooks from 2009 and onwards.
> @@ -270,8 +335,9 @@ Originally, the buttonpad property was coded into the 
> bcm5974 driver
>  version field under the name integrated button. For backwards
>  compatibility, both methods need to be checked in userspace.
>  
> -INPUT_PROP_SEMI_MT:
> +INPUT_PROP_SEMI_MT
>  --
> +
>  Some touchpads, most common between 2008 and 2011, can detect the presence
>  of multiple contacts without resolving the individual positions; only the
>  number of contacts and a rectangular shape is known. For such
> @@ -285,9 +351,10 @@ gestures can normally be extracted from it.
>  If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT
>  device.
>  
> -INPUT_PROP_TOPBUTTONPAD:
> +INPUT_PROP_TOPBUTTONPAD
>  ---
> -Some laptops, most notably the Lenovo *40 series provide a trackstick
> +
> +Some laptops, most notably the Lenovo 40 series provide a trackstick
>  device but do not have physical buttons associated with the 

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

[Peter Hutterer]

On Mon, Mar 27, 2017 at 09:01:19PM -0300, Marcos Paulo de Souza wrote:
> Signed-off-by: Marcos Paulo de Souza 
> ---
> 
>  v3 -> v4:
>  Add comment and a sleep call before UI_DEV_DESTROY (requested 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/uinput.rst | 229 
> +
>  1 file changed, 229 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 000..47a5c4d
> --- /dev/null
> +++ b/Documentation/input/uinput.rst
> @@ -0,0 +1,229 @@
> +=
> +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, UI_SET_EVBIT, EV_REL);
> +  ioctl(fd, UI_SET_RELBIT, REL_X);
> +  ioctl(fd, UI_SET_RELBIT, REL_Y);
> +
> +  memset(, 0, sizeof(usetup));
> +  usetup.id.bustype = BUS_USB;
> +

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

[Peter Hutterer]

On Sun, Mar 26, 2017 at 01:48:12PM -0300, Marcos Paulo de Souza wrote:
> Signed-off-by: Marcos Paulo de Souza 
> ---
>  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)
>  


[...]

tested mouse/keyboard - works as expected, thanks. I found it slightly
confusing though that the mouse example wasn't wrapped in main() but still had a
return 0 at the bottom. This code will never change once it's in the doc, so
I'm not sure skipping things is really that useful here.

> +uinput old interface
> +
> +
> +Before uinput version 5, there wasn't a proper ioctl to setup a virtual 
> device.
> +In this case, the user neesa to fill a different struct and call write o the
> +uinput file descriptor to configure the new uinput device.
> +
> +.. code-block:: c
> +
> +#include 
> +
> +/* emit function is identical to of the first example */
> +
> +struct uinput_user_dev uud;
> +int version;
> +
> +fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);
> +ioctl(fd, UI_GET_VERSION, );
> +
> +if (version < 5) {

this won't work on all kernels. UI_GET_VERSION was added in version 4, on
kernels before you get rc == -1 and errno EINVAL. You can only check
for >= 4. Please make sure the example compiles and works on an older
kernel, otherwise there's no point shipping it.

Cheers,
   Peter

> +/*
> + * 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(, 0, sizeof(uud));
> +snprintf(uud.name, UINPUT_MAX_NAME_SIZE, "uinput old interface");
> +write(fd, , sizeof(uud));
> +
> +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(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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Docs: Input: initial uinput documentation

[Peter Hutterer]

On Sun, Mar 26, 2017 at 01:41:08PM -0300, Marcos Paulo de Souza wrote:
> Hi Jon,
> 
> On Fri, Mar 24, 2017 at 03:17:03PM -0600, Jonathan Corbet wrote:
> > On Fri, 24 Mar 2017 00:34:58 -0300
> > Marcos Paulo de Souza <marcos.souza@gmail.com> wrote:
> > 
> > > this is the second iteration of this patch. The first version can be 
> > > checked
> > > here[1]. A special thanks to Peter Hutterer who dug the last patch and 
> > > suggested
> > > a lot of changes , hopefully, all addressed in this version.
> > 
> > This seems like a good start.  Of course, I have a couple of comments...
> > 
> > 1) RST documentation is good, but it really needs to be hooked into the
> >docs build with the rest.  In this case, it needs to go into the
> >application developer's manual.  The only slight snag is ... well ...
> >that manual doesn't quite exist yet.  Once this is ready, if it comes
> >through me tree, I can follow it with a patch creating that manual and
> >moving this section into it.
> 
> Sounds good. If you want, I can verify and add this new page as well.
> 
> > 
> > 2) We don't normally put in section numbers manually in RST documents,
> >since Sphinx will do that for us.
> 
> Great, fixed here.
> 
> > 
> > 3) Section 3.0 covers the old interface.  I'm not sure we need that in 
> >documentation in current kernels which, by definition, have the
> >current interface.
> 
> Currently both interces can be used in mainline, but this can be nice to have 
> for users
> who still run older kernels. But I can remove if you strongly disagree.

Given the kernel's policy for retiring interfaces, the old interface will be
available forever. But at this point you shouldn't be writing new software
against the old interface.

Cheers,
   Peter
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Peter Hutterer]

On Sun, Mar 26, 2017 at 01:21:14PM -0300, Marcos Paulo de Souza wrote:
> On Fri, Mar 24, 2017 at 02:39:13PM +1000, Peter Hutterer wrote:
> > 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@gmail.com>
> > > ---
> > >  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 000..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
> 
> Fixed.
> 
> > 
> > > +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".
> 
> Much better. Fixed.
> 
> > 
> > > +
> > > +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)
> 
> Fixed.
> 
> > 
> > > +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 
> > > +
> > > +   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, , 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
> 
> Fixed.
> 
> > 
> > > +ioctl(fd, UI_SET_EVBIT, EV_KEY);
> > > +ioctl(fd, UI_SET_KEYBIT, KEY_SPACE);
> > > +
> > > +memset(, 0, sizeof(usetup));
> > > +usetup.id.bustype = BUS_USB;
> > > +uset

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

[Peter Hutterer]

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 
> ---
>  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 000..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 
> +
> +   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, , 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(, 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, );
> +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 
> +
> +/* 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(, 

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

[Peter Hutterer]

On Wed, Mar 22, 2017 at 11:54:48PM -0300, Marcos Paulo de Souza wrote:
> Hi Peter,
> 
> first of all, thanks a lot for reading this patch so quickly and to
> point a lot of things to make this doc way better.
> 
> See some notes below.

thanks for all the fixes, much appreciated.
just two comments below:

> On Wed, Mar 22, 2017 at 02:03:31PM +1000, Peter Hutterer wrote:
[...]
> > > +memset(, 0, sizeof(ie));
> > > +ie.type = type;
> > > +ie.code = code;
> > > +ie.value = val;
> > > +
> > 
> > memset followed by three out of five filled in seems strange. Just add
> >   ie.time.tv_sec = 0;
> >   ie.time.tv_usec = 0;
> > 
> > ideally, with a comment that states that the timestamp is ignored :)
> 
> All the code in this doc is the result of my tests using uinput, so
> somethings were set in my code some time ago and were never touched
> again. Yes, this makes things a way better :)

note that if we ship this as documentation, these become the official
examples so they *have* to be correct. How many times have you copied
something from the examples of a library? Not ideal if there's a bug or just
messy code to begin with :)

> I fixed a lot of things today, the things that are still missing are the
> libevdev example, and the version check. I do think that I can send a
> new version tomorrow.

As for libevdev: just add a link to the documentation, don't add a libevdev
example. libevdev should (and does) provide the examples and you don't want
to ship example code that relies on some other library' API.

Cheers,
   Peter
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

[Peter Hutterer]

Thanks for this, I'm getting enough questions about this, so it's nice to
have a link :)

First comment: I don't think rst requires unwrapped lines, so please break
those up.

Second comment: I'd really like to have a link to libevdev here. It has a
uinput interface that's a bit more obvious and takes some of the guesswork
out. While it's good to have documentation for the kernel module,
application authors should really use libevdev's uinput interface.

On Tue, Mar 21, 2017 at 11:58:17PM -0300, Marcos Paulo de Souza wrote:
> Signed-off-by: Marcos Paulo de Souza 
> ---
>  Documentation/input/uinput.rst | 158 
> +
>  1 file changed, 158 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 000..8d59c98
> --- /dev/null
> +++ b/Documentation/input/uinput.rst
> @@ -0,0 +1,158 @@
> +=
> +uinput module
> +=
> +
> +Introduction
> +
> +
> +uinput is a kernel module that makes possible create and handle input

typo: "that makes it possible to ..."

> devices from userspace. By using /dev/uinput (or /dev/input/uinput), a
> process can create virtual devices and emit events like key pressing,
> mouse movements and joystick buttons.

I'd say something like this: "By writing to the module's /dev/uinput (or
/dev/input/uinput) file, 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 ioctl request keys to create, setup and destroy 
> virtual devices, along with ioctls specific to uinput devices, like enabling 
> events and keys to be send to the kernel.

'request keys' - is this the official name for ioctl numbers? If not, let's
just use "define ioctls" or "ioctl numbers" or something, because the term
"keys" is heavily overloaded. And anything after "along with... " is
superfluous.

> +
> +Examples
> +
> +
> +1.0 Keyboard events
> +---
> +
> +This first example shows how to create a new virtual device and how to
> send a key event as well as a physical keyboard. All default imports and

"as well as" in english usually means "in addition". Just skip the part
after "send a key event".

> error handlers were removed for the sake of simplicity.
> +
> +.. code-block:: c
> +
> +   #include 
> +
> +   int fd;
> +
> +   void emit(int type, int code, int val)
> +   {
> +struct input_event ie;

empty line here.

> +memset(, 0, sizeof(ie));
> +ie.type = type;
> +ie.code = code;
> +ie.value = val;
> +

memset followed by three out of five filled in seems strange. Just add
  ie.time.tv_sec = 0;
  ie.time.tv_usec = 0;

ideally, with a comment that states that the timestamp is ignored :)

> +if (write(fd, , sizeof(ie)) < 0) {
> +perror("write2");
> +exit(1);
> +}
> +   }
> +
> +   int main() {
> +struct input_id uid;
> +struct uinput_setup usetup;
> +
> +fd = open("/dev/uinput", O_WRONLY | O_NONBLOCK);

Empty line here to separate the open from the actual setup. And a comment
explaining what this does wouldn't go amiss.


> +ioctl(fd, UI_SET_EVBIT, EV_KEY);
> +ioctl(fd, UI_SET_KEYBIT, KEY_SPACE);
> +
> +memset(, 0, sizeof(iod));
> +memset(, 0, sizeof(usetup));
> +usetup.id = uid;

this is a bit strange - you're memsetting the id field anyway with the
usetup memset - it's superfluous. Given this is supposed to be example code,
something immediately obvious would help:
   usetup.id.bustype = BUS_USB;
   usetup.id.vendor = 0x1234; /* sample vendor */
   ... 

> +strcpy(usetup.name, "ex_device");

Surely we have enough bytes to name this "Example device" for obviousness :)

> +
> +ioctl(fd, UI_DEV_SETUP, );
> +ioctl(fd, UI_DEV_CREATE);
> +
> +/* wait some time until the Window Manager can get the reference for 
> the
> + * new virtual device to receive data from
> + * */
> +sleep(1);

This needs to be more generic, because the WM is the last thing that
actually cares about the device.

"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."

> +
> +/* send 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);

UI_DEV_DESTROY is missing

> +
> +close(fd);
> +
> +return 0;
> +   }
> +
> +2.0 Mouse movements
> +---
> +
> +This example