The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/cam/README.quirks

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    1 /* $FreeBSD: releng/11.2/sys/cam/README.quirks 170485 2007-06-10 04:31:55Z mjacob $ */
    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).

Cache object: c306ea5766665ee4d2ec6904bd827cb2


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.