sys/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).