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 January 17, 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.El 102.Sh USB Mass Storage quirks: 103.Bl -tag -width Ds 104.It UQ_MSC_NO_TEST_UNIT_READY 105send start/stop instead of TUR 106.It UQ_MSC_NO_RS_CLEAR_UA 107does not reset Unit Att. 108.It UQ_MSC_NO_START_STOP 109does not support start/stop 110.It UQ_MSC_NO_GETMAXLUN 111does not support get max LUN 112.It UQ_MSC_NO_INQUIRY 113fake generic inq response 114.It UQ_MSC_NO_INQUIRY_EVPD 115does not support inq EVPD 116.It UQ_MSC_NO_SYNC_CACHE 117does not support sync cache 118.It UQ_MSC_SHUTTLE_INIT 119requires Shuttle init sequence 120.It UQ_MSC_ALT_IFACE_1 121switch to alternate interface 1 122.It UQ_MSC_FLOPPY_SPEED 123does floppy speeds (20kb/s) 124.It UQ_MSC_IGNORE_RESIDUE 125gets residue wrong 126.It UQ_MSC_WRONG_CSWSIG 127uses wrong CSW signature 128.It UQ_MSC_RBC_PAD_TO_12 129pad RBC requests to 12 bytes 130.It UQ_MSC_READ_CAP_OFFBY1 131reports sector count, not max sec. 132.It UQ_MSC_FORCE_SHORT_INQ 133does not support full inq. 134.It UQ_MSC_FORCE_WIRE_BBB 135force BBB wire protocol 136.It UQ_MSC_FORCE_WIRE_CBI 137force CBI wire protocol 138.It UQ_MSC_FORCE_WIRE_CBI_I 139force CBI with int. wire protocol 140.It UQ_MSC_FORCE_PROTO_SCSI 141force SCSI command protocol 142.It UQ_MSC_FORCE_PROTO_ATAPI 143force ATAPI command protocol 144.It UQ_MSC_FORCE_PROTO_UFI 145force UFI command protocol 146.It UQ_MSC_FORCE_PROTO_RBC 147force RBC command protocol 148.El 149.Sh 3G Datacard (u3g) quirks: 150.Bl -tag -width Ds 151.It UQ_MSC_EJECT_HUAWEI 152ejects after Huawei USB command 153.It UQ_MSC_EJECT_SIERRA 154ejects after Sierra USB command 155.It UQ_MSC_EJECT_SCSIEJECT 156ejects after SCSI eject command 157.Dv 0x1b0000000200 158.It UQ_MSC_EJECT_REZERO 159ejects after SCSI rezero command 160.Dv 0x010000000000 161.It UQ_MSC_EJECT_ZTESTOR 162ejects after ZTE SCSI command 163.Dv 0x850101011801010101010000 164.It UQ_MSC_EJECT_CMOTECH 165ejects after C-motech SCSI command 166.Dv 0xff52444556434847 167.It UQ_MSC_EJECT_WAIT 168wait for the device to eject 169.It UQ_MSC_EJECT_SAEL_M460 170ejects after Sael USB commands 171.It UQ_MSC_EJECT_HUAWEISCSI 172ejects after Huawei SCSI command 173.Dv 0x11060000000000000000000000000000 174.It UQ_MSC_EJECT_TCT 175ejects after TCT SCSI command 176.Dv 0x06f504025270 177.It UQ_MSC_DYMO_EJECT 178ejects after HID command 179.Dv 0x1b5a01 180.El 181.Pp 182See 183.Pa /sys/dev/usb/quirk/usb_quirk.h 184or run "usbconfig dump_quirk_names" for the complete list of supported quirks. 185.Sh LOADER TUNABLE 186The following tunable can be set at the 187.Xr loader 8 188prompt before booting the kernel, or stored in 189.Xr loader.conf 5 . 190.Bl -tag -width indent 191.It Va hw.usb.quirk.%d 192The value is a string whose format is: 193.Bd -literal -offset indent 194.Qo VendorId ProductId LowRevision HighRevision UQ_QUIRK,... Qc 195.Ed 196.Pp 197Installs the quirks 198.Ic UQ_QUIRK,... 199for all USB devices matching 200.Ic VendorId 201and 202.Ic ProductId 203which have a hardware revision between and including 204.Ic LowRevision 205and 206.Ic HighRevision . 207.Pp 208.Ic VendorId , 209.Ic ProductId , 210.Ic LowRevision 211and 212.Ic HighRevision 213are all 16 bits numbers which can be decimal or hexadecimal based. 214.Pp 215A maximum of 100 variables 216.Ic hw.usb.quirk.0, .1, ..., .99 217can be defined. 218.Pp 219If a matching entry is found in the kernel's internal quirks table, it 220is replaced by the new definition. 221.Pp 222Else a new entry is created given that the quirk table is not full. 223.Pp 224The kernel iterates over the 225.Ic hw.usb.quirk.N 226variables starting at 227.Ic N = 0 228and stops at 229.Ic N = 99 230or the first non-existing one. 231.El 232.Sh EXAMPLES 233After attaching a 234.Nm u3g 235device which appears as a USB device on 236.Pa ugen0.3 : 237.Bd -literal -offset indent 238usbconfig -d ugen0.3 add_quirk UQ_MSC_EJECT_WAIT 239.Ed 240.Pp 241Enable a Holtec/Keep Out F85 gaming keyboard on 242.Pa ugen1.4 : 243.Bd -literal -offset indent 244usbconfig -d ugen1.4 add_quirk UQ_KBD_BOOTPROTO 245.Ed 246.Pp 247To install a quirk at boot time, place one or several lines like the 248following in 249.Xr loader.conf 5 : 250.Bd -literal -offset indent 251hw.usb.quirk.0="0x04d9 0xfa50 0 0xffff UQ_KBD_IGNORE" 252.Ed 253.Sh SEE ALSO 254.Xr usbconfig 8 255.Sh HISTORY 256The 257.Nm 258module appeared in 259.Fx 8.0 , 260and was written by 261.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . 262This manual page was written by 263.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . 264