linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH] Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams
@ 2021-01-12 23:03 Peter Hutterer
  2021-01-13  9:00 ` Benjamin Tissoires
  2021-01-28 23:43 ` Jonathan Corbet
  0 siblings, 2 replies; 3+ messages in thread
From: Peter Hutterer @ 2021-01-12 23:03 UTC (permalink / raw)
  To: Dmitry Torokhov, Benjamin Tissoires, Jason Gerecke, Ping Cheng
  Cc: linux-input, Jiri Kosina, Henrik Rydberg, linux-kernel,
	Jonathan Corbet, linux-doc

ABS_PRESSURE and ABS_MT_PRESSURE on touch devices usually represent
contact size (as a finger flattens with higher pressure the contact size
increases) and userspace translates the kernel pressure value back into
contact size. For example, libinput has pressure thresholds when a touch is
considered a palm (palm == large contact area -> high pressure). The values
themselves are on an arbitrary scale and device-specific.

On pressurepads however, the pressure axis may represent the real physical
pressure. Pressurepads are touchpads without a hinge but an actual pressure
sensor underneath the device instead, for example the Lenovo Yoga 9i.

A high-enough pressure is converted to a button click by the firmware.
Microsoft does not require a pressure axis to be present, see [1], so as seen
from userspace most pressurepads are identical to clickpads - one button and
INPUT_PROP_BUTTONPAD set.

However, pressurepads that export the pressure axis break userspace because
that axis no longer represents contact size, resulting in inconsistent touch
tracking, e.g. [2]. Userspace needs to know when a pressure axis represents
real pressure and the best way to do so is to define what the resolution
field means. Userspace can then treat data with a pressure resolution as
true pressure.

This patch documents that the pressure resolution is in units/gram. This
allows for fine-grained detail and tops out at roughly ~2000t, enough for the
devices we're dealing with. Grams is not a scientific pressure unit but the
alternative is:
- Pascal: defined as force per area and area is unreliable on many devices and
  seems like the wrong option here anyway, especially for devices with a
  single pressure sensor only.
- Newton: defined as mass * distance/acceleration and for the purposes of a
  pressure axis, the distance is tricky to interpret and we get the data to
  calculate acceleration from event timestamps anyway.

For the purposes of touch devices and digitizers, grams seems the best choice
and the easiest to interpret.

Bonus side effect: we can use the existing hwdb infrastructure in userspace to
fix devices that advertise false pressure.

[1] https://docs.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-precision-touchpad-required-hid-top-level-collections#windows-precision-touchpad-input-reports
[2] https://gitlab.freedesktop.org/libinput/libinput/-/issues/562

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 Documentation/input/event-codes.rst          | 15 +++++++++++++++
 Documentation/input/multi-touch-protocol.rst |  4 ++++
 2 files changed, 19 insertions(+)

diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
index b24b5343f5eb..3118fc1c1e26 100644
--- a/Documentation/input/event-codes.rst
+++ b/Documentation/input/event-codes.rst
@@ -236,6 +236,21 @@ A few EV_ABS codes have special meanings:
   - Used to describe multitouch input events. Please see
     multi-touch-protocol.txt for details.
 
+* ABS_PRESSURE/ABS_MT_PRESSURE:
+
+   - For touch devices, many devices converted contact size into pressure.
+     A finger flattens with pressure, causing a larger contact area and thus
+     pressure and contact size are directly related. This is not the case
+     for other devices, for example digitizers and touchpads with a true
+     pressure sensor ("pressure pads").
+
+     A device should set the resolution of the axis to indicate whether the
+     pressure is in measurable units. If the resolution is zero, the
+     pressure data is in arbitrary units. If the resolution is nonzero, the
+     pressure data is in units/gram. For example, a value of 10 with a
+     resolution of 1 represents 10 gram, a value of 10 with a resolution on
+     1000 represents 10 microgram.
+
 EV_SW
 -----
 
diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst
index 307fe22d9668..21c1e6a22888 100644
--- a/Documentation/input/multi-touch-protocol.rst
+++ b/Documentation/input/multi-touch-protocol.rst
@@ -260,6 +260,10 @@ ABS_MT_PRESSURE
     of TOUCH and WIDTH for pressure-based devices or any device with a spatial
     signal intensity distribution.
 
