USB_QUIRK(4)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ usb_quirk — the USB quirks module ✨

okay bestie, pull up a chair 🎀 this is USB_QUIRK(4) from the Kernel Interfaces Manual, and it's literally the glow-up your janky USB hardware has been begging for 💅

🌸 NAME 🌸

usb_quirk — the USB quirks module, aka the "your device is lying but we still love it" module 🫶

🦋 SYNOPSIS 🦋

so to bake this module straight into the kernel, you drop this line into your kernel config file:

device usb

orrr, if you'd rather load it at boot time (very main character of you), you put this in loader.conf(5):

usb_quirk_load="YES"

💖 DESCRIPTION 💖

The usb_quirk module is the one that lets you dynamically add and remove quirks for USB devices, using usbconfig(8). no cap. it's giving fix-it energy ✨

🎀 General quirks 🎀

  • UQ_AUDIO_SWAP_LR — swap left and right channels, because your ears deserve the correct sides
  • UQ_AU_INP_ASYNC — the input is async, despite what it claims about being adaptive
  • UQ_AU_NO_FRAC — do not adjust for fractional samples
  • UQ_AU_NO_XU — this audio device has a broken extension unit 😭
  • UQ_AU_VENDOR_CLASS — the audio device uses vendor class to identify itself (identity crisis, honestly)
  • UQ_AU_SET_SPDIF_CM6206 — this audio device needs special programming to enable S/PDIF audio output
  • UQ_BAD_ADC — bad audio spec version number
  • UQ_BAD_AUDIO — the device claims to be audio class, but it is NOT. liar behavior 💀
  • UQ_BROKEN_BIDIR — printer has broken bidir mode
  • UQ_BUS_POWERED — the device is bus powered, despite its claims
  • UQ_HID_IGNORE — this device should be ignored by the hid class
  • UQ_KBD_IGNORE — this device should be ignored by the kbd class
  • UQ_KBD_BOOTPROTO — this device should set the boot protocol
  • UQ_UMS_IGNORE — this device should be ignored by the ums class
  • UQ_MS_BAD_CLASS — does not identify properly (we've all been there 🙈)
  • UQ_MS_LEADING_BYTE — the mouse sends an unknown leading byte
  • UQ_MS_REVZ — the mouse has its Z-axis reversed
  • UQ_NO_STRINGS — string descriptors are broken
  • UQ_POWER_CLAIM — the hub lies about its power status
  • UQ_SPUR_BUT_UP — spurious mouse button up events (stop clicking at me!!)
  • UQ_SWAP_UNICODE — has some Unicode strings swapped
  • UQ_CFG_INDEX_1 — select configuration index 1 by default
  • UQ_CFG_INDEX_2 — select configuration index 2 by default
  • UQ_CFG_INDEX_3 — select configuration index 3 by default
  • UQ_CFG_INDEX_4 — select configuration index 4 by default
  • UQ_CFG_INDEX_0 — select configuration index 0 by default
  • UQ_ASSUME_CM_OVER_DATA — assume cm over data feature
  • UQ_WMT_IGNORE — this device should be ignored by the wmt driver

💅 USB Mass Storage quirks 💅

  • UQ_MSC_NO_TEST_UNIT_READY — send start/stop instead of TUR
  • UQ_MSC_NO_RS_CLEAR_UA — does not reset Unit Att.
  • UQ_MSC_NO_START_STOP — does not support start/stop
  • UQ_MSC_NO_GETMAXLUN — does not support get max LUN
  • UQ_MSC_NO_INQUIRY — fake generic inq response
  • UQ_MSC_NO_INQUIRY_EVPD — does not support inq EVPD
  • UQ_MSC_NO_SYNC_CACHE — does not support sync cache
  • UQ_MSC_SHUTTLE_INIT — requires Shuttle init sequence
  • UQ_MSC_ALT_IFACE_1 — switch to alternate interface 1
  • UQ_MSC_FLOPPY_SPEED — does floppy speeds (20kb/s) 🐌 iconic retro moment
  • UQ_MSC_IGNORE_RESIDUE — gets residue wrong
  • UQ_MSC_WRONG_CSWSIG — uses wrong CSW signature
  • UQ_MSC_RBC_PAD_TO_12 — pad RBC requests to 12 bytes
  • UQ_MSC_READ_CAP_OFFBY1 — reports sector count, not max sec.
  • UQ_MSC_FORCE_SHORT_INQ — does not support full inq.
  • UQ_MSC_FORCE_WIRE_BBB — force BBB wire protocol
  • UQ_MSC_FORCE_WIRE_CBI — force CBI wire protocol
  • UQ_MSC_FORCE_WIRE_CBI_I — force CBI with int. wire protocol
  • UQ_MSC_FORCE_PROTO_SCSI — force SCSI command protocol
  • UQ_MSC_FORCE_PROTO_ATAPI — force ATAPI command protocol
  • UQ_MSC_FORCE_PROTO_UFI — force UFI command protocol
  • UQ_MSC_FORCE_PROTO_RBC — force RBC command protocol

🌈 3G Datacard (u3g) quirks 🌈

  • UQ_MSC_EJECT_HUAWEI — ejects after Huawei USB command
  • UQ_MSC_EJECT_SIERRA — ejects after Sierra USB command
  • UQ_MSC_EJECT_SCSIEJECT — ejects after SCSI eject command 0x1b0000000200
  • UQ_MSC_EJECT_REZERO — ejects after SCSI rezero command 0x010000000000
  • UQ_MSC_EJECT_ZTESTOR — ejects after ZTE SCSI command 0x850101011801010101010000
  • UQ_MSC_EJECT_CMOTECH — ejects after C-motech SCSI command 0xff52444556434847
  • UQ_MSC_EJECT_WAIT — wait for the device to eject
  • UQ_MSC_EJECT_SAEL_M460 — ejects after Sael USB commands
  • UQ_MSC_EJECT_HUAWEISCSI — ejects after Huawei SCSI command 0x11060000000000000000000000000000
  • UQ_MSC_EJECT_TCT — ejects after TCT SCSI command 0x06f504025270
  • UQ_MSC_DYMO_EJECT — ejects after HID command 0x1b5a01
psst 👀 for the complete list of supported quirks, peek at /sys/dev/usb/quirk/usb_quirk.h or run usbconfig dump_quirk_names. slay.

🔥 LOADER TUNABLE 🔥

you can set the following tunable at the loader(8) prompt before booting the kernel, or just store it in loader.conf(5). either way, it's valid 💜

  • hw.usb.quirk.%d — the value is a string, and the format goes like this:
"VendorId ProductId LowRevision HighRevision UQ_QUIRK,..."

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

VendorId, ProductId, LowRevision and HighRevision are all 16 bits numbers which can be decimal or hexadecimal based. math is math ✨

A maximum of 100 variables hw.usb.quirk.0, .1, ..., .99 can be defined.

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.usb.quirk.N variables starting at N = 0 and stops at N = 99 or the first non-existing one.

⭐ EXAMPLES ⭐

After attaching a u3g device which appears as a USB device on ugen0.3:

usbconfig -d ugen0.3 add_quirk UQ_MSC_EJECT_WAIT

Enable a Holtec/Keep Out F85 gaming keyboard on ugen1.4:

usbconfig -d ugen1.4 add_quirk UQ_KBD_BOOTPROTO

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

hw.usb.quirk.0="0x04d9 0xfa50 0 0xffff UQ_KBD_IGNORE"

👑 SEE ALSO 👑

usbconfig(8)

🌸 HISTORY 🌸

The usb_quirk module appeared in FreeBSD 8.0, and was written by Hans Petter Selasky <hselasky@FreeBSD.org>. This manual page was written by Nick Hibma <n_hibma@FreeBSD.org>. absolute legends, we stan 🫶

and that's the whole page bestie 💖 this one came from Debian, dated August 19, 2017, filed under USB_QUIRK(4) — go forth and quirk responsibly, periodt 💅✨

📦 where this page comes from