freebsd-nq/sys/cam
Kenneth D. Merry 1cc052e80f Add descriptor sense support to CAM, and honor sense residuals properly in
CAM.

Desriptor sense is a new sense data format that originated in SPC-3.  Among
other things, it allows for an 8-byte info field, which is necessary to
pass back block numbers larger than 4 bytes.

This change adds a number of new functions to scsi_all.c (and therefore
libcam) that abstract out most access to sense data.

This includes a bump of CAM_VERSION, because the CCB ABI has changed.
Userland programs that use the CAM pass(4) driver will need to be
recompiled.

camcontrol.c:	Change uses of scsi_extract_sense() to use
		scsi_extract_sense_len().

		Use scsi_get_sks() instead of accessing sense key specific
		data directly.

scsi_modes:	Update the control mode page to the latest version (SPC-4).

scsi_cmds.c,
scsi_target.c:	Change references to struct scsi_sense_data to struct
		scsi_sense_data_fixed.  This should be changed to allow the
		user to specify fixed or descriptor sense, and then use
		scsi_set_sense_data() to build the sense data.

ps3cdrom.c:	Use scsi_set_sense_data() instead of setting sense data
		manually.

cam_periph.c:	Use scsi_extract_sense_len() instead of using
		scsi_extract_sense() or accessing sense data directly.

cam_ccb.h:	Bump the CAM_VERSION from 0x15 to 0x16.  The change of
		struct scsi_sense_data from 32 to 252 bytes changes the
		size of struct ccb_scsiio, but not the size of union ccb.
		So the version must be bumped to prevent structure
		mis-matches.

scsi_all.h:	Lots of updated SCSI sense data and other structures.

		Add function prototypes for the new sense data functions.

		Take out the inline implementation of scsi_extract_sense().
		It is now too large to put in a header file.

		Add macros to calculate whether fields are present and
		filled in fixed and descriptor sense data

scsi_all.c:	In scsi_op_desc(), allow the user to pass in NULL inquiry
		data, and we'll assume a direct access device in that case.

		Changed the SCSI RESERVED sense key name and description
		to COMPLETED, as it is now defined in the spec.

		Change the error recovery action for a number of read errors
		to prevent lots of retries when the drive has said that the
		block isn't accessible.  This speeds up reconstruction of
		the block by any RAID software running on top of the drive
		(e.g. ZFS).

		In scsi_sense_desc(), allow for invalid sense key numbers.
		This allows calling this routine without checking the input
		values first.

		Change scsi_error_action() to use scsi_extract_sense_len(),
		and handle things when invalid asc/ascq values are
		encountered.

		Add a new routine, scsi_desc_iterate(), that will call the
		supplied function for every descriptor in descriptor format
		sense data.

		Add scsi_set_sense_data(), and scsi_set_sense_data_va(),
		which build descriptor and fixed format sense data.  They
		currently default to fixed format sense data.

		Add a number of scsi_get_*() functions, which get different
		types of sense data fields from either fixed or descriptor
		format sense data, if the data is present.

		Add a number of scsi_*_sbuf() functions, which print
		formatted versions of various sense data fields.  These
		functions work for either fixed or descriptor sense.

		Add a number of scsi_sense_*_sbuf() functions, which have a
		standard calling interface and print the indicated field.
		These functions take descriptors only.

		Add scsi_sense_desc_sbuf(), which will print a formatted
		version of the given sense descriptor.

		Pull out a majority of the scsi_sense_sbuf() function and
		put it into scsi_sense_only_sbuf().  This allows callers
		that don't use struct ccb_scsiio to easily utilize the
		printing routines.  Revamp that function to handle
		descriptor sense and use the new sense fetching and
		printing routines.

		Move scsi_extract_sense() into scsi_all.c, and implement it
		in terms of the new function, scsi_extract_sense_len().
		The _len() version takes a length (which should be the
		sense length - residual) and can indicate which fields are
		present and valid in the sense data.

		Add a couple of new scsi_get_*() routines to get the sense
		key, asc, and ascq only.

mly.c:		Rename struct scsi_sense_data to struct
		scsi_sense_data_fixed.

sbp_targ.c:	Use the new sense fetching routines to get sense data
		instead of accessing it directly.

sbp.c:		Change the firewire/SCSI sense data transformation code to
		use struct scsi_sense_data_fixed instead of struct
		scsi_sense_data.  This should be changed later to use
		scsi_set_sense_data().

ciss.c:		Calculate the sense residual properly.  Use
		scsi_get_sense_key() to fetch the sense key.

mps_sas.c,
mpt_cam.c:	Set the sense residual properly.

iir.c:		Use scsi_set_sense_data() instead of building sense data by
		hand.

iscsi_subr.c:	Use scsi_extract_sense_len() instead of grabbing sense data
		directly.

umass.c:	Use scsi_set_sense_data() to build sense data.

		Grab the sense key using scsi_get_sense_key().

		Calculate the sense residual properly.

isp_freebsd.h:	Use scsi_get_*() routines to grab asc, ascq, and sense key
		values.

		Calculate and set the sense residual.

MFC after:	3 days
Sponsored by:	Spectra Logic Corporation
2011-10-03 20:32:55 +00:00
..
ata Higher-priority initialization request can eat request scheduling done from 2011-07-30 21:42:53 +00:00
scsi Add descriptor sense support to CAM, and honor sense residuals properly in 2011-10-03 20:32:55 +00:00
cam_ccb.h Add descriptor sense support to CAM, and honor sense residuals properly in 2011-10-03 20:32:55 +00:00
cam_debug.h Implement the usage of Report Luns as part of SCSI probing for SCP3 or 2010-06-08 16:17:25 +00:00
cam_periph.c Add descriptor sense support to CAM, and honor sense residuals properly in 2011-10-03 20:32:55 +00:00
cam_periph.h Lay groundwork in CAM for recording and reporting physical path and 2011-06-14 14:53:17 +00:00
cam_queue.c MFp4: 2009-11-14 20:30:42 +00:00
cam_queue.h MFp4: Large set of CAM inprovements. 2010-01-28 08:41:30 +00:00
cam_sim.c MFp4: Large set of CAM inprovements. 2010-01-28 08:41:30 +00:00
cam_sim.h Fix a comment to reflect what really happens. 2008-12-22 16:58:47 +00:00
cam_xpt_internal.h Lay groundwork in CAM for recording and reporting physical path and 2011-06-14 14:53:17 +00:00
cam_xpt_periph.h MFp4: Large set of CAM inprovements. 2010-01-28 08:41:30 +00:00
cam_xpt_sim.h MFp4: Large set of CAM inprovements. 2010-01-28 08:41:30 +00:00
cam_xpt.c Fixes for sure bus reference miscounting and potential device and 2011-08-12 20:09:38 +00:00
cam_xpt.h Fixes for sure bus reference miscounting and potential device and 2011-08-12 20:09:38 +00:00
cam.c Add some FEATURE macros for various features (AUDIT/CAM/IPC/KTR/MAC/NFS/NTP/ 2011-02-25 10:11:01 +00:00
cam.h Add Serial Management Protocol (SMP) passthrough support to CAM. 2010-11-30 22:39:46 +00:00
README.quirks

/* $FreeBSD$ */

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