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