[PATCH 0/3] Input: add ABS_TWIST and support it in HID and Wacom

[PATCH 0/3] Input: add ABS_TWIST and support it in HID and Wacom

[Siarhei Vishniakou]

Some styli can report rotation along their long ("barrel") axis,
commonly referred to as "twist". While the HID specification defines
this usage as HID_DG_TWIST (0x000d0041) in the Digitizers page, there is
currently no corresponding evdev axis code to expose it to userspace.

Because evdev has no MSC_SCAN equivalent for axes, drivers and OEMs
currently work around this by mapping stylus twist onto unrelated axes
such as ABS_Z or ABS_RZ. As a result, userspace input stacks must
maintain device-specific workarounds to know which axis carries twist.

This series introduces a dedicated ABS_TWIST (0x1d) axis for single-tool
devices such as styli and wires it up in the HID subsystem:

1. Input: Define ABS_TWIST (0x1d) in input-event-codes.h and document it
   in event-codes.rst with resolution in units/radian.
2. HID: Map HID_DG_TWIST (0x000d0041) to ABS_TWIST in hid-input, compute
   its resolution in units/radian, and add KUnit test coverage.
3. HID: wacom: Report pen twist on ABS_TWIST in addition to ABS_Z so
   that userspace can use the standard axis while maintaining backward
   compatibility with existing applications that expect ABS_Z.

Siarhei Vishniakou (3):
  Input: add ABS_TWIST event code
  HID: input: map Digitizers Twist usage to ABS_TWIST
  HID: wacom: report ABS_TWIST alongside ABS_Z for pen twist

 Documentation/input/event-codes.rst    |  6 ++
 drivers/hid/hid-debug.c                |  1 +
 drivers/hid/hid-input-test.c           | 87 ++++++++++++++++++++++++++
 drivers/hid/hid-input.c                |  5 ++
 drivers/hid/wacom_wac.c                | 35 +++++++++--
 include/uapi/linux/input-event-codes.h |  1 +
 6 files changed, 129 insertions(+), 6 deletions(-)

-- 
2.56.0.455.g6c5a503b38-goog

[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@google.com>
---
 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

[PATCH 2/3] HID: input: map Digitizers Twist usage to ABS_TWIST

[Siarhei Vishniakou]

The axis ABS_TWIST is used to report the "twist" (or barrel) rotation
of a stylus.

Map the HID Digitizers Twist usage (0x000d0041) to ABS_TWIST
in hid-input, and calculate its axis resolution in units/radian.

Signed-off-by: Siarhei Vishniakou <svv@google.com>
---
 drivers/hid/hid-input-test.c | 87 ++++++++++++++++++++++++++++++++++++
 drivers/hid/hid-input.c      |  5 +++
 2 files changed, 92 insertions(+)

diff --git a/drivers/hid/hid-input-test.c b/drivers/hid/hid-input-test.c
index 6f5c71660d82..6f1717c0cbe0 100644
--- a/drivers/hid/hid-input-test.c
+++ b/drivers/hid/hid-input-test.c
@@ -62,9 +62,96 @@ static void hid_test_input_get_battery_property(struct kunit *test)
 	KUNIT_EXPECT_EQ(test, val.intval, POWER_SUPPLY_STATUS_DISCHARGING);
 }
 
