---
name: "usb_quirk"
section: "4"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/usb_quirk"
---

# usb\_quirk(4)

USB quirks module

## NAME

**usb\_quirk** – USB quirks module

## SYNOPSIS

To compile this module into the kernel, place the following line in your kernel configuration file:

**device usb**

Alternatively, to load the module at boot time, place the following line in [loader.conf(5)](/loader.conf/5.md):

```
usb_quirk_load="YES"
```

## DESCRIPTION

The **usb\_quirk** module provides support for dynamically adding and removing quirks for USB devices with [usbconfig(8)](/usbconfig/8.md).

## General quirks:

- UQ\_AUDIO\_SWAP\_LR

  swap left and right channels

- UQ\_AU\_INP\_ASYNC

  input is async despite claim of adaptive

- UQ\_AU\_NO\_FRAC

  do not adjust for fractional samples

- UQ\_AU\_NO\_XU

  audio device has broken extension unit

- UQ\_AU\_VENDOR\_CLASS

  audio device uses vendor class to identify itself

- UQ\_AU\_SET\_SPDIF\_CM6206

  audio device needs special programming to enable S/PDIF audio output

- UQ\_BAD\_ADC

  bad audio spec version number

- UQ\_BAD\_AUDIO

  device claims audio class, but is not

- UQ\_BROKEN\_BIDIR

  printer has broken bidir mode

- UQ\_BUS\_POWERED

  device is bus powered, despite claim

- UQ\_HID\_IGNORE

  device should be ignored by hid class

- UQ\_KBD\_IGNORE

  device should be ignored by kbd class

- UQ\_KBD\_BOOTPROTO

  device should set the boot protocol

- UQ\_UMS\_IGNORE

  device should be ignored by ums class

- UQ\_MS\_BAD\_CLASS

  does not identify properly

- UQ\_MS\_LEADING\_BYTE

  mouse sends an unknown leading byte

- UQ\_MS\_REVZ

  mouse has Z-axis reversed

- UQ\_MS\_VENDOR\_BTN

  mouse has buttons in vendor usage page

- UQ\_NO\_STRINGS

  string descriptors are broken

- UQ\_POWER\_CLAIM

  hub lies about power status

- UQ\_SPUR\_BUT\_UP

  spurious mouse button up events

- 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\_IGNORE\_CDC\_CM

  ignore cm descriptor

- UQ\_WMT\_IGNORE

  device should be ignored by 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)

- 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

See */sys/dev/usb/quirk/usb\_quirk.h* or run "usbconfig dump\_quirk\_names" for the complete list of supported quirks.

## LOADER TUNABLE

The following tunable can be set at the [loader(8)](/loader/8.md) prompt before booting the kernel, or stored in [loader.conf(5)](/loader.conf/5.md).

- *hw.usb.quirk.%d*

  The value is a string whose format is:

  ```
  "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.

  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)](/loader.conf/5.md):

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

## SEE ALSO

[usbconfig(8)](/usbconfig/8.md)

## 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*⟩.