Repository files navigation

• USB mice on Linux
  • Linux kernel driver usbhid
  • On Wayland
  • On X Window System
  • On text console/virtual terminal
  • USB auto-suspend
  • USB mouse disconnects/reconnects every minute
• USB mouse in virtual machines
• Wireless and Bluetooth mice

Everything in this howto relates to openSUSE Leap 15.3 but is mostly applicableto other Linux distros as well.

Author:Sebastian Parschauer

This document has been created with the help of colleagues when I workedat SUSE. But opinions are my own. Furthermore, this work is subject tocontinuous improvements.All contributions are welcome.Please just open issues on GitHub to start the discussion.

USB optical mice are usually based on a single chip from PixArt Imaging.An example is thePAN3511identifying itself with USB IDs093a:2510.

Many USB mice support using them as PS/2 mouse as well (e.g. with an adapter).They also support a PS/2 legacy data report protocol. This is important forusing them on the text consoles/virtual terminals (VT) as well. Currently thereis support for the general USB report protocol only on the display servers onLinux. See section 5 "USB Interface" in the PAN3511 datasheet for hardwaredetails.

Almost all wired USB mice use theusbhid driver but an additional user-spacedriver is required. usbhid devices usually use the USB interrupt transfer. Sothe default behavior of the driver is to wait for interrupts. But this can causebuffers in some devices to overflow. So the usbhid quirk fixHID_QUIRK_ALWAYS_POLL is often required for USB mice to work properly withouta user-space driver running.

The problem is that it can only use the USB vendor ID and product ID to identifyif a quirk fix is required. And with more modern chips than the PAN3511, the USBIDs can be modified. So often quirk fixes for mice with the same chips butdifferent IDs are missing.

The quirks tablehid_quirks is located indrivers/hid/hid-quirks.cand theusbhid vendor/product IDs are located indrivers/hid/hid-ids.hof the Linux kernel source. Another important kernel source file isinclude/linux/hid.hcontaining the quirk defines. It shows thatHID_QUIRK_ALWAYS_POLL has thevalue0x00000400 (BIT(10)).

A usbhid quirk can also be set by the kernel boot optionusbhid.quirks.E.g.usbhid.quirks=0x413c:0x301a:0x00000400 setsHID_QUIRK_ALWAYS_POLLfor the Dell MS116 mouse with idVendor0x413c and idProduct0x301a.Usually up to four usbhid quirks can be provided in a comma-separated list.WithHID_QUIRK_IGNORE (0x00000004) it is also possible to exclude a device.The USB IDs can be displayed withlsusb -vvv.

If you find out that a quirk fix is required for your device, then please opena GitHub issue here for discussion. The relevant mailing list islinux-inputonvger.kernel.org to get it fixed in the upstream kernel.

Inhid-quirks.c there is also a listhid_have_special_driver to specify whichdevices come with a special driver. This usually includes gaming mice like theones from Roccat.

Recent changes:

• v4.16: quirks moved fromhid_blacklist indrivers/hid/usbhid/hid-quirks.c tohid_quirks indrivers/hid/hid-quirks.c

Wayland compositors uselibinput. In GNOME Wayland sessions, thegnome-shellprocesses are the ones loading it. It is the user-space driver for all inputdevices.

Documentation:libinput

List available input devices:

zypper install libinput-toolslibinput list-devices

Test the mouse events:

zypper install evtestevtest --grab /dev/input/event23

Use the event device which you have found for your mouse. My Dell MS116 mouseis at/dev/input/event23 here. Typical events areBTN_LEFT,BTN_RIGHT,BTN_MIDDLE,REL_X,REL_Y, andREL_WHEEL.

Modern Linux systems uselibinput with thexf86-input-libinput package forthe X server as well. This way it integrates nicely if the X server is runningon top of Wayland to provide compatibility.

Mouse support on the X Window System usually works fine on all Linux distroswith almost all USB mice.

Documentation:

• man 4 libinput
• libinput

Alternatives are the packagesxf86-input-mouse andxf86-input-evdev.

Use the following command to check which input driver is running:

xpid=$(pidof -s Xorg); if [ -z "$xpid" ]; then xpid=$(pidof -s X); fi; \sudo cat /proc/$xpid/maps | grep input

The packagexf86-input-mouse is usually only used on non-Linux systems.

Documentation:

• man mousedrv
• less /usr/share/doc/packages/xf86-input-mouse/README

In contrast to that, the packagexf86-input-evdev provides another genericLinux input driver.

Documentation:

• man evdev
• less /usr/share/doc/packages/xf86-input-evdev/README

