[Midnightbsd-cvs] src: README.quirks: Add document describing quirks
laffer1 at midnightbsd.org
laffer1 at midnightbsd.org
Mon Sep 15 20:28:14 EDT 2008
Log Message:
-----------
Add document describing quirks
Added Files:
-----------
src/sys/cam:
README.quirks (r1.1)
-------------- next part --------------
--- /dev/null
+++ sys/cam/README.quirks
@@ -0,0 +1,213 @@
+/* $MidnightBSD: src/sys/cam/README.quirks,v 1.1 2008/09/16 00:28:14 laffer1 Exp $ */
+/* $FreeBSD: src/sys/cam/README.quirks,v 1.2 2007/06/10 04:31:55 mjacob Exp $ */
+
+ 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).
More information about the Midnightbsd-cvs
mailing list