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_MS_VENDOR_BTN 82mouse has buttons in vendor usage page 83.It UQ_NO_STRINGS 84string descriptors are broken 85.It UQ_POWER_CLAIM 86hub lies about power status 87.It UQ_SPUR_BUT_UP 88spurious mouse button up events 89.It UQ_SWAP_UNICODE 90has some Unicode strings swapped 91.It UQ_CFG_INDEX_1 92select configuration index 1 by default 93.It UQ_CFG_INDEX_2 94select configuration index 2 by default 95.It UQ_CFG_INDEX_3 96select configuration index 3 by default 97.It UQ_CFG_INDEX_4 98select configuration index 4 by default 99.It UQ_CFG_INDEX_0 100select configuration index 0 by default 101.It UQ_ASSUME_CM_OVER_DATA 102assume cm over data feature 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