Message-ID: <CAMCVhVN+5aigp7WMkTpfdUgNrzRSsQbNeF7dw0z=s7Zj2uythQ@mail.gmail.com>
Date: Wed, 23 Jul 2025 14:59:22 -0500
From: Jonathan Denose <jdenose@...gle.com>
To: Jiri Kosina <jikos@...nel.org>, Benjamin Tissoires <bentiss@...nel.org>, 
	Dmitry Torokhov <dmitry.torokhov@...il.com>, Jonathan Corbet <corbet@....net>, 
	Henrik Rydberg <rydberg@...math.org>
Cc: 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 00/11] HID: Implement haptic forcepad support

On Mon, Jul 14, 2025 at 10:09 AM 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_hid_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_hid_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>
> ---
> Angela Czubak (11):
>       HID: add haptics page defines
>       Input: add FF_HID 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                    |  20 ++
>  drivers/hid/Makefile                   |   1 +
>  drivers/hid/hid-haptic.c               | 580 +++++++++++++++++++++++++++++++++
>  drivers/hid/hid-haptic.h               | 131 ++++++++
>  drivers/hid/hid-input.c                |  18 +-
>  drivers/hid/hid-multitouch.c           | 136 +++++++-
>  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, 959 insertions(+), 8 deletions(-)
> ---
> base-commit: 86731a2a651e58953fc949573895f2fa6d456841
> change-id: 20250625-support-forcepads-0b4f74fd3d0a
>
> Best regards,
> --
> Jonathan Denose <jdenose@...gle.com>
>
Hello,

Gently bumping this patch series for initial review if anyone has some
bandwidth to give it a look.

Please feel free to let me know if you have any questions!

Thanks,
--
Jonathan

Powered by blists - more mailing lists