Merge git://git.kernel.org/pub/scm/linux/kernel/git/steve/gfs2-2.6-nmw

[safe/jmp/linux-2.6] / Documentation / scsi / scsi_mid_low_api.txt

diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt
index 3209b37..de67229 100644 (file)
--- a/Documentation/scsi/scsi_mid_low_api.txt
+++ b/Documentation/scsi/scsi_mid_low_api.txt
@@ -150,7 +150,8 @@ scsi devices of which only the first 2 respond:
 LLD                   mid level                    LLD
 ===-------------------=========--------------------===------
 scsi_host_alloc()  -->
 LLD                   mid level                    LLD
 ===-------------------=========--------------------===------
 scsi_host_alloc()  -->

-scsi_add_host()  --------+
+scsi_add_host()  ---->
+scsi_scan_host()  -------+

                          |
                     slave_alloc()
                     slave_configure() -->  scsi_adjust_queue_depth()
                          |
                     slave_alloc()
                     slave_configure() -->  scsi_adjust_queue_depth()


@@ -196,7 +197,7 @@ of the issues involved. See the section on reference counting below.
 
 
 The hotplug concept may be extended to SCSI devices. Currently, when an
 
 
 The hotplug concept may be extended to SCSI devices. Currently, when an

-HBA is added, the scsi_add_host() function causes a scan for SCSI devices
+HBA is added, the scsi_scan_host() function causes a scan for SCSI devices

 attached to the HBA's SCSI transport. On newer SCSI transports the HBA
 may become aware of a new SCSI device _after_ the scan has completed.
 An LLD can use this sequence to make the mid level aware of a SCSI device:
 attached to the HBA's SCSI transport. On newer SCSI transports the HBA
 may become aware of a new SCSI device _after_ the scan has completed.
 An LLD can use this sequence to make the mid level aware of a SCSI device:


@@ -372,9 +373,8 @@ names all start with "scsi_".
 Summary:
    scsi_activate_tcq - turn on tag command queueing
    scsi_add_device - creates new scsi device (lu) instance
 Summary:
    scsi_activate_tcq - turn on tag command queueing
    scsi_add_device - creates new scsi device (lu) instance

-   scsi_add_host - perform sysfs registration and SCSI bus scan.
+   scsi_add_host - perform sysfs registration and set up transport class

    scsi_adjust_queue_depth - change the queue depth on a SCSI device
    scsi_adjust_queue_depth - change the queue depth on a SCSI device

-   scsi_assign_lock - replace default host_lock with given lock

    scsi_bios_ptable - return copy of block device's partition table
    scsi_block_requests - prevent further commands being queued to given host
    scsi_deactivate_tcq - turn off tag command queueing
    scsi_bios_ptable - return copy of block device's partition table
    scsi_block_requests - prevent further commands being queued to given host
    scsi_deactivate_tcq - turn off tag command queueing


@@ -386,6 +386,7 @@ Summary:
    scsi_remove_device - detach and remove a SCSI device
    scsi_remove_host - detach and remove all SCSI devices owned by host
    scsi_report_bus_reset - report scsi _bus_ reset observed
    scsi_remove_device - detach and remove a SCSI device
    scsi_remove_host - detach and remove all SCSI devices owned by host
    scsi_report_bus_reset - report scsi _bus_ reset observed

+   scsi_scan_host - scan SCSI bus

    scsi_track_queue_full - track successive QUEUE_FULL events 
    scsi_unblock_requests - allow further commands to be queued to given host
    scsi_unregister - [calls scsi_host_put()]
    scsi_track_queue_full - track successive QUEUE_FULL events 
    scsi_unblock_requests - allow further commands to be queued to given host
    scsi_unregister - [calls scsi_host_put()]


@@ -425,10 +426,10 @@ void scsi_activate_tcq(struct scsi_device *sdev, int depth)
  *      Might block: yes
  *
  *      Notes: This call is usually performed internally during a scsi
  *      Might block: yes
  *
  *      Notes: This call is usually performed internally during a scsi

- *      bus scan when an HBA is added (i.e. scsi_add_host()). So it
+ *      bus scan when an HBA is added (i.e. scsi_scan_host()). So it

  *      should only be called if the HBA becomes aware of a new scsi
  *      should only be called if the HBA becomes aware of a new scsi

