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