+    If the resolution is zero, the pressure data is in arbitrary units.
+    If the resolution is nonzero, the pressure data is in units/gram. See
+    :ref:`input-event-codes` for details.
+
 ABS_MT_DISTANCE
     The distance, in surface units, between the contact and the surface. Zero
     distance means the contact is touching the surface. A positive number means
-- 
2.29.2


^ permalink raw reply related	[flat|nested] 3+ messages in thread

* Re: [PATCH] Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams
  2021-01-12 23:03 [PATCH] Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams Peter Hutterer
@ 2021-01-13  9:00 ` Benjamin Tissoires
  2021-01-28 23:43 ` Jonathan Corbet
  1 sibling, 0 replies; 3+ messages in thread
From: Benjamin Tissoires @ 2021-01-13  9:00 UTC (permalink / raw)
  To: Peter Hutterer
  Cc: Dmitry Torokhov, Jason Gerecke, Ping Cheng, linux-input,
	Jiri Kosina, Henrik Rydberg, lkml, Jonathan Corbet, linux-doc

On Wed, Jan 13, 2021 at 12:03 AM Peter Hutterer
<peter.hutterer@who-t.net> wrote:
>
> ABS_PRESSURE and ABS_MT_PRESSURE on touch devices usually represent
> contact size (as a finger flattens with higher pressure the contact size
> increases) and userspace translates the kernel pressure value back into
> contact size. For example, libinput has pressure thresholds when a touch is
> considered a palm (palm == large contact area -> high pressure). The values
> themselves are on an arbitrary scale and device-specific.
>
> On pressurepads however, the pressure axis may represent the real physical
> pressure. Pressurepads are touchpads without a hinge but an actual pressure
> sensor underneath the device instead, for example the Lenovo Yoga 9i.
>
> A high-enough pressure is converted to a button click by the firmware.
> Microsoft does not require a pressure axis to be present, see [1], so as seen
> from userspace most pressurepads are identical to clickpads - one button and
> INPUT_PROP_BUTTONPAD set.
>
> However, pressurepads that export the pressure axis break userspace because
> that axis no longer represents contact size, resulting in inconsistent touch
> tracking, e.g. [2]. Userspace needs to know when a pressure axis represents
> real pressure and the best way to do so is to define what the resolution
> field means. Userspace can then treat data with a pressure resolution as
> true pressure.
>
> This patch documents that the pressure resolution is in units/gram. This
> allows for fine-grained detail and tops out at roughly ~2000t, enough for the
> devices we're dealing with. Grams is not a scientific pressure unit but the
> alternative is:
> - Pascal: defined as force per area and area is unreliable on many devices and
>   seems like the wrong option here anyway, especially for devices with a
>   single pressure sensor only.
> - Newton: defined as mass * distance/acceleration and for the purposes of a
>   pressure axis, the distance is tricky to interpret and we get the data to
>   calculate acceleration from event timestamps anyway.
>
> For the purposes of touch devices and digitizers, grams seems the best choice
> and the easiest to interpret.
>
> Bonus side effect: we can use the existing hwdb infrastructure in userspace to
> fix devices that advertise false pressure.
>
> [1] https://docs.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-precision-touchpad-required-hid-top-level-collections#windows-precision-touchpad-input-reports
> [2] https://gitlab.freedesktop.org/libinput/libinput/-/issues/562
>
> Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

FWIW, and because I was involved in the initial discussion:
Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>

Cheers,
Benjamin