If you want to use your PS/2 capable USB mouse on a VT as well, then you needGPM (General Purpose Mouse) from packagegpm. It provides a "gpm" systemdservice which is usually disabled by default. Its config is located at/etc/sysconfig/mouse.

Default config:

MOUSEDEVICE="/dev/input/mice"MOUSETYPE="imps2"GPM_PARAM=""GPM_REPEAT=""

This config is exactly what we need. Just enable and start the gpm service inyour services manager (e.g. with YaST2) and your PS/2 capable USB mouse shouldwork on your VTs.

Note: In some cases a reboot might be required after enabling and startinggpm.

The supported mouse protocols/types can be displayed with the following commandexecuted as root:

gpm -m /dev/input/mice -t help | less

Forimps2 it shows:

* imps2    Microsoft Intellimouse (ps2)-autodetect 2/3 buttons,wheel unused

Mice often don't work well with USB auto-suspend. It is safest to disable itcompletely by the kernel boot optionusbcore.autosuspend=-1 to check if themouse is affected.

It is also possible to blacklist certain devices. It depends if they arecontrolled bytlp, thelaptop-mode-tools, or the kernel directly. Thereare enough howtos on the web for this.

openSUSE USB power management

Let's look at a Dell MS116 optical USB mouse. This is a PixArt OEM mouse. Itreally annoyed me that it spammed the virtual terminal and the kernel log withUSB disconnect messages every minute without a user-space driver running:

[12334.243124] usb 3-14: USB disconnect, device number 12[12335.748073] usb 3-14: new low-speed USB device number 13 using xhci_hcd[12335.879685] usb 3-14: New USB device found, idVendor=413c, idProduct=301a[12335.879689] usb 3-14: New USB device strings: Mfr=1, Product=2, SerialNumber=0[12335.879691] usb 3-14: Product: Dell MS116 USB Optical Mouse[12335.879696] usb 3-14: Manufacturer: PixArt[12335.881821] input: PixArt Dell MS116 USB Optical Mouse as /devices/pci0000:00/0000:00:14.0/usb3/3-14/3-14:1.0/0003:413C:301A.000A/input/input19[12335.882034] hid-generic 0003:413C:301A.000A: input,hidraw1: USB HID v1.11 Mouse [PixArt Dell MS116 USB Optical Mouse] on usb-0000:00:14.0-14/input0

Disconnecting it physically everytime you use the VT is no good option.Itsbuffer overflows if it is not always polled. This can be fixed by activatingthegpm service and a reboot, or even better by the kernel boot optionusbhid.quirks=0x413c:0x301a:0x00000400 as this is ausbhid bug.

The bit mask0x00000400 activatesHID_QUIRK_ALWAYS_POLL.

For details see:Linux kernel driver usbhid

Fixing the Upstream Kernel

Of cause I've senta patchfor this to thelinux-usb mailing list (beforev4.16) which got accepted.As I've sent it to the linuxstable mailing list as well, this is fixed forall Linux distributions now.

PixArt mice with this HW issue are known from vendorsAlienware, Chicony, Dell, HP, Lenovo, Microsoft, PixArt, and Primax.
Further suspects are Acer Lite-On, Dynex, and Jesis(see#22).
Please let me know if your mouse is affectedasissues often persist for years.

There is a strong indication that PixArt chips useLogitech firmware withthat bug. Before integration, the sensor chips were usually coupled with aLogitech USB mouse controller IC and PixArt ICs with that bug can be found inLogitech mice as well. E.g. the Dell MS111-L is a Logitech PixArt mouserequiring the quirk fix as well (IDs046d:c077, see#19).

It is most common in virtual machines that the mouse cursor is not located whereit should be. Windows VMs requireabsolute mouse movement and Linux VMsrequirerelative mouse movement. Make sure that this is properly set e.g.invirt-manager.

With very old Linux distributions which still use GNOME 2 like e.g. SLES11, theQEMUEvTouch USB Graphics Tablet emulation does not work properly. Remove itand add aGeneric USB Mouse instead.

Do yourself and people around you a favor and avoid using those due to harmfulpulsed microwave radiation at2.4 GHz. The related topic iselectrosmog.It can be measured e.g. with the EMFields Acousticom 2.

See e.g.:https://swissharmony.com/what-is-electrosmog/
German:https://www.elektrosmog.com/forschungsergebnisse-zu-biologischen-wirkungen-von-mikrowellen

EspeciallyLogitech/Unifying based devices are often found to benot optimized in this regard and can causewrist pain as the mostobvious effect.

With the long range those can also be a majorsecurity issue.