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