> ---
>  Documentation/input/event-codes.rst          | 15 +++++++++++++++
>  Documentation/input/multi-touch-protocol.rst |  4 ++++
>  2 files changed, 19 insertions(+)
>
> diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst
> index b24b5343f5eb..3118fc1c1e26 100644
> --- a/Documentation/input/event-codes.rst
> +++ b/Documentation/input/event-codes.rst
> @@ -236,6 +236,21 @@ A few EV_ABS codes have special meanings:
>    - Used to describe multitouch input events. Please see
>      multi-touch-protocol.txt for details.
>
> +* ABS_PRESSURE/ABS_MT_PRESSURE:
> +
> +   - For touch devices, many devices converted contact size into pressure.
> +     A finger flattens with pressure, causing a larger contact area and thus
> +     pressure and contact size are directly related. This is not the case
> +     for other devices, for example digitizers and touchpads with a true
> +     pressure sensor ("pressure pads").
> +
> +     A device should set the resolution of the axis to indicate whether the
> +     pressure is in measurable units. If the resolution is zero, the
> +     pressure data is in arbitrary units. If the resolution is nonzero, the
> +     pressure data is in units/gram. For example, a value of 10 with a
> +     resolution of 1 represents 10 gram, a value of 10 with a resolution on
> +     1000 represents 10 microgram.
> +
>  EV_SW
>  -----
>
> diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst
> index 307fe22d9668..21c1e6a22888 100644
> --- a/Documentation/input/multi-touch-protocol.rst
> +++ b/Documentation/input/multi-touch-protocol.rst
> @@ -260,6 +260,10 @@ ABS_MT_PRESSURE
>      of TOUCH and WIDTH for pressure-based devices or any device with a spatial
>      signal intensity distribution.
>
> +    If the resolution is zero, the pressure data is in arbitrary units.
> +    If the resolution is nonzero, the pressure data is in units/gram. See
> +    :ref:`input-event-codes` for details.
> +
>  ABS_MT_DISTANCE
>      The distance, in surface units, between the contact and the surface. Zero
>      distance means the contact is touching the surface. A positive number means
> --
> 2.29.2
>

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [PATCH] Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams
  2021-01-12 23:03 [PATCH] Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams Peter Hutterer
  2021-01-13  9:00 ` Benjamin Tissoires
@ 2021-01-28 23:43 ` Jonathan Corbet
  1 sibling, 0 replies; 3+ messages in thread
From: Jonathan Corbet @ 2021-01-28 23:43 UTC (permalink / raw)
  To: Peter Hutterer
  Cc: Dmitry Torokhov, Benjamin Tissoires, Jason Gerecke, Ping Cheng,
	linux-input, Jiri Kosina, Henrik Rydberg, linux-kernel,
	linux-doc

On Wed, 13 Jan 2021 09:03:10 +1000
Peter Hutterer <peter.hutterer@who-t.net> wrote:

> ABS_PRESSURE and ABS_MT_PRESSURE on touch devices usually represent
> contact size (as a finger flattens with higher pressure the contact size
> increases) and userspace translates the kernel pressure value back into
> contact size. For example, libinput has pressure thresholds when a touch is
> considered a palm (palm == large contact area -> high pressure). The values
> themselves are on an arbitrary scale and device-specific.
> 
> On pressurepads however, the pressure axis may represent the real physical
> pressure. Pressurepads are touchpads without a hinge but an actual pressure
> sensor underneath the device instead, for example the Lenovo Yoga 9i.
> 
> A high-enough pressure is converted to a button click by the firmware.
> Microsoft does not require a pressure axis to be present, see [1], so as seen
> from userspace most pressurepads are identical to clickpads - one button and
> INPUT_PROP_BUTTONPAD set.
> 
> However, pressurepads that export the pressure axis break userspace because
> that axis no longer represents contact size, resulting in inconsistent touch
> tracking, e.g. [2]. Userspace needs to know when a pressure axis represents
> real pressure and the best way to do so is to define what the resolution
> field means. Userspace can then treat data with a pressure resolution as
> true pressure.
> 
> This patch documents that the pressure resolution is in units/gram. This
> allows for fine-grained detail and tops out at roughly ~2000t, enough for the
> devices we're dealing with. Grams is not a scientific pressure unit but the
> alternative is:
> - Pascal: defined as force per area and area is unreliable on many devices and
>   seems like the wrong option here anyway, especially for devices with a
>   single pressure sensor only.
> - Newton: defined as mass * distance/acceleration and for the purposes of a
>   pressure axis, the distance is tricky to interpret and we get the data to
>   calculate acceleration from event timestamps anyway.
> 
> For the purposes of touch devices and digitizers, grams seems the best choice
> and the easiest to interpret.
> 
> Bonus side effect: we can use the existing hwdb infrastructure in userspace to
> fix devices that advertise false pressure.
> 
> [1] https://docs.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-precision-touchpad-required-hid-top-level-collections#windows-precision-touchpad-input-reports
> [2] https://gitlab.freedesktop.org/libinput/libinput/-/issues/562
> 
> Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
> ---
>  Documentation/input/event-codes.rst          | 15 +++++++++++++++
>  Documentation/input/multi-touch-protocol.rst |  4 ++++
>  2 files changed, 19 insertions(+)

It looks like nobody has picked this up, so I went ahead and applied it.

Thanks,

jon

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2021-01-28 23:45 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-01-12 23:03 [PATCH] Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams Peter Hutterer
2021-01-13  9:00 ` Benjamin Tissoires
2021-01-28 23:43 ` Jonathan Corbet

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).