1/* $FreeBSD$ */
2
3 FreeBSD Quirk Guidelines
4
5 Nate Lawson - njl at freebsd org
6
70. Introduction
8
9FreeBSD drivers make every attempt possible to support the standards
10behind hardware. Where possible and not in conflict with the standard,
11they also attempt to work around hardware which doesn't strictly
12conform. However, some devices have flaws which can't be worked
13around while keeping the driver compatible with the standard. For
14these devices, we have created a quirks mechanism to indicate to
15the driver that it must avoid certain commands or use them differently
16with a specific model and/or version of hardware. This document
17focuses on identifying and committing quirks for storage hardware
18involving CAM and UMASS but is applicable to other areas.
19
20CAM provides a generic transport for SCSI-like devices. Many different
21transports use SCSI command sets including parallel SCSI, firewire
22(1394), USB UMASS, fibre channel, and ATAPI. For block devices (i.e.
23hard drives, flash adapters, cameras) there are two standards, SBC
24and RBC. SCSI hard drives are usually SBC-compliant and smaller
25devices like flash drives are usually RBC-compliant. Multimedia
26devices including CDROMs and DVD-RW are usually MMC-compliant.
27
28Please follow these guidelines to get your device working as soon
29as possible. If you are a committer, please do NOT commit quirks
30directly but follow this process also.
31
321. Determing the problem
33
34The first step is to determine what's wrong. If the device should
35be supported but hangs while attaching, it's possible a quirk can
36help. The types of things a quirk can fix are:
37`
38 * cam/cam_xpt.c quirks
39
40 o CAM_QUIRK_NOLUNS - do not probe luns other than 0 since device
41 responds to all inquiries with "lun present".
42
43 o CAM_QUIRK_NOSERIAL - do not send an inquiry for serial number.
44
45 o CAM_QUIRK_HILUNS - probe all luns even if some respond "not present"
46 since device has a sparse lun space.
47
48 * cam/scsi/scsi_da.c quirks
49
50 o DA_Q_NO_SYNC_CACHE - The sync cache command is used to force a
51 drive to write out all changes to disk before shutting down. Some
52 drives hang when receiving this command even though it is required
53 by all SBC and RBC standards. Note that a warning message on
54 console is NOT sufficient to add this quirk. The warning messages
55 are harmless and only a device or system hang is cause for adding
56 this quirk.
57
58 o DA_Q_NO_6_BYTE - The RBC spec (see Links below) does not allow
59 for 6-byte READ/WRITE commands. Some manufacturers took that too
60 literally and crash when receiving 6-byte commands. This quirk
61 causes FreeBSD to only send 10-byte commands. Since the CAM subsystem
62 has been modified to not send 6-byte commands to USB, 1394, and
63 other transports that don't support SBC, this quirk should be very
64 rare.
65
66 o DA_Q_NO_PREVENT - Don't use the prevent/allow commands to keep a
67 removable medium from being ejected. Some systems can't handle these
68 commands (rare).
69
70 * cam/scsi/scsi_cd.c quirks
71
72 o CD_Q_NO_TOUCH - not implemented
73
74 o CD_Q_BCD_TRACKS - convert start/end track to BCD
75
76 o CD_Q_NO_CHANGER - never treat as a changer
77
78 o CD_Q_CHANGER - always treat as a changer
79
80 * cam/scsi/scsi_ch.c quirks
81 o CH_Q_NO_DBD - disable block descriptors in mode sense
82
83 * cam/scsi/scsi_sa.c quirks
84
85 o SA_QUIRK_NOCOMP - Can't deal with compression at all
86
87 o SA_QUIRK_FIXED - Force fixed mode
88
89 o SA_QUIRK_VARIABLE - Force variable mode
90
91 o SA_QUIRK_2FM - Needs Two File Marks at EOD
92
93 o SA_QUIRK_1FM - No more than 1 File Mark at EOD
94
95 o SA_QUIRK_NODREAD - Don't try and dummy read density
96
97 o SA_QUIRK_NO_MODESEL - Don't do mode select at all
98
99 o SA_QUIRK_NO_CPAGE - Don't use DEVICE COMPRESSION page
100
101 * dev/usb/umass.c quirks
102
103 o NO_TEST_UNIT_READY - The drive does not support Test Unit Ready.
104 Convert to Start Unit. This command is a simple no-op for most
105 firmware but some of them hang when this command is sent.
106
107 o RS_NO_CLEAR_UA - The drive does not reset the Unit Attention state
108 after REQUEST SENSE has been sent. The INQUIRY command does not
109 reset the UA either, and so CAM runs in circles trying to retrieve
110 the initial INQUIRY data. This quirk signifies that after a unit
111 attention condition, don't try to clear the condition with a request
112 sense command.
113
114 o NO_START_STOP - Like test unit ready, don't send this command if it hangs the device.
115
116 o FORCE_SHORT_INQUIRY - Don't ask for full inquiry data (256
117 bytes). Some drives can only handle the shorter inquiry length
118 (36 bytes).
119
120 o SHUTTLE_INIT - Needs to be initialised the Shuttle way. Haven't
121 looked into what this does but apparently it's mostly Shuttle
122 devices.
123
124 o ALT_IFACE_1 - Drive needs to be switched to alternate interface 1. Rare.
125
126 o FLOPPY_SPEED - Drive does not do 1Mb/s, but just floppy speeds (20kb/s).
127
128 o IGNORE_RESIDUE - The device can't count and gets the residue
129 of transfers wrong. This is sometimes needed for devices where
130 large transfers cause stalls.
131
132 o NO_GETMAXLUN - Get maximum LUN is a command to identify multiple
133 devices sharing the same ID. For instance, a multislot compact
134 flash reader might be on two LUNS. Some non-standard devices hang
135 when receiving this command so this quirk disables it.
136
137 o WRONG_CSWSIG - The device uses a weird CSWSIGNATURE. Rare.
138
139 o NO_INQUIRY - Device cannot handle INQUIRY so fake a generic
140 response. INQUIRY is one of the most basic commands but some
141 drives can't even handle it. (No idea how such devices even work
142 at all on other OS's.) This quirk fakes up a valid but generic
143 response for devices that can't handle INQUIRY.
144
145 o NO_INQUIRY_EVPD - Device cannot handle an extended INQUIRY
146 asking for vital product data (EVPD) so just return a "no data"
147 response (check condition) without sending the command to the
148 device.
149
1502. Testing a Quirk
151
152After you have an idea what you want to try, edit the proper file
153above, using wildcarding to be sure your device is matched. Here
154is a list of the common things to try. Note that some devices require
155multiple quirks or quirks in different drivers. For example, some
156USB pen drives or flash readers require quirks in both da(4) and
157umass(4).
158
159* umass(4) device (sys/dev/usb/umass.c) -- this quirk matches an Asahi Optical device with any product ID or revision ID.
160*
161* { USB_VENDOR_ASAHIOPTICAL, PID_WILDCARD, RID_WILDCARD,
162* UMASS_PROTO_ATAPI | UMASS_PROTO_CBI_I,
163* RS_NO_CLEAR_UA
164* },
165* da(4) device (sys/cam/scsi/scsi_da.c) -- this quirk matches a Creative device with a name of "NOMAD_MUVO" and any revision.
166*
167* {
168* /*
169* * Creative Nomad MUVO mp3 player (USB)
170* * PR: kern/53094
171* */
172* {T_DIRECT, SIP_MEDIA_REMOVABLE, "CREATIVE", "NOMAD_MUVO", "*"},
173* /*quirks*/ DA_Q_NO_SYNC_CACHE|DA_Q_NO_PREVENT
174* },
175
1763. Filing a PR
177
178All quirk submissions MUST go through GNATS. For information on how
179to submit a PR, see this page.
180
181Please include the following in your PR:
182
183 * Subject: QUIRK: FooCo USB DVD-RAM drive
184 * Output of "camcontrol inquiry yourdevice"
185 * Manufacturer name, model number, etc.
186 * Transport type (FC, SCSI, USB, Firewire)
187 * Output from dmesg for failed attach attempts
188 * Output from dmesg for successful attach attempts (after quirk added)
189 * Output of "usbdevs -v" with device attached
190 * Valid email address
191
192Here are some examples of well-formed PRs:
193
194 * kern/43580
195 * kern/49054
196
1974. What happens next
198
199I will review your submission, respond with comments, and once the
200quirk is deemed necessary and ready for committing, I'll commit it,
201referencing the PR. (Again, all quirks must be submitted as PRs).
202Questions? Email njl AT freebsd.org.
203
2045. Note to Committers
205
206Please insert quirks in the right section in scsi_da.c, sorted by
207PR number. Always include the name and PR number for scsi_da.c (see
208above for an example.) Please sort quirks alphabetically in umass.c.
209Follow the surrounding style in all drivers. Be sure to correspond
210with the submitter to be sure the quirk you are adding is the minimum
211necessary, not quirking other useful features and not overly broad
212(i.e., too many wildcards).
213