initial commit
[freebsd-arm:freebsd-arm.git] / cam / README.quirks
1 /* $FreeBSD$ */
2
3                      FreeBSD Quirk Guidelines
4
5                   Nate Lawson - njl at freebsd org
6
7 0. Introduction
8
9 FreeBSD drivers make every attempt possible to support the standards
10 behind hardware. Where possible and not in conflict with the standard,
11 they also attempt to work around hardware which doesn't strictly
12 conform. However, some devices have flaws which can't be worked
13 around while keeping the driver compatible with the standard. For
14 these devices, we have created a quirks mechanism to indicate to
15 the driver that it must avoid certain commands or use them differently
16 with a specific model and/or version of hardware. This document
17 focuses on identifying and committing quirks for storage hardware
18 involving CAM and UMASS but is applicable to other areas.
19
20 CAM provides a generic transport for SCSI-like devices. Many different
21 transports use SCSI command sets including parallel SCSI, firewire
22 (1394), USB UMASS, fibre channel, and ATAPI. For block devices (i.e.
23 hard drives, flash adapters, cameras) there are two standards, SBC
24 and RBC. SCSI hard drives are usually SBC-compliant and smaller
25 devices like flash drives are usually RBC-compliant. Multimedia
26 devices including CDROMs and DVD-RW are usually MMC-compliant.
27
28 Please follow these guidelines to get your device working as soon
29 as possible. If you are a committer, please do NOT commit quirks
30 directly but follow this process also.
31
32 1. Determing the problem
33
34 The first step is to determine what's wrong. If the device should
35 be supported but hangs while attaching, it's possible a quirk can
36 help. 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
150 2. Testing a Quirk
151
152 After you have an idea what you want to try, edit the proper file
153 above, using wildcarding to be sure your device is matched. Here
154 is a list of the common things to try. Note that some devices require
155 multiple quirks or quirks in different drivers. For example, some
156 USB pen drives or flash readers require quirks in both da(4) and
157 umass(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
176 3. Filing a PR
177
178 All quirk submissions MUST go through GNATS. For information on how
179 to submit a PR, see this page.
180
181 Please 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
192 Here are some examples of well-formed PRs: 
193
194  * kern/43580 
195  * kern/49054 
196
197 4. What happens next
198
199 I will review your submission, respond with comments, and once the
200 quirk is deemed necessary and ready for committing, I'll commit it,
201 referencing the PR. (Again, all quirks must be submitted as PRs).
202 Questions? Email njl AT freebsd.org.
203
204 5. Note to Committers
205
206 Please insert quirks in the right section in scsi_da.c, sorted by
207 PR number. Always include the name and PR number for scsi_da.c (see
208 above for an example.) Please sort quirks alphabetically in umass.c.
209 Follow the surrounding style in all drivers. Be sure to correspond
210 with the submitter to be sure the quirk you are adding is the minimum
211 necessary, not quirking other useful features and not overly broad
212 (i.e., too many wildcards).