linux/Documentation/input/event-codes.rst

484 lines
18 KiB

Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams 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> Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com> Link: https://lore.kernel.org/r/20210112230310.GA149342@jelly Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-01-13 09:03:10 +10:00
Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams 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> Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com> Link: https://lore.kernel.org/r/20210112230310.GA149342@jelly Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-01-13 09:03:10 +10:00
Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams 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> Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com> Link: https://lore.kernel.org/r/20210112230310.GA149342@jelly Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-01-13 09:03:10 +10:00
Input: rename INPUT_PROP_HAPTIC_TOUCHPAD to INPUT_PROP_PRESSUREPAD And expand it to encompass all pressure pads. Definition: "pressure pad" as used here as includes all touchpads that use physical pressure to convert to click, without physical hinges. Also called haptic touchpads in general parlance, Synaptics calls them ForcePads. Most (all?) pressure pads are currently advertised as INPUT_PROP_BUTTONPAD. The suggestion to identify them as pressure pads by defining the resolution on ABS_MT_PRESSURE has been in the docs since commit 20ccc8dd38a3 ("Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams") but few devices provide this information. In userspace it's thus impossible to determine whether a device is a true pressure pad (pressure equals pressure) or a normal clickpad with (pressure equals finger size). Commit 7075ae4ac9db ("Input: add INPUT_PROP_HAPTIC_TOUCHPAD") introduces INPUT_PROP_HAPTIC_TOUCHPAD but restricted it to those touchpads that have support for userspace-controlled effects. Let's expand and rename that definition to include all pressure pad touchpads since those that do support FF effects can be identified by the presence of the FF_HAPTIC bit. This means: - clickpad: INPUT_PROP_BUTTONPAD - pressurepad: INPUT_PROP_BUTTONPAD + INPUT_PROP_PRESSUREPAD - pressurepad with configurable haptics: INPUT_PROP_BUTTONPAD + INPUT_PROP_PRESSUREPAD + FF_HAPTIC Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Acked-by: Benjamin Tissoires <bentiss@kernel.org> Link: https://patch.msgid.link/20251106114534.GA405512@tassie Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
2025-11-06 21:45:34 +10:00
Input: rename INPUT_PROP_HAPTIC_TOUCHPAD to INPUT_PROP_PRESSUREPAD And expand it to encompass all pressure pads. Definition: "pressure pad" as used here as includes all touchpads that use physical pressure to convert to click, without physical hinges. Also called haptic touchpads in general parlance, Synaptics calls them ForcePads. Most (all?) pressure pads are currently advertised as INPUT_PROP_BUTTONPAD. The suggestion to identify them as pressure pads by defining the resolution on ABS_MT_PRESSURE has been in the docs since commit 20ccc8dd38a3 ("Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams") but few devices provide this information. In userspace it's thus impossible to determine whether a device is a true pressure pad (pressure equals pressure) or a normal clickpad with (pressure equals finger size). Commit 7075ae4ac9db ("Input: add INPUT_PROP_HAPTIC_TOUCHPAD") introduces INPUT_PROP_HAPTIC_TOUCHPAD but restricted it to those touchpads that have support for userspace-controlled effects. Let's expand and rename that definition to include all pressure pad touchpads since those that do support FF effects can be identified by the presence of the FF_HAPTIC bit. This means: - clickpad: INPUT_PROP_BUTTONPAD - pressurepad: INPUT_PROP_BUTTONPAD + INPUT_PROP_PRESSUREPAD - pressurepad with configurable haptics: INPUT_PROP_BUTTONPAD + INPUT_PROP_PRESSUREPAD + FF_HAPTIC Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Acked-by: Benjamin Tissoires <bentiss@kernel.org> Link: https://patch.msgid.link/20251106114534.GA405512@tassie Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
2025-11-06 21:45:34 +10:00
Input: rename INPUT_PROP_HAPTIC_TOUCHPAD to INPUT_PROP_PRESSUREPAD And expand it to encompass all pressure pads. Definition: "pressure pad" as used here as includes all touchpads that use physical pressure to convert to click, without physical hinges. Also called haptic touchpads in general parlance, Synaptics calls them ForcePads. Most (all?) pressure pads are currently advertised as INPUT_PROP_BUTTONPAD. The suggestion to identify them as pressure pads by defining the resolution on ABS_MT_PRESSURE has been in the docs since commit 20ccc8dd38a3 ("Documentation: input: define ABS_PRESSURE/ABS_MT_PRESSURE resolution as grams") but few devices provide this information. In userspace it's thus impossible to determine whether a device is a true pressure pad (pressure equals pressure) or a normal clickpad with (pressure equals finger size). Commit 7075ae4ac9db ("Input: add INPUT_PROP_HAPTIC_TOUCHPAD") introduces INPUT_PROP_HAPTIC_TOUCHPAD but restricted it to those touchpads that have support for userspace-controlled effects. Let's expand and rename that definition to include all pressure pad touchpads since those that do support FF effects can be identified by the presence of the FF_HAPTIC bit. This means: - clickpad: INPUT_PROP_BUTTONPAD - pressurepad: INPUT_PROP_BUTTONPAD + INPUT_PROP_PRESSUREPAD - pressurepad with configurable haptics: INPUT_PROP_BUTTONPAD + INPUT_PROP_PRESSUREPAD + FF_HAPTIC Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Acked-by: Benjamin Tissoires <bentiss@kernel.org> Link: https://patch.msgid.link/20251106114534.GA405512@tassie Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
2025-11-06 21:45:34 +10:00