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