HIDQUIRK(4)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 HIDQUIRK — the HID quirks module, explained by your favorite nerd bestie

okay so welcome to hidquirk, a manual page from the FreeBSD Kernel Interfaces Manual (section 4, if you're keeping score 🎀). It's a whole module about telling the HID subsystem "bestie, this device is special, handle it accordingly" and honestly? iconic.

✨ NAME ✨

hidquirk — the HID quirks module. that's it, that's the vibe 🦋

🌸 SYNOPSIS 🌸

so there are two ways to get this into your life, and both are valid:

Option one — compile it into the kernel. drop this line in your kernel configuration file:

device hid

Option two — load the module at boot time. put this in loader.conf(5):

hidquirk_load="YES"

pick your fighter, both slay 💅

💖 DESCRIPTION 💖

The hidquirk module provides support for adding quirks for HID devices. Basically, when a device is a little weird and doesn't behave like the spec says it should, you give it a quirk and the kernel knows what's up. no cap.

Here's the whole roster, and yes every single one is here because I would never do you like that:

  • HQ_HID_IGNORE — device should be ignored by the hid class. not me, not today, we're skipping it 🙈
  • HQ_KBD_BOOTPROTO — device should set the boot protocol.
  • HQ_MS_BOOTPROTO — device should set the boot protocol. (yes, same description as the keyboard one — that's what the page says, I'm not out here editing facts ✨)
  • HQ_MS_BAD_CLASS — doesn't identify properly. it's giving mysterious.
  • HQ_MS_LEADING_BYTE — mouse sends an unknown leading byte.
  • HQ_MS_REVZ — mouse has Z-axis reversed. up is down, down is up, we love a plot twist.
  • HQ_MS_VENDOR_BTN — mouse has buttons in vendor usage page.
  • HQ_SPUR_BUT_UP — spurious mouse button up events. ghost clicks fr fr 💀
  • HQ_MT_TIMESTAMP — Multitouch device exports HW timestamps 0x1b5a01.
See /sys/dev/hid/hidquirk.h for the complete list of supported quirks. that file is the main character, go read it 🔥

👑 LOADER TUNABLE 👑

okay this part is the actual tea ☕ the following tunable can be set at the loader(8) prompt before booting the kernel, or stored in loader.conf(5).

  • hw.hid.quirk.%d — the value is a string whose format is:
"BusId VendorId ProductId LowRevision HighRevision HQ_QUIRK,..."

Installs the quirks HQ_QUIRK,... for all HID devices matching BusId and VendorId and ProductId which have a hardware revision between and including LowRevision and HighRevision.

BusId, VendorId, ProductId, LowRevision and HighRevision are all 16 bits numbers which can be decimal or hexadecimal based. so like, 0x18 and 24 are both fine, pick whichever makes your heart happy 🌈

A maximum of 100 variables hw.hid.quirk.0, .1, ..., .99 can be defined. that's the cap, bestie, there is no 101 💅

If a matching entry is found in the kernel's internal quirks table, it is replaced by the new definition. Else a new entry is created given that the quirk table is not full.

The kernel iterates over the hw.hid.quirk.N variables starting at N = 0 and stops at N = 99 or the first non-existing one. so don't leave a gap in the middle unless you want everything after it to be ignored, iykyk 🫶

🦋 EXAMPLES 🦋

To install a quirk at boot time, place one or several lines like the following in loader.conf(5):

hw.hid.quirk.0="0x18 0x6cb 0x1941 0 0xffff HQ_MT_TIMESTAMP"

look at that. chef's kiss. ate and left no crumbs 🍓

⭐ HISTORY ⭐

The hidquirk module appeared in FreeBSD 13.0. a legend was born ✨

💜 AUTHORS 💜

The hidquirk driver was written by Hans Petter Selasky <hselasky@FreeBSD.org> for usb(4) subsystem and adopted to hid(4) by Vladimir Kondratyev <wulf@FreeBSD.org>. This manual page is based on usb_quirk(4) manual page written by Nick Hibma <n_hibma@FreeBSD.org>.

and that's the whole page, bestie. go forth and quirk responsibly 🧚

mwah 💋 this one came from the Debian build, dated September 16, 2020 — stay hydrated, read your hidquirk.h, and see you in the next man page 🎀💅

📦 where this page comes from