+static void hid_test_input_calc_abs_res_twist(struct kunit *test)
+{
+	struct hid_field field = {
+		.logical_minimum = 0,
+		.logical_maximum = 3599,
+		.physical_minimum = 0,
+		.physical_maximum = 3599,
+		.unit = 0x14, /* Degrees */
+		.unit_exponent = -1,
+	};
+
+	/* 0..3599 over 0..359.9 degrees -> ~573 units/radian */
+	KUNIT_EXPECT_EQ(test, hidinput_calc_abs_res(&field, ABS_TWIST), 573);
+
+	/* 0..359 over 0..359 degrees -> ~57 units/radian */
+	field.logical_maximum = 359;
+	field.physical_maximum = 359;
+	field.unit_exponent = 0;
+	KUNIT_EXPECT_EQ(test, hidinput_calc_abs_res(&field, ABS_TWIST), 57);
+
+	/* 0..628 over 0..6.28 radians -> 100 units/radian */
+	field.logical_maximum = 628;
+	field.physical_maximum = 628;
+	field.unit = 0x12; /* Radians */
+	field.unit_exponent = -2;
+	KUNIT_EXPECT_EQ(test, hidinput_calc_abs_res(&field, ABS_TWIST), 100);
+
+	/* Linear unit (centimeters) is invalid for ABS_TWIST */
+	field.unit = 0x11;
+	KUNIT_EXPECT_EQ(test, hidinput_calc_abs_res(&field, ABS_TWIST), 0);
+}
+
+static void hid_test_input_configure_twist_usage(struct kunit *test)
+{
+	struct hid_device *dev;
+	struct hid_driver *drv;
+	struct hid_input *hidinput;
+	struct input_dev *input;
+	struct hid_field *field;
+	struct hid_usage *usage;
+
+	dev = kunit_kzalloc(test, sizeof(*dev), GFP_KERNEL);
+	KUNIT_ASSERT_NOT_ERR_OR_NULL(test, dev);
+
+	drv = kunit_kzalloc(test, sizeof(*drv), GFP_KERNEL);
+	KUNIT_ASSERT_NOT_ERR_OR_NULL(test, drv);
+	dev->driver = drv;
+
+	input = kunit_kzalloc(test, sizeof(*input), GFP_KERNEL);
+	KUNIT_ASSERT_NOT_ERR_OR_NULL(test, input);
+	input->absinfo = kunit_kcalloc(test, ABS_CNT, sizeof(*input->absinfo), GFP_KERNEL);
+	KUNIT_ASSERT_NOT_ERR_OR_NULL(test, input->absinfo);
+	input_set_drvdata(input, dev);
+
+	hidinput = kunit_kzalloc(test, sizeof(*hidinput), GFP_KERNEL);
+	KUNIT_ASSERT_NOT_ERR_OR_NULL(test, hidinput);
+	hidinput->input = input;
+
+	field = kunit_kzalloc(test, sizeof(*field), GFP_KERNEL);
+	KUNIT_ASSERT_NOT_ERR_OR_NULL(test, field);
+	field->report_count = 1;
+	field->logical_minimum = 0;
+	field->logical_maximum = 3599;
+	field->physical_minimum = 0;
+	field->physical_maximum = 3599;
+	field->unit = 0x14; /* Degrees */
+	field->unit_exponent = -1;
+	field->usages_priorities = kunit_kzalloc(test, sizeof(int), GFP_KERNEL);
+	KUNIT_ASSERT_NOT_ERR_OR_NULL(test, field->usages_priorities);
+
+	usage = kunit_kzalloc(test, sizeof(*usage), GFP_KERNEL);
+	KUNIT_ASSERT_NOT_ERR_OR_NULL(test, usage);
+	usage->hid = HID_DG_TWIST;
+
+	hidinput_configure_usage(hidinput, field, usage, 0);
+
+	KUNIT_EXPECT_EQ(test, usage->type, EV_ABS);
+	KUNIT_EXPECT_EQ(test, usage->code, ABS_TWIST);
+	KUNIT_EXPECT_TRUE(test, test_bit(EV_ABS, input->evbit));
+	KUNIT_EXPECT_TRUE(test, test_bit(ABS_TWIST, input->absbit));
+	KUNIT_EXPECT_EQ(test, input_abs_get_min(input, ABS_TWIST), 0);
+	KUNIT_EXPECT_EQ(test, input_abs_get_max(input, ABS_TWIST), 3599);
+	KUNIT_EXPECT_EQ(test, input_abs_get_res(input, ABS_TWIST), 573);
+}
+
 static struct kunit_case hid_input_tests[] = {
 	KUNIT_CASE(hid_test_input_update_battery_charge_status),
 	KUNIT_CASE(hid_test_input_get_battery_property),
+	KUNIT_CASE(hid_test_input_calc_abs_res_twist),
+	KUNIT_CASE(hid_test_input_configure_twist_usage),
 	{ }
 };
 
diff --git a/drivers/hid/hid-input.c b/drivers/hid/hid-input.c
index 6a1651f572e2..dc4bd2a579d2 100644
--- a/drivers/hid/hid-input.c
+++ b/drivers/hid/hid-input.c
@@ -291,6 +291,7 @@ __s32 hidinput_calc_abs_res(const struct hid_field *field, __u16 code)
 	case ABS_WHEEL:
 	case ABS_TILT_X:
 	case ABS_TILT_Y:
