[PATCH RFC 0/4] HID: logitech: add Bolt support with HID++ input handling

["Erik Håkansson" <erikhakan@gmail.com>]

This series is posted as an RFC for review and hardware testing since the
previous patch had some issues and had to be reverted. It is not ready for
merging pending testing and discussion of defaults.
The series adds Bolt receiver support to the Logitech HID++ and DJ drivers,
with revised native input handling and HID++ wheel diversion.

Original patch: https://lore.kernel.org/linux-input/20260712003051.338194-1-erikhakan@gmail.com/

The original approach failed to use the correct descriptor for the virtual
Bolt mouse device, which may have caused mouse reports to be incorrectly
interpreted. In an attempt to fix that, the second approach was to not let
the DJ driver claim interfaces 0 and 1, and thus let the generic HID
handler handle native keyboard and mouse reports. This had the side effect
of incorrect scroll scaling for 0x2121 (hi-res scroll) devices, and
attempts to fix that caused various side-effects, especially when used
together with user-space settings for scrolling.
Attempts to fix everything failed to account for the fact that we were
treating Bolt devices differently than other non-DJ devices.

Further, some attempts of fixing tried to rely on storing user settings
on-device, but these do not seem to survive reconnect or turning off and on
when tested in the Bolt MX Keys or Lightspeed G502.

This series aims to fix all of this, while also preferring HID++ reports
for Bolt mice to allow for device identification, despite the fact that
Bolt receivers do not support DJ mode. Regular mouse and keyboard events
will still be native HID events and can't be identified per device.

- Handle Bolt mice the same way as e.g. Lightspeed mice are handled, i.e.
  let the DJ driver claim interfaces 0-2 and use the existing 16-bit mouse
  descriptor for the virtual mouse.
- Fix diverted 0x2121 HID++ wheel movement, including resolution and
  software-side inversion when scroll direction is inverted. Also, handle
  both low- and high-resolution reports coming over HID++. Bolt devices
  have HID++ diversion enabled by default.
- Add HID++ 0x2150 thumbwheel handling, with device-provided scaling and
  direction. Bolt devices have HID++ diversion enabled by default.
- Extend the M650 Back/Forward diversion quirk to devices connected through
  the Bolt receiver.
- Add HID++ 0x2130 ratchet-wheel handling. Bolt devices have HID++
  diversion enabled by default.

HID++ diversion supplies a device index, allowing supported wheel events to
be attributed and scaled per device. Ordinary native mouse and keyboard
reports still lack that index. Their source remains ambiguous when several
devices share a receiver; this series does not solve that limitation.

Non-Bolt wheel-reporting defaults remain unchanged, however the 0x2121
general behaviour has been changed. Instead of first setting
high-resolution mode and then attempting to fetch 0x2121 capabilities (and
thus scale) from the device, we now get the capabilities first.
Previously, in case of failure to fetch, high-resolution scroll reports
would be scaled as low-resolution, or whichever scale already existed. Now,
if we fail to fetch capabilities, we request low-resolution native HID and
set the scale to 1.

All settings are applied at device connect (or driver load), and userspace
may override afterwards. Solaar is known to apply its settings a few
seconds after the kernel driver is loaded for a device.
Userspace changes to wheel resolution, diversion and inversion should now
be handled correctly. These combinations still require hardware testing.

A risk with this series is that for testing I only have access to an MX
Keys for Business over Bolt and a G502 over Lightspeed. The series has been
tested with both and works as expected, but it needs testing with as many
devices as possible to ensure none of the previous issues remain.

The following items need to be tested:
1. First and foremost, the 16-bit descriptor finding was based on looking
   at the native descriptor from the Bolt receiver and not something I
   could test myself without a Bolt mouse.
   Hence, just regular mouse movement needs to be verified with a few
   different devices.
2. Further, scrolling with a 0x2121-supporting device (i.e. high-resolution
   scrolling) needs to be tested with Solaar set to all four combinations
   of HID++ diversion + resolution, and all four combinations of HID++
   diversion + scroll direction inversion.
3. MX Master 4 thumbwheel (0x2150, or any other mouse with this), diversion
   on and off in Solaar.
4. M650 Back/Forward clicks when connected over Bolt.
5. Ratchet wheel (0x2130, I think Signature M650 and M750 support this,
   from issue reports online) with diversion on and off in Solaar.
6. For all devices, testing so everything works after turning off and on,
   after reconnecting, after reboot, after switching to Bluetooth and back.
7. There was previously one report of scrambled keyboard input for a Logi
   POP Icon Keys when letting the keyboard interface be claimed by the DJ
   driver. This issue was never traced to a root cause and may have been
   unrelated. It has not been replicated on MX Keys. It should be retested.

Besides testing, a few decisions need to be made:

A. Currently, no HID++ diversion is enabled for keyboards, but at least MX
   Keys for Business supports diverting some keys over HID++. These include
   e.g. media keys, brightness control, etc. Some proprietary keys ONLY go
   over HID++ and do not support native HID at all.
   However, the use case for diverting only some keys seems small. Without
   diverting the entire keyboard, it can't be used for e.g. separate
   layout, or remapping all keys on only one keyboard, etc. The only
   possible use case is for special treatment of only those few divertable
   keys.
   However, the downside is that not all keycodes map to native HID
   keycodes so a list of all diverted key mappings needs to be maintained.
   Further, it might interfere with keyboards that support reprogramming
   keys.
   I could add it anyway though, either in this series or in a future
   patch?
   On the MX Keys S, a few keys seem to only work when diverted, or are
   diverted always, such as FN lock, mute microphone, backlight up/down,
   etc. These HID++ events currently have no handler in this driver.

B. Bolt devices now default to diverting the various scroll events to
   HID++. This is to be able to separate those events by originating
   device, in case their settings or support differ, so e.g. scroll
   resolution scaling will be applied correctly per device, instead of
   scaling different-resolution devices according to one device's scaling.
   But the use case of having multiple mice on the same Bolt receiver is
   rare, and perhaps it's better to let Bolt devices default to native HID
   and let the user override with Solaar if necessary?

   tshark captures of a Windows guest using MX Keys for Business suggest
   that the Windows driver enables HID++ diversion for keys, but this is
   not verified for mice.

Finally, thanks to Rafael Passos for the original Bolt HID++ wheel-event
work. The related Magnetar-OS patches were also used as inspiration:
https://github.com/Magnetar-OS/logitech-bolt-hidpp-dkms/tree/main/patches

Signed-off-by: Erik Håkansson <erikhakan@gmail.com>
---
Erik Håkansson (4):
      HID: logitech: add Bolt receiver support
      HID: logitech: handle HID++ thumbwheel reports
      HID: logitech: divert M650 side buttons over Bolt
      HID: logitech-hidpp: support ratchet wheel

 drivers/hid/hid-logitech-dj.c    |  33 ++-
 drivers/hid/hid-logitech-hidpp.c | 471 ++++++++++++++++++++++++++++++++++++---
 2 files changed, 464 insertions(+), 40 deletions(-)
---
base-commit: d72f75f1d9c038ead2588b42de6c2531e3b80bea
change-id: 20261001-bolt-input-rfc-9748607cc6b2

Best regards,
-- 
Erik Håkansson <erikhakan@gmail.com>