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