- *      device (lu) after scsi_add_host() has completed. If successful
- *      this call we lead to slave_alloc() and slave_configure() callbacks
+ *      device (lu) after scsi_scan_host() has completed. If successful
+ *      this call can lead to slave_alloc() and slave_configure() callbacks

  *      into the LLD.
  *
  *      Defined in: drivers/scsi/scsi_scan.c
  *      into the LLD.
  *
  *      Defined in: drivers/scsi/scsi_scan.c


@@ -439,7 +440,7 @@ struct scsi_device * scsi_add_device(struct Scsi_Host *shost,
 
 
 /**
 
 
 /**

- * scsi_add_host - perform sysfs registration and SCSI bus scan.
+ * scsi_add_host - perform sysfs registration and set up transport class

  * @shost:   pointer to scsi host instance
  * @dev:     pointer to struct device of type scsi class
  *
  * @shost:   pointer to scsi host instance
  * @dev:     pointer to struct device of type scsi class
  *


@@ -448,7 +449,11 @@ struct scsi_device * scsi_add_device(struct Scsi_Host *shost,
  *      Might block: no
  *
  *      Notes: Only required in "hotplug initialization model" after a
  *      Might block: no
  *
  *      Notes: Only required in "hotplug initialization model" after a

- *      successful call to scsi_host_alloc().
+ *      successful call to scsi_host_alloc().  This function does not
+ *     scan the bus; this can be done by calling scsi_scan_host() or
+ *     in some other transport-specific way.  The LLD must set up
+ *     the transport template before calling this function and may only
+ *     access the transport class data after this function has been called.

  *
  *      Defined in: drivers/scsi/hosts.c
  **/
  *
  *      Defined in: drivers/scsi/hosts.c
  **/


@@ -483,20 +488,6 @@ void scsi_adjust_queue_depth(struct scsi_device * sdev, int tagged,
 
 
 /**
 
 
 /**

- * scsi_assign_lock - replace default host_lock with given lock
- * @shost: a pointer to a scsi host instance
- * @lock: pointer to lock to replace host_lock for this host
- *
- *      Returns nothing
- *
- *      Might block: no
- *
- *      Defined in: include/scsi/scsi_host.h .
- **/
-void scsi_assign_lock(struct Scsi_Host *shost, spinlock_t *lock)
-
-
-/**

  * scsi_bios_ptable - return copy of block device's partition table
  * @dev:        pointer to block device
  *
  * scsi_bios_ptable - return copy of block device's partition table
  * @dev:        pointer to block device
  *


@@ -559,7 +550,7 @@ void scsi_deactivate_tcq(struct scsi_device *sdev, int depth)
  *      area for the LLD's exclusive use.
  *      Both associated refcounting objects have their refcount set to 1.
  *      Full registration (in sysfs) and a bus scan are performed later when
  *      area for the LLD's exclusive use.
  *      Both associated refcounting objects have their refcount set to 1.
  *      Full registration (in sysfs) and a bus scan are performed later when

- *      scsi_add_host() is called.
+ *      scsi_add_host() and scsi_scan_host() are called.

  *
  *      Defined in: drivers/scsi/hosts.c .
  **/
  *
  *      Defined in: drivers/scsi/hosts.c .
  **/


@@ -699,6 +690,19 @@ void scsi_report_bus_reset(struct Scsi_Host * shost, int channel)
 
 
 /**
 
 
 /**

+ * scsi_scan_host - scan SCSI bus
+ * @shost: a pointer to a scsi host instance
+ *
+ *     Might block: yes
+ *
+ *     Notes: Should be called after scsi_add_host()
+ *
+ *     Defined in: drivers/scsi/scsi_scan.c
+ **/
+void scsi_scan_host(struct Scsi_Host *shost)
+
+
+/**

  * scsi_track_queue_full - track successive QUEUE_FULL events on given
  *                      device to determine if and when there is a need
  *                      to adjust the queue depth on the device.
  * scsi_track_queue_full - track successive QUEUE_FULL events on given
  *                      device to determine if and when there is a need
  *                      to adjust the queue depth on the device.


@@ -785,7 +789,6 @@ Summary:
    eh_bus_reset_handler - issue SCSI bus reset
    eh_device_reset_handler - issue SCSI device reset
    eh_host_reset_handler - reset host (host bus adapter)
    eh_bus_reset_handler - issue SCSI bus reset
    eh_device_reset_handler - issue SCSI device reset
    eh_host_reset_handler - reset host (host bus adapter)

-   eh_strategy_handler - driver supplied alternate to scsi_unjam_host()

    info - supply information about given host
    ioctl - driver can respond to ioctls
    proc_info - supports /proc/scsi/{driver_name}/{host_no}
    info - supply information about given host
    ioctl - driver can respond to ioctls
    proc_info - supports /proc/scsi/{driver_name}/{host_no}


@@ -951,24 +954,6 @@ Details:
 
 
 /**
 
 
 /**

- *      eh_strategy_handler - driver supplied alternate to scsi_unjam_host()
- *      @shp: host on which error has occurred
- *
- *      Returns TRUE if host unjammed, else FALSE.
- *
- *      Locks: none
- *
- *      Calling context: kernel thread
- *
- *      Notes: Invoked from scsi_eh thread. LLD supplied alternate to 
- *      scsi_unjam_host() found in scsi_error.c
- *
- *      Optionally defined in: LLD
- **/
-     int eh_strategy_handler(struct Scsi_Host * shp)
-
-
-/**

  *      info - supply information about given host: driver name plus data
  *             to distinguish given host
  *      @shp: host to supply information about
  *      info - supply information about given host: driver name plus data
  *             to distinguish given host
  *      @shp: host to supply information about


@@ -1286,6 +1271,11 @@ of interest:
     hostdata[0]  - area reserved for LLD at end of struct Scsi_Host. Size
                    is set by the second argument (named 'xtr_bytes') to
                    scsi_host_alloc() or scsi_register().
     hostdata[0]  - area reserved for LLD at end of struct Scsi_Host. Size
                    is set by the second argument (named 'xtr_bytes') to
                    scsi_host_alloc() or scsi_register().

+    vendor_id    - a unique value that identifies the vendor supplying
+                   the LLD for the Scsi_Host.  Used most often in validating
+                   vendor-specific message requests.  Value consists of an
+                   identifier type and a vendor-specific value.
+                   See scsi_netlink.h for a description of valid formats.

 
 The scsi_host structure is defined in include/scsi/scsi_host.h
 
 
 The scsi_host structure is defined in include/scsi/scsi_host.h
 


@@ -1366,17 +1356,11 @@ Locks
 Each struct Scsi_Host instance has a spin_lock called struct 
 Scsi_Host::default_lock which is initialized in scsi_host_alloc() [found in 
 hosts.c]. Within the same function the struct Scsi_Host::host_lock pointer
 Each struct Scsi_Host instance has a spin_lock called struct 
 Scsi_Host::default_lock which is initialized in scsi_host_alloc() [found in 
 hosts.c]. Within the same function the struct Scsi_Host::host_lock pointer

-is initialized to point at default_lock with the scsi_assign_lock() function.
-Thereafter lock and unlock operations performed by the mid level use the
-struct Scsi_Host::host_lock pointer.
-
-LLDs can override the use of struct Scsi_Host::default_lock by
-using scsi_assign_lock(). The earliest opportunity to do this would
-be in the detect() function after it has invoked scsi_register(). It
-could be replaced by a coarser grain lock (e.g. per driver) or a
-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().
+is initialized to point at default_lock.  Thereafter lock and unlock
+operations performed by the mid level use the struct Scsi_Host::host_lock
+pointer.  Previously drivers could override the host_lock pointer but
+this is not allowed anymore.
+

 
 Autosense
 =========
 
 Autosense
 =========


@@ -1428,7 +1412,7 @@ Credits
 =======
 The following people have contributed to this document:
         Mike Anderson <andmike at us dot ibm dot com>
 =======
 The following people have contributed to this document:
         Mike Anderson <andmike at us dot ibm dot com>

-        James Bottomley <James dot Bottomley at steeleye dot com> 
+        James Bottomley <James dot Bottomley at hansenpartnership dot com>

         Patrick Mansfield <patmans at us dot ibm dot com> 
         Christoph Hellwig <hch at infradead dot org>
         Doug Ledford <dledford at redhat dot com>
         Patrick Mansfield <patmans at us dot ibm dot com> 
         Christoph Hellwig <hch at infradead dot org>
         Doug Ledford <dledford at redhat dot com>