sys/cam/README.quirks

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