share/man/man4/usb_quirk.4

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