+	case ABS_TWIST:
 		if (field->unit == 0x14) {		/* If degrees */
 			/* Convert to radians */
 			prev = logical_extents;
@@ -1018,6 +1019,10 @@ static void hidinput_configure_usage(struct hid_input *hidinput, struct hid_fiel
 			map_abs_clear(ABS_TILT_Y);
 			break;
 
+		case 0x41: /* Twist */
+			map_abs_clear(ABS_TWIST);
+			break;
+
 		case 0x33: /* Touch */
 		case 0x42: /* TipSwitch */
 		case 0x43: /* TipSwitch2 */
-- 
2.56.0.455.g6c5a503b38-goog

[PATCH 3/3] HID: wacom: report ABS_TWIST alongside ABS_Z for pen twist

[Siarhei Vishniakou]

Historically, Wacom tablets reported stylus barrel rotation (twist)
via ABS_Z because a dedicated evdev axis did not exist. Now that we
have this axis, report pen twist on ABS_TWIST in addition to ABS_Z.

Keep reporting ABS_Z to maintain backward compatibility for existing
applications that support Wacom devices.

Signed-off-by: Siarhei Vishniakou <svv@google.com>
---
 drivers/hid/wacom_wac.c | 35 +++++++++++++++++++++++++++++------
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/drivers/hid/wacom_wac.c b/drivers/hid/wacom_wac.c
index 614f2adab563..7676bc26a027 100644
--- a/drivers/hid/wacom_wac.c
+++ b/drivers/hid/wacom_wac.c
@@ -802,8 +802,10 @@ static void wacom_exit_report(struct wacom_wac *wacom)
 		input_report_key(input, BTN_STYLUS2, 0);
 		input_report_key(input, BTN_TOUCH, 0);
 		input_report_abs(input, ABS_WHEEL, 0);
-		if (features->type >= INTUOS3S)
+		if (features->type >= INTUOS3S) {
 			input_report_abs(input, ABS_Z, 0);
+			input_report_abs(input, ABS_TWIST, 0);
+		}
 	}
 	input_report_key(input, wacom->tool[idx], 0);
 	input_report_abs(input, ABS_MISC, 0); /* reset tool id */
@@ -981,6 +983,7 @@ static int wacom_intuos_general(struct wacom_wac *wacom)
 			t = (data[7] & 0x20) ? ((t > 900) ? ((t-1) / 2 - 1350) :
 				((t-1) / 2 + 450)) : (450 - t / 2) ;
 			input_report_abs(input, ABS_Z, t);
+			input_report_abs(input, ABS_TWIST, t);
 		} else {
 			/* 4D mouse 2nd packet */
 			t = (data[6] << 3) | ((data[7] >> 5) & 7);
@@ -1411,6 +1414,7 @@ static void wacom_intuos_pro2_bt_pen(struct wacom_wac *wacom)
 				input_report_abs(pen_input, ABS_TILT_Y,
 						 (signed char)frame[8]);
 				input_report_abs(pen_input, ABS_Z, rotation);
+				input_report_abs(pen_input, ABS_TWIST, rotation);
 				input_report_abs(pen_input, ABS_WHEEL,
 						 get_unaligned_le16(&frame[11]));
 			}
