[PATCH] scsi_mid_low_api.txt against 2.5.28

Here are a few changes to this document. Note that the
bios_param callback changed its second argument in lk 2.5.28 .

There is a new section on how a lower level driver passes
back the sense buffer to the mid level (autosense or
a REQUEST SENSE command performed by the lower level driver).

Doug Gilbert

--- linux/drivers/scsi/scsi_mid_low_api.txt     Wed Jul 24 23:57:35 2002
+++ linux/drivers/scsi/scsi_mid_low_api.txt2528add      Thu Jul 25 00:05:52 2002
@@ -34,12 +34,15 @@
 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 @@
 /**
  *      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
@@ -304,7 +307,10 @@
  *      @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 +330,9 @@
  *      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 +514,28 @@
 (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 +545,7 @@
 
 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 +564,4 @@
 
 Douglas Gilbert
 dgilbert@xxxxxxxxxxxx
-27th April 2002
+24th July 2002