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 April 4, 2016 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_BAD_ADC 56bad audio spec version number 57.It UQ_BAD_AUDIO 58device claims audio class, but is not 59.It UQ_BROKEN_BIDIR 60printer has broken bidir mode 61.It UQ_BUS_POWERED 62device is bus powered, despite claim 63.It UQ_HID_IGNORE 64device should be ignored by hid class 65.It UQ_KBD_IGNORE 66device should be ignored by kbd class 67.It UQ_KBD_BOOTPROTO 68device should set the boot protocol 69.It UQ_UMS_IGNORE 70device should be ignored by ums class 71.It UQ_MS_BAD_CLASS 72does not identify properly 73.It UQ_MS_LEADING_BYTE 74mouse sends an unknown leading byte 75.It UQ_MS_REVZ 76mouse has Z-axis reversed 77.It UQ_NO_STRINGS 78string descriptors are broken 79.It UQ_POWER_CLAIM 80hub lies about power status 81.It UQ_SPUR_BUT_UP 82spurious mouse button up events 83.It UQ_SWAP_UNICODE 84has some Unicode strings swapped 85.It UQ_CFG_INDEX_1 86select configuration index 1 by default 87.It UQ_CFG_INDEX_2 88select configuration index 2 by default 89.It UQ_CFG_INDEX_3 90select configuration index 3 by default 91.It UQ_CFG_INDEX_4 92select configuration index 4 by default 93.It UQ_CFG_INDEX_0 94select configuration index 0 by default 95.It UQ_ASSUME_CM_OVER_DATA 96assume cm over data feature 97.El 98.Sh USB Mass Storage quirks: 99.Bl -tag -width Ds 100.It UQ_MSC_NO_TEST_UNIT_READY 101send start/stop instead of TUR 102.It UQ_MSC_NO_RS_CLEAR_UA 103does not reset Unit Att. 104.It UQ_MSC_NO_START_STOP 105does not support start/stop 106.It UQ_MSC_NO_GETMAXLUN 107does not support get max LUN 108.It UQ_MSC_NO_INQUIRY 109fake generic inq response 110.It UQ_MSC_NO_INQUIRY_EVPD 111does not support inq EVPD 112.It UQ_MSC_NO_SYNC_CACHE 113does not support sync cache 114.It UQ_MSC_SHUTTLE_INIT 115requires Shuttle init sequence 116.It UQ_MSC_ALT_IFACE_1 117switch to alternate interface 1 118.It UQ_MSC_FLOPPY_SPEED 119does floppy speeds (20kb/s) 120.It UQ_MSC_IGNORE_RESIDUE 121gets residue wrong 122.It UQ_MSC_WRONG_CSWSIG 123uses wrong CSW signature 124.It UQ_MSC_RBC_PAD_TO_12 125pad RBC requests to 12 bytes 126.It UQ_MSC_READ_CAP_OFFBY1 127reports sector count, not max sec. 128.It UQ_MSC_FORCE_SHORT_INQ 129does not support full inq. 130.It UQ_MSC_FORCE_WIRE_BBB 131force BBB wire protocol 132.It UQ_MSC_FORCE_WIRE_CBI 133force CBI wire protocol 134.It UQ_MSC_FORCE_WIRE_CBI_I 135force CBI with int. wire protocol 136.It UQ_MSC_FORCE_PROTO_SCSI 137force SCSI command protocol 138.It UQ_MSC_FORCE_PROTO_ATAPI 139force ATAPI command protocol 140.It UQ_MSC_FORCE_PROTO_UFI 141force UFI command protocol 142.It UQ_MSC_FORCE_PROTO_RBC 143force RBC command protocol 144.El 145.Sh 3G Datacard (u3g) quirks: 146.Bl -tag -width Ds 147.It UQ_MSC_EJECT_HUAWEI 148ejects after Huawei USB command 149.It UQ_MSC_EJECT_SIERRA 150ejects after Sierra USB command 151.It UQ_MSC_EJECT_SCSIEJECT 152ejects after SCSI eject command 153.Dv 0x1b0000000200 154.It UQ_MSC_EJECT_REZERO 155ejects after SCSI rezero command 156.Dv 0x010000000000 157.It UQ_MSC_EJECT_ZTESTOR 158ejects after ZTE SCSI command 159.Dv 0x850101011801010101010000 160.It UQ_MSC_EJECT_CMOTECH 161ejects after C-motech SCSI command 162.Dv 0xff52444556434847 163.It UQ_MSC_EJECT_WAIT 164wait for the device to eject 165.It UQ_MSC_EJECT_SAEL_M460 166ejects after Sael USB commands 167.It UQ_MSC_EJECT_HUAWEISCSI 168ejects after Huawei SCSI command 169.Dv 0x11060000000000000000000000000000 170.It UQ_MSC_EJECT_TCT 171ejects after TCT SCSI command 172.Dv 0x06f504025270 173.It UQ_MSC_DYMO_EJECT 174ejects after HID command 175.Dv 0x1b5a01 176.El 177.Pp 178See 179.Pa /sys/dev/usb/quirk/usb_quirk.h 180or run "usbconfig dump_quirk_names" for the complete list of supported quirks. 181.Sh LOADER TUNABLE 182The following tunable can be set at the 183.Xr loader 8 184prompt before booting the kernel, or stored in 185.Xr loader.conf 5 . 186.Bl -tag -width indent 187.It Va hw.usb.quirk.%d 188The value is a string whose format is: 189.Bd -literal -offset indent 190.Qo VendorId ProductId LowRevision HighRevision UQ_QUIRK,... Qc 191.Ed 192.Pp 193Installs the quirks 194.Ic UQ_QUIRK,... 195for all USB devices matching 196.Ic VendorId 197and 198.Ic ProductId 199which have a hardware revision between and including 200.Ic LowRevision 201and 202.Ic HighRevision . 203.Pp 204.Ic VendorId , 205.Ic ProductId , 206.Ic LowRevision 207and 208.Ic HighRevision 209are all 16 bits numbers which can be decimal or hexadecimal based. 210.Pp 211A maximum of 100 variables 212.Ic hw.usb.quirk.0, .1, ..., .99 213can be defined. 214.Pp 215If a matching entry is found in the kernel's internal quirks table, it 216is replaced by the new definition. 217.Pp 218Else a new entry is created given that the quirk table is not full. 219.Pp 220The kernel iterates over the 221.Ic hw.usb.quirk.N 222variables starting at 223.Ic N = 0 224and stops at 225.Ic N = 99 226or the first non-existing one. 227.El 228.Sh EXAMPLES 229After attaching a 230.Nm u3g 231device which appears as a USB device on 232.Pa ugen0.3 : 233.Bd -literal -offset indent 234usbconfig -d ugen0.3 add_quirk UQ_MSC_EJECT_WAIT 235.Ed 236.Pp 237Enable a Holtec/Keep Out F85 gaming keyboard on 238.Pa ugen1.4 : 239.Bd -literal -offset indent 240usbconfig -d ugen1.4 add_quirk UQ_KBD_BOOTPROTO 241.Ed 242.Pp 243To install a quirk at boot time, place one or several lines like the 244following in 245.Xr loader.conf 5 : 246.Bd -literal -offset indent 247hw.usb.quirk.0="0x04d9 0xfa50 0 0xffff UQ_KBD_IGNORE" 248.Ed 249.Sh SEE ALSO 250.Xr usbconfig 8 251.Sh HISTORY 252The 253.Nm 254module appeared in 255.Fx 8.0 , 256and was written by 257.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . 258This manual page was written by 259.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . 260