@@ -1935,7 +1939,7 @@ static void wacom_map_usage(struct input_dev *input, struct hid_usage *usage,
 	int resolution;
 
 	if (equivalent_usage == HID_DG_TWIST) {
-		resolution_code = ABS_RZ;
+		resolution_code = ABS_TWIST;
 	}
 
 	resolution = hidinput_calc_abs_res(field, resolution_code);
@@ -2332,6 +2336,7 @@ static void wacom_wac_pen_usage_mapping(struct hid_device *hdev,
 		break;
 	case HID_DG_TWIST:
 		wacom_map_usage(input, usage, field, EV_ABS, ABS_Z, 0);
+		wacom_map_usage(input, usage, field, EV_ABS, ABS_TWIST, 0);
 		break;
 	case HID_DG_ERASER:
 		input_set_capability(input, EV_KEY, BTN_TOOL_RUBBER);
@@ -2522,10 +2527,21 @@ static void wacom_wac_pen_event(struct hid_device *hdev, struct hid_field *field
 		return;
 
 	/* send pen events only when the pen is in range */
-	if (wacom_wac->hid_data.inrange_state)
-		input_event(input, usage->type, usage->code, value);
-	else if (wacom_wac->shared->stylus_in_proximity && !wacom_wac->hid_data.sense_state)
-		input_event(input, usage->type, usage->code, 0);
+	if (!wacom_wac->hid_data.inrange_state) {
+		if (!wacom_wac->shared->stylus_in_proximity ||
+		    wacom_wac->hid_data.sense_state)
+			return;
+		value = 0;
+	}
+
+	input_event(input, usage->type, usage->code, value);
+	/*
+	 * ABS_Z was used to report twist data, because ABS_TWIST was not yet
+	 * defined at the time. For compatibility purposes, also report twist
+	 * via ABS_Z.
+	 */
+	if (equivalent_usage == HID_DG_TWIST)
+		input_report_abs(input, ABS_Z, value);
 }
 
 static void wacom_wac_pen_pre_report(struct hid_device *hdev,
@@ -3741,6 +3757,7 @@ void wacom_setup_device_quirks(struct wacom *wacom)
 		__clear_bit(BTN_TOOL_PENCIL, wacom_wac->pen_input->keybit);
 		__clear_bit(BTN_TOOL_AIRBRUSH, wacom_wac->pen_input->keybit);
 		__clear_bit(ABS_Z, wacom_wac->pen_input->absbit);
+		__clear_bit(ABS_TWIST, wacom_wac->pen_input->absbit);
 		__clear_bit(ABS_DISTANCE, wacom_wac->pen_input->absbit);
 		__clear_bit(ABS_TILT_X, wacom_wac->pen_input->absbit);
 		__clear_bit(ABS_TILT_Y, wacom_wac->pen_input->absbit);
@@ -3823,6 +3840,8 @@ int wacom_setup_pen_input_capabilities(struct input_dev *input_dev,
 	case CINTIQ_COMPANION_2:
 		input_set_abs_params(input_dev, ABS_Z, -900, 899, 0, 0);
 		input_abs_set_res(input_dev, ABS_Z, 287);
+		input_set_abs_params(input_dev, ABS_TWIST, -900, 899, 0, 0);
+		input_abs_set_res(input_dev, ABS_TWIST, 287);
 		wacom_setup_cintiq(wacom_wac);
 		break;
 
@@ -3835,6 +3854,8 @@ int wacom_setup_pen_input_capabilities(struct input_dev *input_dev,
 	case INTUOS4S:
 		input_set_abs_params(input_dev, ABS_Z, -900, 899, 0, 0);
 		input_abs_set_res(input_dev, ABS_Z, 287);
+		input_set_abs_params(input_dev, ABS_TWIST, -900, 899, 0, 0);
+		input_abs_set_res(input_dev, ABS_TWIST, 287);
 		fallthrough;
 
 	case INTUOS:
@@ -3855,6 +3876,8 @@ int wacom_setup_pen_input_capabilities(struct input_dev *input_dev,
 
 		input_set_abs_params(input_dev, ABS_Z, -900, 899, 0, 0);
 		input_abs_set_res(input_dev, ABS_Z, 287);
+		input_set_abs_params(input_dev, ABS_TWIST, -900, 899, 0, 0);
+		input_abs_set_res(input_dev, ABS_TWIST, 287);
 
 		wacom_setup_intuos(wacom_wac);
 		break;
-- 
2.56.0.455.g6c5a503b38-goog

Re: [PATCH 0/3] Input: add ABS_TWIST and support it in HID and Wacom

[Dmitry Torokhov]

Hi Siarhei,

On Mon, Nov 09, 2026 at 06:06:29PM -0800, Siarhei Vishniakou wrote:
> Some styli can report rotation along their long ("barrel") axis,
> commonly referred to as "twist". While the HID specification defines
> this usage as HID_DG_TWIST (0x000d0041) in the Digitizers page, there is
> currently no corresponding evdev axis code to expose it to userspace.
> 
> Because evdev has no MSC_SCAN equivalent for axes, drivers and OEMs
> currently work around this by mapping stylus twist onto unrelated axes
> such as ABS_Z or ABS_RZ. As a result, userspace input stacks must
> maintain device-specific workarounds to know which axis carries twist.

How is it different from orientation?

Thanks.

-- 
Dmitry