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