1170118Smjacob/* $FreeBSD$ */ 2170118Smjacob 3170485Smjacob FreeBSD Quirk Guidelines 4170485Smjacob 5170485Smjacob Nate Lawson - njl at freebsd org 6170485Smjacob 7170485Smjacob0. Introduction 8170485Smjacob 9170485SmjacobFreeBSD drivers make every attempt possible to support the standards 10170485Smjacobbehind hardware. Where possible and not in conflict with the standard, 11170485Smjacobthey also attempt to work around hardware which doesn't strictly 12170485Smjacobconform. However, some devices have flaws which can't be worked 13170485Smjacobaround while keeping the driver compatible with the standard. For 14170485Smjacobthese devices, we have created a quirks mechanism to indicate to 15170485Smjacobthe driver that it must avoid certain commands or use them differently 16170485Smjacobwith a specific model and/or version of hardware. This document 17170485Smjacobfocuses on identifying and committing quirks for storage hardware 18170485Smjacobinvolving CAM and UMASS but is applicable to other areas. 19170485Smjacob 20170485SmjacobCAM provides a generic transport for SCSI-like devices. Many different 21170485Smjacobtransports use SCSI command sets including parallel SCSI, firewire 22170485Smjacob(1394), USB UMASS, fibre channel, and ATAPI. For block devices (i.e. 23170485Smjacobhard drives, flash adapters, cameras) there are two standards, SBC 24170485Smjacoband RBC. SCSI hard drives are usually SBC-compliant and smaller 25170485Smjacobdevices like flash drives are usually RBC-compliant. Multimedia 26170485Smjacobdevices including CDROMs and DVD-RW are usually MMC-compliant. 27170485Smjacob 28170485SmjacobPlease follow these guidelines to get your device working as soon 29170485Smjacobas possible. If you are a committer, please do NOT commit quirks 30170485Smjacobdirectly but follow this process also. 31170485Smjacob 32170485Smjacob1. Determing the problem 33170485Smjacob 34170485SmjacobThe first step is to determine what's wrong. If the device should 35170485Smjacobbe supported but hangs while attaching, it's possible a quirk can 36170485Smjacobhelp. The types of things a quirk can fix are: 37170485Smjacob` 38170485Smjacob * cam/cam_xpt.c quirks 39170485Smjacob 40170485Smjacob o CAM_QUIRK_NOLUNS - do not probe luns other than 0 since device 41170485Smjacob responds to all inquiries with "lun present". 42170485Smjacob 43170485Smjacob o CAM_QUIRK_NOSERIAL - do not send an inquiry for serial number. 44170485Smjacob 45170485Smjacob o CAM_QUIRK_HILUNS - probe all luns even if some respond "not present" 46170485Smjacob since device has a sparse lun space. 47170485Smjacob 48170485Smjacob * cam/scsi/scsi_da.c quirks 49170485Smjacob 50170485Smjacob o DA_Q_NO_SYNC_CACHE - The sync cache command is used to force a 51170485Smjacob drive to write out all changes to disk before shutting down. Some 52170485Smjacob drives hang when receiving this command even though it is required 53170485Smjacob by all SBC and RBC standards. Note that a warning message on 54170485Smjacob console is NOT sufficient to add this quirk. The warning messages 55170485Smjacob are harmless and only a device or system hang is cause for adding 56170485Smjacob this quirk. 57170485Smjacob 58170485Smjacob o DA_Q_NO_6_BYTE - The RBC spec (see Links below) does not allow 59170485Smjacob for 6-byte READ/WRITE commands. Some manufacturers took that too 60170485Smjacob literally and crash when receiving 6-byte commands. This quirk 61170485Smjacob causes FreeBSD to only send 10-byte commands. Since the CAM subsystem 62170485Smjacob has been modified to not send 6-byte commands to USB, 1394, and 63170485Smjacob other transports that don't support SBC, this quirk should be very 64170485Smjacob rare. 65170485Smjacob 66170485Smjacob o DA_Q_NO_PREVENT - Don't use the prevent/allow commands to keep a 67170485Smjacob removable medium from being ejected. Some systems can't handle these 68170485Smjacob commands (rare). 69170485Smjacob 70170485Smjacob * cam/scsi/scsi_cd.c quirks 71170485Smjacob 72170485Smjacob o CD_Q_NO_TOUCH - not implemented 73170485Smjacob 74170485Smjacob o CD_Q_BCD_TRACKS - convert start/end track to BCD 75170485Smjacob 76170485Smjacob o CD_Q_NO_CHANGER - never treat as a changer 77170485Smjacob 78170485Smjacob o CD_Q_CHANGER - always treat as a changer 79170485Smjacob 80170485Smjacob * cam/scsi/scsi_ch.c quirks 81170485Smjacob o CH_Q_NO_DBD - disable block descriptors in mode sense 82170485Smjacob 83170485Smjacob * cam/scsi/scsi_sa.c quirks 84170485Smjacob 85170485Smjacob o SA_QUIRK_NOCOMP - Can't deal with compression at all 86170485Smjacob 87170485Smjacob o SA_QUIRK_FIXED - Force fixed mode 88170485Smjacob 89170485Smjacob o SA_QUIRK_VARIABLE - Force variable mode 90170485Smjacob 91170485Smjacob o SA_QUIRK_2FM - Needs Two File Marks at EOD 92170485Smjacob 93170485Smjacob o SA_QUIRK_1FM - No more than 1 File Mark at EOD 94170485Smjacob 95170485Smjacob o SA_QUIRK_NODREAD - Don't try and dummy read density 96170485Smjacob 97170485Smjacob o SA_QUIRK_NO_MODESEL - Don't do mode select at all 98170485Smjacob 99170485Smjacob o SA_QUIRK_NO_CPAGE - Don't use DEVICE COMPRESSION page 100170485Smjacob 101170485Smjacob * dev/usb/umass.c quirks 102170485Smjacob 103170485Smjacob o NO_TEST_UNIT_READY - The drive does not support Test Unit Ready. 104170485Smjacob Convert to Start Unit. This command is a simple no-op for most 105170485Smjacob firmware but some of them hang when this command is sent. 106170485Smjacob 107170485Smjacob o RS_NO_CLEAR_UA - The drive does not reset the Unit Attention state 108170485Smjacob after REQUEST SENSE has been sent. The INQUIRY command does not 109170485Smjacob reset the UA either, and so CAM runs in circles trying to retrieve 110170485Smjacob the initial INQUIRY data. This quirk signifies that after a unit 111170485Smjacob attention condition, don't try to clear the condition with a request 112170485Smjacob sense command. 113170485Smjacob 114170485Smjacob o NO_START_STOP - Like test unit ready, don't send this command if it hangs the device. 115170485Smjacob 116170485Smjacob o FORCE_SHORT_INQUIRY - Don't ask for full inquiry data (256 117170485Smjacob bytes). Some drives can only handle the shorter inquiry length 118170485Smjacob (36 bytes). 119170485Smjacob 120170485Smjacob o SHUTTLE_INIT - Needs to be initialised the Shuttle way. Haven't 121170485Smjacob looked into what this does but apparently it's mostly Shuttle 122170485Smjacob devices. 123170485Smjacob 124170485Smjacob o ALT_IFACE_1 - Drive needs to be switched to alternate interface 1. Rare. 125170485Smjacob 126170485Smjacob o FLOPPY_SPEED - Drive does not do 1Mb/s, but just floppy speeds (20kb/s). 127170485Smjacob 128170485Smjacob o IGNORE_RESIDUE - The device can't count and gets the residue 129170485Smjacob of transfers wrong. This is sometimes needed for devices where 130170485Smjacob large transfers cause stalls. 131170485Smjacob 132170485Smjacob o NO_GETMAXLUN - Get maximum LUN is a command to identify multiple 133170485Smjacob devices sharing the same ID. For instance, a multislot compact 134170485Smjacob flash reader might be on two LUNS. Some non-standard devices hang 135170485Smjacob when receiving this command so this quirk disables it. 136170485Smjacob 137170485Smjacob o WRONG_CSWSIG - The device uses a weird CSWSIGNATURE. Rare. 138170485Smjacob 139170485Smjacob o NO_INQUIRY - Device cannot handle INQUIRY so fake a generic 140170485Smjacob response. INQUIRY is one of the most basic commands but some 141170485Smjacob drives can't even handle it. (No idea how such devices even work 142170485Smjacob at all on other OS's.) This quirk fakes up a valid but generic 143170485Smjacob response for devices that can't handle INQUIRY. 144170485Smjacob 145170485Smjacob o NO_INQUIRY_EVPD - Device cannot handle an extended INQUIRY 146170485Smjacob asking for vital product data (EVPD) so just return a "no data" 147170485Smjacob response (check condition) without sending the command to the 148170485Smjacob device. 149170485Smjacob 150170485Smjacob2. Testing a Quirk 151170485Smjacob 152170485SmjacobAfter you have an idea what you want to try, edit the proper file 153170485Smjacobabove, using wildcarding to be sure your device is matched. Here 154170485Smjacobis a list of the common things to try. Note that some devices require 155170485Smjacobmultiple quirks or quirks in different drivers. For example, some 156170485SmjacobUSB pen drives or flash readers require quirks in both da(4) and 157170485Smjacobumass(4). 158170485Smjacob 159170485Smjacob* umass(4) device (sys/dev/usb/umass.c) -- this quirk matches an Asahi Optical device with any product ID or revision ID. 160170485Smjacob* 161170485Smjacob* { USB_VENDOR_ASAHIOPTICAL, PID_WILDCARD, RID_WILDCARD, 162170485Smjacob* UMASS_PROTO_ATAPI | UMASS_PROTO_CBI_I, 163170485Smjacob* RS_NO_CLEAR_UA 164170485Smjacob* }, 165170485Smjacob* da(4) device (sys/cam/scsi/scsi_da.c) -- this quirk matches a Creative device with a name of "NOMAD_MUVO" and any revision. 166170485Smjacob* 167170485Smjacob* { 168170485Smjacob* /* 169170485Smjacob* * Creative Nomad MUVO mp3 player (USB) 170170485Smjacob* * PR: kern/53094 171170485Smjacob* */ 172170485Smjacob* {T_DIRECT, SIP_MEDIA_REMOVABLE, "CREATIVE", "NOMAD_MUVO", "*"}, 173170485Smjacob* /*quirks*/ DA_Q_NO_SYNC_CACHE|DA_Q_NO_PREVENT 174170485Smjacob* }, 175170485Smjacob 176170485Smjacob3. Filing a PR 177170485Smjacob 178170485SmjacobAll quirk submissions MUST go through GNATS. For information on how 179170485Smjacobto submit a PR, see this page. 180170485Smjacob 181170485SmjacobPlease include the following in your PR: 182170485Smjacob 183170485Smjacob * Subject: QUIRK: FooCo USB DVD-RAM drive 184170485Smjacob * Output of "camcontrol inquiry yourdevice" 185170485Smjacob * Manufacturer name, model number, etc. 186170485Smjacob * Transport type (FC, SCSI, USB, Firewire) 187170485Smjacob * Output from dmesg for failed attach attempts 188170485Smjacob * Output from dmesg for successful attach attempts (after quirk added) 189170485Smjacob * Output of "usbdevs -v" with device attached 190170485Smjacob * Valid email address 191170485Smjacob 192170485SmjacobHere are some examples of well-formed PRs: 193170485Smjacob 194170485Smjacob * kern/43580 195170485Smjacob * kern/49054 196170485Smjacob 197170485Smjacob4. What happens next 198170485Smjacob 199170485SmjacobI will review your submission, respond with comments, and once the 200170485Smjacobquirk is deemed necessary and ready for committing, I'll commit it, 201170485Smjacobreferencing the PR. (Again, all quirks must be submitted as PRs). 202170485SmjacobQuestions? Email njl AT freebsd.org. 203170485Smjacob 204170485Smjacob5. Note to Committers 205170485Smjacob 206170485SmjacobPlease insert quirks in the right section in scsi_da.c, sorted by 207170485SmjacobPR number. Always include the name and PR number for scsi_da.c (see 208170485Smjacobabove for an example.) Please sort quirks alphabetically in umass.c. 209170485SmjacobFollow the surrounding style in all drivers. Be sure to correspond 210170485Smjacobwith the submitter to be sure the quirk you are adding is the minimum 211170485Smjacobnecessary, not quirking other useful features and not overly broad 212170485Smjacob(i.e., too many wildcards). 213