Message-ID: <vyhhm3x6nfdfw6gbgluq3sjr6bzamhear7nec6xdi5wfxq7wcz@cx2egj4yr5sp>
Date: Thu, 4 Sep 2025 12:02:35 +0200
From: Benjamin Tissoires <bentiss@...nel.org>
To: Dmitry Torokhov <dmitry.torokhov@...il.com>, 
	Jonathan Denose <jdenose@...gle.com>
Cc: Jiri Kosina <jikos@...nel.org>, Jonathan Corbet <corbet@....net>, 
	Henrik Rydberg <rydberg@...math.org>, linux-input@...r.kernel.org, linux-kernel@...r.kernel.org, 
	linux-doc@...r.kernel.org, Angela Czubak <aczubak@...gle.com>, 
	Sean O'Brien <seobrien@...gle.com>
Subject: Re: [PATCH v3 00/11] HID: Implement haptic touchpad support

On Sep 02 2025, Jonathan Denose wrote:
> On Mon, Aug 18, 2025 at 6:10 PM Jonathan Denose <jdenose@...gle.com> wrote:
> >
> > Hello,
> >
> > This is an updated implementation of the interface for controlling haptic
> > touchpads.
> >
> > Below is an updated design proposal for the userspace and HID interfaces,
> > modified from what one of my colleagues submitted in 2019 [0].
> >
> > We would appreciate any feedback you might have.
> >
> > Thank you,
> >
> > Jonathan Denose
> > Chromium OS Team
> >
> > Background
> > ==========
> >
> > There are multiple independent projects to develop a touchpad with force sensors
> > and haptic actuators, instead of a traditional button.  These haptic touchpads
> > have several advantages and potential uses; they allow clicking across the
> > entire touchpad surface, adjusting the force requirement for clicks, haptic
> > feedback initiated by UI, etc. Supporting these features will potentially
> > require two new communication channels at the kernel level:
> > * Control of haptic motor by the host
> > * Force sensor data from device to host
> >
> > This document includes two related proposals:
> > 1. HID design proposal, that hardware makers would need to implement
> > 2. Kernel design proposal
> >
> > Objective
> > ==========
> >
> > Develop a standard protocol to allow userspace applications to communicate with
> > haptic touchpads, and minimize duplicated code and effort.
> >
> > Requirements:
> > 1. Support UI-initiated haptic feedback.
> > 2. Allow userspace to control when button press and button release haptic
> >    effects are triggered. (Useful when detecting a false click, changing force
> >    thresholds, or sending context-dependent effects).
> > 3. Reveal force sensor readings to userspace applications.
> > 4. Only allow OS-controlled haptic feedback for those systems which support it.
> >
> > Proposal
> > ========
> >
> > In order to minimize duplicated effort, we propose standardized haptic touchpad
> > support in the linux kernel.
> >
> > HID API
> > -------
> >
> > Modes
> > .....
> >
> > The haptic touchpad should be able to operate under two different modes.
> >
> > 1. Device-controlled mode
> >
> > The haptic touchpad should start up in "device-controlled mode"
> > (HID_HAPTIC_MODE_DEVICE), meaning it acts as a normal touchpad. This means it
> > should perform the press and release haptic feedback autonomously at predefined
> > force thresholds, and send the appropriate BTN_* events.
> >
> > 2. Host-controlled mode
> >
> > Once the touchpad has been confirmed as supporting haptics (described in more
> > detail in the the "Click and release control" section below), the device should
> > enter "host-controlled mode" (HID_HAPTIC_MODE_HOST). In this mode userspace
> > should take control. From here, userspace will take control over
> > press/release haptic feedback, relying on the effects sent by the kernel.
> >
> > Multitouch
> > ..........
> >
> > The HID API for multitouch reports should follow the Microsoft precision
> > touchpad spec [1], with the following changes:
> > * A tip pressure field [2] should be used to report the force. The physical unit
> >   Type (Newtons or grams), exponent, and limits should be reported in the
> >   report descriptor for the force field.
> > * The device will always report the button state according to its predefined
> >   force thresholds, even when not in device-controlled mode.
> > * The device must expose a "simple haptic controller" logical collection
> >   alongside the touchpad collection.
> >
> > Haptic control
> > ..............
> >
> > The HID protocol described in HUTRR63[3] must be used.
> >
> > The following waveforms should be supported:
> >
> > | WAVEFORMNONE             | Implicit waveforms required by protocol           |
> > | WAVEFORMSTOP             |                                                   |
> > | ------------------------ | ------------------------------------------------- |
> > | WAVEFORMPRESS            | To be used to simulate button press. In device-   |
> > |                          | controlled mode, it will also be used to simulate |
> > |                          | button release.                                   |
> > | ------------------------ | ------------------------------------------------- |
> > | WAVEFORMRELEASE          | To be used to simulate button release.            |
> >
> > All waveforms will have an associated duration; continuous waveforms will be
> > ignored by the kernel.
> >
> > Triggers & Mode switching
> > .........................
> >
> > The “auto trigger waveform” should be set to WAVEFORM_PRESS by default, and the
> > button from the touchpad collection should be set as the “auto trigger
> > associated control”.
> >
> > The kernel can trigger the different modes in the following ways:
> > * Device-controlled mode can be enabled by setting the “auto trigger waveform” to
> >   WAVEFORM_PRESS.
> > * Host-controlled mode can be enabled by setting the "auto trigger waveform" to
> >   WAVEFORM_STOP.
> >
> > The device must also support manual triggering. If intensity modification for
> > waveforms is supported by the device, the intensity control should be included
> > in the manual trigger output report. This allows modification of the intensity
> > on a per-waveform basis. Retriggering does not need to be supported by the
> > device.
> >
> > Userspace API
> > -------------
> >
> > Multitouch protocol
> > ...................
> >
> > ABS_MT_PRESSURE will be used to report force. The resolution of ABS_MT_PRESSURE
> > should also be defined and reported in force units of grams or Newtons.
> > ABS_PRESSURE should be reported as the total force applied to the touchpad.
> > When the kernel is in host-controlled mode, it should always forward the button
> > press and release events to userspace.
> >
> > Use Force Feedback protocol to request pre-defined effects
> > ..........................................................
> >
> > The force feedback protocol [4] should be used to control predefined effects.
> >
> > Typical use of the force feedback protocol requires loading effects to the
> > driver by describing the output waveform, and then requesting those effects
> > using an ID provided by the driver. However, for haptic touchpads we do not want
> > to describe the output waveform explicitly, but use a set of predefined effects,
> > which are identified by HID usage.
> >
> > The force feedback protocol will need to be extended to allow requests for HID
> > haptic effects. This requires a new feedback effect type:
> >
> > /**
> >  * struct ff_haptic_effect
> >  * @hid_usage: hid_usage according to Haptics page (WAVEFORM_CLICK, etc.)
> >  * @vendor_id: the waveform vendor ID if hid_usage is in the vendor-defined
> >  * range
> >  * @vendor_id: the vendor waveform page if hid_usage is in the vendor-defined
> >  * range
> >  * @intensity: strength of the effect
> >  * @repeat_count: number of times to retrigger effect
> >  * @retrigger_period: time before effect is retriggered (in ms)
> >  */
> > struct ff_haptic_effect {
> >         __u16 hid_usage;
> >         __u16 vendor_id;
> >         __u8  vendor_waveform_page;
> >         __s16 intensity;
> >         __u16 repeat_count;
> >         __u16 retrigger_period;
> > }
> >
> > Since the standard waveform id namespace does not overlap with the vendor
> > waveform id namespace, the vendor id and page can be ignored for standard
> > waveforms.
> >
> > Click and release control
> > .........................
> >
> > Haptic functionality shall be gated behind the HID_MULTITOUCH_HAPTIC kernel
> > configuration option, and this kernel configuration option should only be
> > enabled if userspace will support haptic capabilities. Haptic functionality will
> > only be initialized and used if HID_MULTITOUCH_HAPTIC is enabled, and if the
> > following conditions have been met:
> > * ABS_MT_PRESSURE is defined and reporting force units of Newtons or grams.
> > * The device supports haptic effects according to the hid protocol defined in
> >   HUTRR63 [3].
> > These checks will happen when the driver probes and initializes the multitouch
> > device.
> >
> > In the case when the kernel configuration option has been set and the device
> > reports pressure and haptic effects as defined above, the kernel will initialize
> > the haptic device and configure the haptic driver to signal that the touchpad is
> > haptic-compatible. To signal to userspace that the touchpad is haptic-compatible
> > the kernel will mark INPUT_PROP_HAPTIC_TOUCHPAD.
> >
> > With userspace willing and able to take control, the kernel will signal to the
> > device to exit device-controlled mode once a WAVEFORMPRESS or WAVEFORMRELEASE
> > event is uploaded. From here, userspace will take control over press/release
> > haptic feedback, relying on the effects sent by the kernel.
> >
> > In all other cases, the driver will take no action to enable haptic
> > functionality.
> >
> > Summary of normal use-case
> > 1. The kernel waits for userspace to upload WAVEFORMPRESS or
> >    WAVEFORMRELEASE.
> > 2. Userspace determines when a click has been performed based on its own
> >    criteria and tells the touchpad to perform a haptic effect.
> > 3. When userspace erases the WAVEFORMPRESS or WAVEFORMRELEASE effect, signal the
> >    device to return to device-controlled mode.
> >
> > [0]: https://www.spinics.net/lists/linux-input/msg60938.html
> > [1]: https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/touchpad-devices
> > [2]: Usage ID 0x30 of HID usage table 0x0D. See chapter 16:
> >      https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
> > [3]: https://www.usb.org/sites/default/files/hutrr63b_-_haptics_page_redline_0.pdf
> > [4]: https://www.kernel.org/doc/html/v4.20/input/ff.html
> >
> > Signed-off-by: Jonathan Denose <jdenose@...gle.com>
> > ---
> > Changes in v3:
> > - Change CONFIG_HID_HAPTIC from bool to tristate
> > - Fix devm_kzalloc calls in hid-multitouch.c to use correct device
> > - Minor comment cleanup + grammar fix
> > - Link to v2: https://lore.kernel.org/r/20250818-support-forcepads-v2-0-ca2546e319d5@google.com
> >
> > Changes in v2:
> > - Rename FF_HID and ff_hid_effect to FF_HAPTIC and ff_haptic_effect
> > - Add more detail to CONFIG_HID_HAPTIC config option description
> > - Remove CONFIG_MULTITOUCH_HAPTIC config option
> > - Utilize devm api in hid-multitouch haptic functions
> > - Link to v1: https://lore.kernel.org/all/20250714-support-forcepads-v1-0-71c7c05748c9@google.com
> >
> > ---
> > Angela Czubak (11):
> >       HID: add haptics page defines
> >       Input: add FF_HAPTIC effect type
> >       Input: add INPUT_PROP_HAPTIC_TOUCHPAD
> >       HID: haptic: introduce hid_haptic_device
> >       HID: input: allow mapping of haptic output
> >       HID: haptic: initialize haptic device
> >       HID: input: calculate resolution for pressure
> >       HID: haptic: add functions handling events
> >       Input: MT - add INPUT_MT_TOTAL_FORCE flags
> >       HID: haptic: add hid_haptic_switch_mode
> >       HID: multitouch: add haptic multitouch support
> >
> >  Documentation/input/event-codes.rst    |  14 +
> >  drivers/hid/Kconfig                    |  11 +
> >  drivers/hid/Makefile                   |   1 +
> >  drivers/hid/hid-haptic.c               | 580 +++++++++++++++++++++++++++++++++
> >  drivers/hid/hid-haptic.h               | 127 ++++++++
> >  drivers/hid/hid-input.c                |  18 +-
> >  drivers/hid/hid-multitouch.c           |  47 +++
> >  drivers/input/input-mt.c               |  14 +-
> >  include/linux/hid.h                    |  29 ++
> >  include/linux/input/mt.h               |   1 +
> >  include/uapi/linux/input-event-codes.h |   1 +
> >  include/uapi/linux/input.h             |  22 +-
> >  12 files changed, 858 insertions(+), 7 deletions(-)
> > ---
> > base-commit: 86731a2a651e58953fc949573895f2fa6d456841
> > change-id: 20250625-support-forcepads-0b4f74fd3d0a
> >
> > Best regards,
> > --
> > Jonathan Denose <jdenose@...gle.com>
> >
> Hi all,
> 
> Please let me know if there is anything else needed from me.
> 

Dmitry, I've just re-reviewed and tested this series. I'm fine with it.
Can you give us your ack on the input bits?

Cheers,
Benjamin

Powered by blists - more mailing lists