[PATCH 1/3] Input: add ABS_TWIST event code

[Siarhei Vishniakou]

Some styli can report the rotation along their long ("barrel") axis.
This is typically referred to as "twist".

In the HID usage pages, twist is already supported as HID_DG_TWIST.
However, this usage is not reported to the userspace via evdev interface
today, since there's no MSC_SCAN equivalent for axes.

Peripheral OEMs get around this today by mapping this axis to other axes
like ABS_Z or ABS_RZ. This is not a valid way to report twist.

As a result, the userspace programs that would like to support twist
must account for the various ways specific OEMs map this, since there's
no generic axis for this.

Unify this behaviour by introducing a new axis, ABS_TWIST. This axis will
only apply to the single-pointer touch devices (stylus), as opposed to
"per-slot" multi-touch devices (which would then suggest something like
ABS_MT_TWIST).

Here we define the ABS_TWIST absolute axis code (0x1d) to report the
rotation of a tool (such as a stylus) around its major (barrel) axis,
and document it in event-codes.rst.

The device can specify its twist resolution as units/radian.

Signed-off-by: Siarhei Vishniakou <svv@xxxxxxxxxx>
---
 Documentation/input/event-codes.rst    | 6 ++++++
 drivers/hid/hid-debug.c                | 1 +
 include/uapi/linux/input-event-codes.h | 1 +
 3 files changed, 8 insertions(+)

diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
index b4557462edd7..f1f7fd502081 100644
--- a/Documentation/input/event-codes.rst
+++ b/Documentation/input/event-codes.rst
@@ -235,6 +235,12 @@ A few EV_ABS codes have special meanings:
     BTN_TOOL_<name> signals the type of tool that is currently detected by the
     hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH.
 
+* ABS_TWIST:
+
+  - Used to describe the rotation of a tool (such as a stylus) around its
+    major (barrel) axis. If the resolution is non-zero, the twist data is
+    in units/radian.
+
 * ABS_PROFILE:
 
   - Used to describe the state of a multi-value profile switch.  An event is
diff --git a/drivers/hid/hid-debug.c b/drivers/hid/hid-debug.c
index 15e35702773c..594cf5248163 100644
--- a/drivers/hid/hid-debug.c
+++ b/drivers/hid/hid-debug.c
@@ -1015,6 +1015,7 @@ static const char *absolutes[ABS_CNT] = {
 	[ABS_HAT3Y] = "Hat 3Y",		[ABS_PRESSURE] = "Pressure",
 	[ABS_DISTANCE] = "Distance",	[ABS_TILT_X] = "XTilt",
 	[ABS_TILT_Y] = "YTilt",		[ABS_TOOL_WIDTH] = "ToolWidth",
+	[ABS_TWIST] = "Twist",
 	[ABS_VOLUME] = "Volume",	[ABS_PROFILE] = "Profile",
 	[ABS_MISC] = "Misc",
 	[ABS_MT_TOUCH_MAJOR] = "MTMajor",
diff --git a/include/uapi/linux/input-event-codes.h b/include/uapi/linux/input-event-codes.h
index f410c22e080d..cdc718fc1c4a 100644
--- a/include/uapi/linux/input-event-codes.h
+++ b/include/uapi/linux/input-event-codes.h
@@ -862,6 +862,7 @@
 #define ABS_TILT_X		0x1a
 #define ABS_TILT_Y		0x1b
 #define ABS_TOOL_WIDTH		0x1c
+#define ABS_TWIST		0x1d
 
 #define ABS_VOLUME		0x20
 #define ABS_PROFILE		0x21
-- 
2.56.0.455.g6c5a503b38-goog