1.\" 2.\" Copyright (c) 2010 AnyWi Technologies 3.\" All rights reserved. 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd August 19, 2017 18.Dt USB_QUIRK 4 19.Os 20.Sh NAME 21.Nm usb_quirk 22.Nd USB quirks module 23.Sh SYNOPSIS 24To compile this module into the kernel, 25place the following line in your 26kernel configuration file: 27.Bd -ragged -offset indent 28.Cd "device usb" 29.Ed 30.Pp 31Alternatively, to load the module at boot 32time, place the following line in 33.Xr loader.conf 5 : 34.Bd -literal -offset indent 35usb_quirk_load="YES" 36.Ed 37.Sh DESCRIPTION 38The 39.Nm 40module provides support for dynamically adding and removing quirks for 41USB devices with 42.Xr usbconfig 8 . 43.Sh General quirks: 44.Bl -tag -width Ds 45.It UQ_AUDIO_SWAP_LR 46swap left and right channels 47.It UQ_AU_INP_ASYNC 48input is async despite claim of adaptive 49.It UQ_AU_NO_FRAC 50do not adjust for fractional samples 51.It UQ_AU_NO_XU 52audio device has broken extension unit 53.It UQ_AU_VENDOR_CLASS 54audio device uses vendor class to identify itself 55.It UQ_AU_SET_SPDIF_CM6206 56audio device needs special programming to enable S/PDIF audio output 57.It UQ_BAD_ADC 58bad audio spec version number 59.It UQ_BAD_AUDIO 60device claims audio class, but is not 61.It UQ_BROKEN_BIDIR 62printer has broken bidir mode 63.It UQ_BUS_POWERED 64device is bus powered, despite claim 65.It UQ_HID_IGNORE 66device should be ignored by hid class 67.It UQ_KBD_IGNORE 68device should be ignored by kbd class 69.It UQ_KBD_BOOTPROTO 70device should set the boot protocol 71.It UQ_UMS_IGNORE 72device should be ignored by ums class 73.It UQ_MS_BAD_CLASS 74does not identify properly 75.It UQ_MS_LEADING_BYTE 76mouse sends an unknown leading byte 77.It UQ_MS_REVZ 78mouse has Z-axis reversed 79.It UQ_MS_VENDOR_BTN 80mouse has buttons in vendor usage page 81.It UQ_NO_STRINGS 82string descriptors are broken 83.It UQ_POWER_CLAIM 84hub lies about power status 85.It UQ_SPUR_BUT_UP 86spurious mouse button up events 87.It UQ_SWAP_UNICODE 88has some Unicode strings swapped 89.It UQ_CFG_INDEX_1 90select configuration index 1 by default 91.It UQ_CFG_INDEX_2 92select configuration index 2 by default 93.It UQ_CFG_INDEX_3 94select configuration index 3 by default 95.It UQ_CFG_INDEX_4 96select configuration index 4 by default 97.It UQ_CFG_INDEX_0 98select configuration index 0 by default 99.It UQ_ASSUME_CM_OVER_DATA 100assume cm over data feature 101.It UQ_IGNORE_CDC_CM 102ignore cm descriptor 103.It UQ_WMT_IGNORE 104device should be ignored by wmt driver 105.El 106.Sh USB Mass Storage quirks: 107.Bl -tag -width Ds 108.It UQ_MSC_NO_TEST_UNIT_READY 109send start/stop instead of TUR 110.It UQ_MSC_NO_RS_CLEAR_UA 111does not reset Unit Att. 112.It UQ_MSC_NO_START_STOP 113does not support start/stop 114.It UQ_MSC_NO_GETMAXLUN 115does not support get max LUN 116.It UQ_MSC_NO_INQUIRY 117fake generic inq response 118.It UQ_MSC_NO_INQUIRY_EVPD 119does not support inq EVPD 120.It UQ_MSC_NO_SYNC_CACHE 121does not support sync cache 122.It UQ_MSC_SHUTTLE_INIT 123requires Shuttle init sequence 124.It UQ_MSC_ALT_IFACE_1 125switch to alternate interface 1 126.It UQ_MSC_FLOPPY_SPEED 127does floppy speeds (20kb/s) 128.It UQ_MSC_IGNORE_RESIDUE 129gets residue wrong 130.It UQ_MSC_WRONG_CSWSIG 131uses wrong CSW signature 132.It UQ_MSC_RBC_PAD_TO_12 133pad RBC requests to 12 bytes 134.It UQ_MSC_READ_CAP_OFFBY1 135reports sector count, not max sec. 136.It UQ_MSC_FORCE_SHORT_INQ 137does not support full inq. 138.It UQ_MSC_FORCE_WIRE_BBB 139force BBB wire protocol 140.It UQ_MSC_FORCE_WIRE_CBI 141force CBI wire protocol 142.It UQ_MSC_FORCE_WIRE_CBI_I 143force CBI with int. wire protocol 144.It UQ_MSC_FORCE_PROTO_SCSI 145force SCSI command protocol 146.It UQ_MSC_FORCE_PROTO_ATAPI 147force ATAPI command protocol 148.It UQ_MSC_FORCE_PROTO_UFI 149force UFI command protocol 150.It UQ_MSC_FORCE_PROTO_RBC 151force RBC command protocol 152.El 153.Sh 3G Datacard (u3g) quirks: 154.Bl -tag -width Ds 155.It UQ_MSC_EJECT_HUAWEI 156ejects after Huawei USB command 157.It UQ_MSC_EJECT_SIERRA 158ejects after Sierra USB command 159.It UQ_MSC_EJECT_SCSIEJECT 160ejects after SCSI eject command 161.Dv 0x1b0000000200 162.It UQ_MSC_EJECT_REZERO 163ejects after SCSI rezero command 164.Dv 0x010000000000 165.It UQ_MSC_EJECT_ZTESTOR 166ejects after ZTE SCSI command 167.Dv 0x850101011801010101010000 168.It UQ_MSC_EJECT_CMOTECH 169ejects after C-motech SCSI command 170.Dv 0xff52444556434847 171.It UQ_MSC_EJECT_WAIT 172wait for the device to eject 173.It UQ_MSC_EJECT_SAEL_M460 174ejects after Sael USB commands 175.It UQ_MSC_EJECT_HUAWEISCSI 176ejects after Huawei SCSI command 177.Dv 0x11060000000000000000000000000000 178.It UQ_MSC_EJECT_TCT 179ejects after TCT SCSI command 180.Dv 0x06f504025270 181.It UQ_MSC_DYMO_EJECT 182ejects after HID command 183.Dv 0x1b5a01 184.El 185.Pp 186See 187.Pa /sys/dev/usb/quirk/usb_quirk.h 188or run "usbconfig dump_quirk_names" for the complete list of supported quirks. 189.Sh LOADER TUNABLE 190The following tunable can be set at the 191.Xr loader 8 192prompt before booting the kernel, or stored in 193.Xr loader.conf 5 . 194.Bl -tag -width indent 195.It Va hw.usb.quirk.%d 196The value is a string whose format is: 197.Bd -literal -offset indent 198.Qo VendorId ProductId LowRevision HighRevision UQ_QUIRK,... Qc 199.Ed 200.Pp 201Installs the quirks 202.Ic UQ_QUIRK,... 203for all USB devices matching 204.Ic VendorId 205and 206.Ic ProductId 207which have a hardware revision between and including 208.Ic LowRevision 209and 210.Ic HighRevision . 211.Pp 212.Ic VendorId , 213.Ic ProductId , 214.Ic LowRevision 215and 216.Ic HighRevision 217are all 16 bits numbers which can be decimal or hexadecimal based. 218.Pp 219A maximum of 100 variables 220.Ic hw.usb.quirk.0, .1, ..., .99 221can be defined. 222.Pp 223If a matching entry is found in the kernel's internal quirks table, it 224is replaced by the new definition. 225.Pp 226Else a new entry is created given that the quirk table is not full. 227.Pp 228The kernel iterates over the 229.Ic hw.usb.quirk.N 230variables starting at 231.Ic N = 0 232and stops at 233.Ic N = 99 234or the first non-existing one. 235.El 236.Sh EXAMPLES 237After attaching a 238.Nm u3g 239device which appears as a USB device on 240.Pa ugen0.3 : 241.Bd -literal -offset indent 242usbconfig -d ugen0.3 add_quirk UQ_MSC_EJECT_WAIT 243.Ed 244.Pp 245Enable a Holtec/Keep Out F85 gaming keyboard on 246.Pa ugen1.4 : 247.Bd -literal -offset indent 248usbconfig -d ugen1.4 add_quirk UQ_KBD_BOOTPROTO 249.Ed 250.Pp 251To install a quirk at boot time, place one or several lines like the 252following in 253.Xr loader.conf 5 : 254.Bd -literal -offset indent 255hw.usb.quirk.0="0x04d9 0xfa50 0 0xffff UQ_KBD_IGNORE" 256.Ed 257.Sh SEE ALSO 258.Xr usbconfig 8 259.Sh HISTORY 260The 261.Nm 262module appeared in 263.Fx 8.0 , 264and was written by 265.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . 266This manual page was written by 267.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . 268