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