[PATCH] lk 2.5.31 scsi interface documentation

Linus,
Below is a patch to a file that documents the interface
between the scsi mid level and lower level (HBA) drivers.

The main change is documenting "autosense". bios_param()'s
interface has changed.

Doug Gilbert

drivers/scsi/scsi_mid_low_api.txt

@@ -34,12 +34,15 @@ scsi_module.c is normally included at the end of a lower
 level driver. For it to work a declaration like this is needed before
 it is included:
     static Scsi_Host_Template driver_template = DRIVER_TEMPLATE;
-    /* DRIVER_TEMPLATE should contain pointers to supported interface
-       functions. Scsi_Host_Template is defined in hosts.h */
     #include "scsi_module.c"
 
+In this case "DRIVER_TEMPLATE" is defined to be a structure initializer
+that is placed in the driver header file by convention. It contains
+pointers to supported interface functions and other values.
+Scsi_Host_Template is defined in hosts.h . 
+
 The scsi_module.c assumes the name "driver_template" is appropriately
-defined. It contains 2 functions:
+defined. scsi_module.c contains 2 functions:
   1) init_this_scsi_driver() called during builtin and module driver
      initialization: invokes mid level's scsi_register_host()
   2) exit_this_scsi_driver() called during closedown: invokes
@@ -68,7 +71,7 @@ The interface functions are listed below in alphabetical order.
 /**
  *      bios_param - fetch head, sector, cylinder info for a disk
  *      @sdkp: pointer to disk structure (defined in sd.h)
- *      @dev: corresponds to dev_t of device file name (e.g. /dev/sdb)
+ *      @bdev: pointer to block device context (defined in fs.h)
  *      @params: three element array to place output:
  *              params[0] number of heads
  *              params[1] number of sectors
@@ -267,6 +270,8 @@ The interface functions are listed below in alphabetical order.
  *      unsupported ioctl() 'cmd' numbers should return -ENOTTY.
  *      However the mid level returns -EINVAL for unrecognized 'cmd'
  *      numbers when this function is not supplied by the driver.
+ *      Unfortunately some applications expect -EINVAL and react badly
+ *	when -ENOTTY is returned; stick with -EINVAL.
  **/
     int ioctl(Scsi_Device *sdp, int cmd, void *arg);
 
@@ -304,7 +309,10 @@ int proc_info(char * buffer, char ** start, off_t offset,
  *      @scp: pointer to scsi command object
  *      @done: function pointer to be invoked on completion
  *
- *      Returns 1 if the adapter is busy, else returns 0.
+ *      Returns 1 if the adapter (host) is busy, else returns 0. One
+ *		reason for an adapter to be busy is that the number
+ *		of outstanding queued commands is already equal to
+ *		Scsi_Host::can_queue .
  *
  *      Required: if Scsi_Host::can_queue is ever non-zero
  *                then this function is required.
@@ -324,6 +332,9 @@ int proc_info(char * buffer, char ** start, off_t offset,
  *      return value should be generated by this function. However, in
  *      this case, it should be placed in scp->result before this function 
  *      returns.
+ *      If a status of CHECK CONDITION is placed in "result" when the
+ *	'done' callback is invoked, then the lower level driver should 
+ *	perform autosense and fill in the Scsi_Cmnd::sense_buffer array.
  **/
     int queuecommand(Scsi_Cmnd * scp, void (*done)(Scsi_Cmnd *));
 
@@ -505,6 +516,28 @@ lock of equal granularity (i.e. per host). Using finer grain locks
 (e.g. per scsi device) may be possible by juggling locks in
 queuecommand().
 
+Autosense
+=========
+Autosense (or auto-sense) is defined in the SAM-2 document as "the
+automatic return of sense data to the application client coincident
+with the completion of a SCSI command" when a status of CHECK CONDITION
+occurs. Lower level drivers should perform autosense. This should be
+done when the lower level driver detects a CHECK CONDITION status by either: 
+    a) instructing the SCSI protocol (e.g. SCSI Parallel Interface (SPI))
+       to perform an extra data in phase on such responses
+    b) or, the lower level driver issuing a REQUEST SENSE command itself
+
+Either way, the mid level decides whether the lower level driver has 
+performed autosense by checking Scsi_Cmnd::sense_buffer[0] . If this
+byte has an upper nibble of 7 then autosense is assumed to have taken 
+place. If it has another value (and this byte is initialized to 0 before
+each command) then the mid level will issue a REQUEST SENSE command.
+
+In the presence of queued commands the "nexus" that maintains sense
+buffer data from the command that failed until a following REQUEST SENSE
+may get out of synchronization. This is why it is best for the lower
+level driver to perform autosense.
+
 
 Changes since lk 2.4 series
 ===========================
@@ -514,6 +547,7 @@ per scsi host.
 
 The older error handling mechanism has been removed. This means the
 lower level interface functions abort() and reset() have been removed.
+The Scsi_Host_Template::use_new_eh_code flag has been removed.
 
 In the 2.4 series the scsi subsystem configuration descriptions were 
 aggregated with the configuration descriptions from all other Linux 
@@ -532,4 +566,4 @@ The following people have contributed to this document:
 
 Douglas Gilbert
 dgilbert@interlog.com
-27th April 2002
+13th August 2002