Commit for Nate his "guidelines for submitting quirks".

1 files changed, 210 insertions, 2 deletions

diff --git a/sys/cam/README.quirks b/sys/cam/README.quirks
index 4118e89..707862b 100644
--- a/sys/cam/README.quirks
+++ b/sys/cam/README.quirks
@@ -1,4 +1,212 @@
 /* $FreeBSD$ */
 
-This is a place holder for instructions about how both committers
-and non-committers should submit device quirks.
+                     FreeBSD Quirk Guidelines
+
+                  Nate Lawson - njl at freebsd org
+
+0. Introduction
+
+FreeBSD drivers make every attempt possible to support the standards
+behind hardware. Where possible and not in conflict with the standard,
+they also attempt to work around hardware which doesn't strictly
+conform. However, some devices have flaws which can't be worked
+around while keeping the driver compatible with the standard. For
+these devices, we have created a quirks mechanism to indicate to
+the driver that it must avoid certain commands or use them differently
+with a specific model and/or version of hardware. This document
+focuses on identifying and committing quirks for storage hardware
+involving CAM and UMASS but is applicable to other areas.
+
+CAM provides a generic transport for SCSI-like devices. Many different
+transports use SCSI command sets including parallel SCSI, firewire
+(1394), USB UMASS, fibre channel, and ATAPI. For block devices (i.e.
+hard drives, flash adapters, cameras) there are two standards, SBC
+and RBC. SCSI hard drives are usually SBC-compliant and smaller
+devices like flash drives are usually RBC-compliant. Multimedia
+devices including CDROMs and DVD-RW are usually MMC-compliant.
+
+Please follow these guidelines to get your device working as soon
+as possible. If you are a committer, please do NOT commit quirks
+directly but follow this process also.
+
+1. Determing the problem
+
+The first step is to determine what's wrong. If the device should
+be supported but hangs while attaching, it's possible a quirk can
+help. The types of things a quirk can fix are:
+`
+ * cam/cam_xpt.c quirks 
+
+  o CAM_QUIRK_NOLUNS - do not probe luns other than 0 since device
+  responds to all inquiries with "lun present".
+
+  o CAM_QUIRK_NOSERIAL - do not send an inquiry for serial number. 
+
+  o CAM_QUIRK_HILUNS - probe all luns even if some respond "not present"
+  since device has a sparse lun space. 
+
+ * cam/scsi/scsi_da.c quirks 
+
+  o DA_Q_NO_SYNC_CACHE - The sync cache command is used to force a
+  drive to write out all changes to disk before shutting down. Some
+  drives hang when receiving this command even though it is required
+  by all SBC and RBC standards. Note that a warning message on
+  console is NOT sufficient to add this quirk. The warning messages
+  are harmless and only a device or system hang is cause for adding
+  this quirk.
+
+  o DA_Q_NO_6_BYTE - The RBC spec (see Links below) does not allow
+  for 6-byte READ/WRITE commands. Some manufacturers took that too
+  literally and crash when receiving 6-byte commands. This quirk
+  causes FreeBSD to only send 10-byte commands. Since the CAM subsystem
+  has been modified to not send 6-byte commands to USB, 1394, and
+  other transports that don't support SBC, this quirk should be very
+  rare.
+
+  o DA_Q_NO_PREVENT - Don't use the prevent/allow commands to keep a
+  removable medium from being ejected. Some systems can't handle these
+  commands (rare).
+
+ * cam/scsi/scsi_cd.c quirks 
+
+  o CD_Q_NO_TOUCH - not implemented 
+
+  o CD_Q_BCD_TRACKS - convert start/end track to BCD 
+
+  o CD_Q_NO_CHANGER - never treat as a changer 
+
+  o CD_Q_CHANGER - always treat as a changer 
+
+ * cam/scsi/scsi_ch.c quirks 
+  o CH_Q_NO_DBD - disable block descriptors in mode sense 
+
+ * cam/scsi/scsi_sa.c quirks 
+
+  o SA_QUIRK_NOCOMP - Can't deal with compression at all 
+
+  o SA_QUIRK_FIXED - Force fixed mode 
+
+  o SA_QUIRK_VARIABLE - Force variable mode 
+
+  o SA_QUIRK_2FM - Needs Two File Marks at EOD 
+
+  o SA_QUIRK_1FM - No more than 1 File Mark at EOD 
+
+  o SA_QUIRK_NODREAD - Don't try and dummy read density 
+
+  o SA_QUIRK_NO_MODESEL - Don't do mode select at all 
+
+  o SA_QUIRK_NO_CPAGE - Don't use DEVICE COMPRESSION page 
+
+ * dev/usb/umass.c quirks 
+
+  o NO_TEST_UNIT_READY - The drive does not support Test Unit Ready.
+  Convert to Start Unit. This command is a simple no-op for most
+  firmware but some of them hang when this command is sent.
+
+  o RS_NO_CLEAR_UA - The drive does not reset the Unit Attention state
+  after REQUEST SENSE has been sent. The INQUIRY command does not
+  reset the UA either, and so CAM runs in circles trying to retrieve
+  the initial INQUIRY data. This quirk signifies that after a unit
+  attention condition, don't try to clear the condition with a request
+  sense command.
+
+  o NO_START_STOP - Like test unit ready, don't send this command if it hangs the device. 
+
+  o FORCE_SHORT_INQUIRY - Don't ask for full inquiry data (256
+  bytes). Some drives can only handle the shorter inquiry length
+  (36 bytes).
+
+  o SHUTTLE_INIT - Needs to be initialised the Shuttle way. Haven't
+  looked into what this does but apparently it's mostly Shuttle
+  devices.
+
+  o ALT_IFACE_1 - Drive needs to be switched to alternate interface 1. Rare.
+
+  o FLOPPY_SPEED - Drive does not do 1Mb/s, but just floppy speeds (20kb/s). 
+
+  o IGNORE_RESIDUE - The device can't count and gets the residue
+  of transfers wrong. This is sometimes needed for devices where
+  large transfers cause stalls.
+
+  o NO_GETMAXLUN - Get maximum LUN is a command to identify multiple
+  devices sharing the same ID. For instance, a multislot compact
+  flash reader might be on two LUNS. Some non-standard devices hang
+  when receiving this command so this quirk disables it.
+
+  o WRONG_CSWSIG - The device uses a weird CSWSIGNATURE. Rare. 
+
+  o NO_INQUIRY - Device cannot handle INQUIRY so fake a generic
+  response. INQUIRY is one of the most basic commands but some
+  drives can't even handle it. (No idea how such devices even work
+  at all on other OS's.) This quirk fakes up a valid but generic
+  response for devices that can't handle INQUIRY.
+
+  o NO_INQUIRY_EVPD - Device cannot handle an extended INQUIRY
+  asking for vital product data (EVPD) so just return a "no data"
+  response (check condition) without sending the command to the
+  device.
+
+2. Testing a Quirk
+
+After you have an idea what you want to try, edit the proper file
+above, using wildcarding to be sure your device is matched. Here
+is a list of the common things to try. Note that some devices require
+multiple quirks or quirks in different drivers. For example, some
+USB pen drives or flash readers require quirks in both da(4) and
+umass(4).
+
+* umass(4) device (sys/dev/usb/umass.c) -- this quirk matches an Asahi Optical device with any product ID or revision ID. 
+* 
+*         { USB_VENDOR_ASAHIOPTICAL, PID_WILDCARD, RID_WILDCARD,
+*           UMASS_PROTO_ATAPI | UMASS_PROTO_CBI_I,
+*           RS_NO_CLEAR_UA
+*         },
+* da(4) device (sys/cam/scsi/scsi_da.c) -- this quirk matches a Creative device with a name of "NOMAD_MUVO" and any revision. 
+* 
+*         {
+*                 /*
+*                  * Creative Nomad MUVO mp3 player (USB)
+*                  * PR: kern/53094
+*                  */
+*                 {T_DIRECT, SIP_MEDIA_REMOVABLE, "CREATIVE", "NOMAD_MUVO", "*"},
+*                 /*quirks*/ DA_Q_NO_SYNC_CACHE|DA_Q_NO_PREVENT
+*         },
+
+3. Filing a PR
+
+All quirk submissions MUST go through GNATS. For information on how
+to submit a PR, see this page.
+
+Please include the following in your PR:
+
+ * Subject: QUIRK: FooCo USB DVD-RAM drive 
+ * Output of "camcontrol inquiry yourdevice" 
+ * Manufacturer name, model number, etc. 
+ * Transport type (FC, SCSI, USB, Firewire) 
+ * Output from dmesg for failed attach attempts 
+ * Output from dmesg for successful attach attempts (after quirk added) 
+ * Output of "usbdevs -v" with device attached 
+ * Valid email address 
+
+Here are some examples of well-formed PRs: 
+
+ * kern/43580 
+ * kern/49054 
+
+4. What happens next
+
+I will review your submission, respond with comments, and once the
+quirk is deemed necessary and ready for committing, I'll commit it,
+referencing the PR. (Again, all quirks must be submitted as PRs).
+Questions? Email njl AT freebsd.org.
+
+5. Note to Committers
+
+Please insert quirks in the right section in scsi_da.c, sorted by
+PR number. Always include the name and PR number for scsi_da.c (see
+above for an example.) Please sort quirks alphabetically in umass.c.
+Follow the surrounding style in all drivers. Be sure to correspond
+with the submitter to be sure the quirk you are adding is the minimum
+necessary, not quirking other useful features and not overly broad
+(i.e., too many wildcards).