[PATCH] scsi_mid_low_api.txt update

[PATCH] scsi_mid_low_api.txt update

[Douglas Gilbert]

[-- Attachment #1: Type: text/plain, Size: 357 bytes --]

After some prompting from Adrian Bunk here is an
update to the scsi mid level to lower level driver
(A)PI document.

Comments welcome.


This patch was sent a month ago but received no comments
and has not made it into the kernel. This patch is
against lk 2.6.9-rc1. The scsi_mid_low_api.txt file has had
a one line change since lk 2.6.8-rc1.

Doug Gilbert

[-- Attachment #2: scsi_mid_low_api.txt269rc1.diff.gz --]
[-- Type: application/x-gzip, Size: 6021 bytes --]

Re: [PATCH] scsi_mid_low_api.txt update

[Christoph Hellwig]

On Wed, Aug 25, 2004 at 01:17:37PM +1000, Douglas Gilbert wrote:
> After some prompting from Adrian Bunk here is an
> update to the scsi mid level to lower level driver
> (A)PI document.
> 
> Comments welcome.

Looks good to me, but is the emial address obsfucation really nesecary?

[PATCH] scsi_mid_low_api.txt update

[Douglas Gilbert]

[-- Attachment #1: Type: text/plain, Size: 118 bytes --]

Changes:
    - initiator device -> initiator port
    - add scsi_activate_tcq() + scsi_deactivate_tcq()

Doug Gilbert

[-- Attachment #2: scsi_mid_low_api269rc2.diff --]
[-- Type: text/x-patch, Size: 4312 bytes --]

--- linux/Documentation/scsi/scsi_mid_low_api.txt	2004-09-14 09:51:04.000000000 +1000
+++ linux/Documentation/scsi/scsi_mid_low_api.txt269rc2add	2004-09-21 12:24:17.397103864 +1000
@@ -8,11 +8,11 @@
 SCSI lower level drivers. Lower level drivers (LLDs) are variously called 
 host bus adapter (HBA) drivers and host drivers (HD). A "host" in this
 context is a bridge between a computer IO bus (e.g. PCI or ISA) and a
-single SCSI initiator device on a SCSI transport. An "initiator" device
-(SCSI terminology) sends SCSI commands to "target" SCSI devices (e.g.
-disks). There can be many LLDs in a running system, but only one per
-hardware type. Most LLDs can control one or more SCSI HBAs. Some HBAs 
-contain multiple hosts.
+single SCSI initiator port on a SCSI transport. An "initiator" port
+(SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands
+to "target" SCSI ports (e.g. disks). There can be many LLDs in a running
+system, but only one per hardware type. Most LLDs can control one or more
+SCSI HBAs. Some HBAs contain multiple hosts.
 
 In some cases the SCSI transport is an external bus that already has
 its own subsystem in Linux (e.g. USB and ieee1394). In such cases the
@@ -370,6 +370,7 @@
 names all start with "scsi_".
 
 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_timer - (re-)start timer on a SCSI command.
@@ -377,6 +378,7 @@
    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_delete_timer - cancel timer on a SCSI command.
    scsi_host_alloc - return a new scsi_host instance whose refcount==1
    scsi_host_get - increments Scsi_Host instance's refcount
@@ -397,6 +399,24 @@
 Details:
 
 /**
+ * scsi_activate_tcq - turn on tag command queueing ("ordered" task attribute)
+ * @sdev:       device to turn on TCQ for
+ * @depth:      queue depth
+ *
+ *      Returns nothing
+ *
+ *      Might block: no
+ *
+ *      Notes: Eventually, it is hoped depth would be the maximum depth
+ *      the device could cope with and the real queue depth
+ *      would be adjustable from 0 to depth.
+ *
+ *      Defined (inline) in: include/scsi/scsi_tcq.h
+ **/
+void scsi_activate_tcq(struct scsi_device *sdev, int depth)
+
+
+/**
  * scsi_add_device - creates new scsi device (lu) instance
  * @shost:   pointer to scsi host instance
  * @channel: channel number (rarely other than 0)
@@ -462,10 +482,10 @@
 
 
 /**
- * scsi_adjust_queue_depth - change the queue depth on a SCSI device
+ * scsi_adjust_queue_depth - allow LLD to change queue depth on a SCSI device
  * @sdev:       pointer to SCSI device to change queue depth on
  * @tagged:     0 - no tagged queuing
- *              MSG_SIMPLE_TAG - simple (unordered) tagged queuing
+ *              MSG_SIMPLE_TAG - simple tagged queuing
  *              MSG_ORDERED_TAG - ordered tagged queuing
  * @tags        Number of tags allowed if tagged queuing enabled,
  *              or number of commands the LLD can queue up
@@ -479,7 +499,7 @@
  *      LLD. [Specifically during and after slave_configure() and prior to
  *      slave_destroy().] Can safely be invoked from interrupt code. Actual
  *      queue depth change may be delayed until the next command is being
- *      processed.
+ *      processed. See also scsi_activate_tcq() and scsi_deactivate_tcq().
  *
  *      Defined in: drivers/scsi/scsi.c [see source code for more notes]
  *
@@ -535,6 +555,20 @@
 
 
 /**
+ * scsi_deactivate_tcq - turn off tag command queueing
+ * @sdev:       device to turn off TCQ for
+ * @depth:      queue depth (stored in sdev)
+ *
+ *      Returns nothing
+ *
+ *      Might block: no
+ *
+ *      Defined (inline) in: include/scsi/scsi_tcq.h
+ **/
+void scsi_deactivate_tcq(struct scsi_device *sdev, int depth)
+
+
+/**
  * scsi_delete_timer - cancel timer on a SCSI command.
  * @scmd:    pointer to scsi command instance
  *
@@ -1515,4 +1549,4 @@
 
 Douglas Gilbert
 dgilbert at interlog dot com
-25th August 2004
+21st September 2004

[PATCH] scsi_mid_low_api.txt update

[Douglas Gilbert]

[-- Attachment #1: Type: text/plain, Size: 149 bytes --]

After some prompting from Adrian Bunk here is an
update to the scsi mid level to lower level driver
(A)PI document.

Comments welcome.

Doug Gilbert

[-- Attachment #2: scsi_mid_low_api.txt268rc1.diff.gz --]
[-- Type: application/x-gzip, Size: 6025 bytes --]

[PATCH] scsi_mid_low_api.txt update

[Douglas Gilbert]

[-- Attachment #1: Type: text/plain, Size: 585 bytes --]

Attached is an update of the scsi_mid_low_api text
document. The first attachment is a gzipped patch against
lk 2.6.0-test4 and the second one is the file gzipped.

Changes:
   - add "Calling context:" entry to interface functions
   - add "Might block:" entry to mid level functions
   - drop scsi_set_device_offline() + command()
   - change references to reflect transfer of headers to
     include/scsi/scsi_*.h
   - try to define what a "scsi host" is
   - typos + grammar

Thanks to Randy Dunlap, Alan Stern amd Christoph Hellwig
for their input. Comments welcome.

Doug Gilbert

[-- Attachment #2: scsi_mid_low_api030829.diff.gz --]
[-- Type: application/x-gzip, Size: 11118 bytes --]

[-- Attachment #3: scsi_mid_low_api.txt.gz --]
[-- Type: application/x-gzip, Size: 15651 bytes --]

Re: [PATCH] scsi_mid_low_api.txt update

[Matthew Wilcox]

On Sun, Aug 31, 2003 at 04:44:25PM +1000, Douglas Gilbert wrote:
> Thanks to Randy Dunlap, Alan Stern amd Christoph Hellwig
> for their input. Comments welcome.

-Traditionally a LLD for the SCSI subsystem has been at least two files in
+Traditionally an LLD for the SCSI subsystem has been at least two files in

I disagree with this change.  LLD isn't a word or a pronouncable
abbreviation, it's an acronym.

-- 
"It's not Hollywood.  War is real, war is primarily not about defeat or
victory, it is about death.  I've seen thousands and thousands of dead bodies.
Do you think I want to have an academic debate on this subject?" -- Robert Fisk

Re: [PATCH] scsi_mid_low_api.txt update

[Alan Cox]

On Sul, 2003-08-31 at 14:38, Matthew Wilcox wrote:
> -Traditionally a LLD for the SCSI subsystem has been at least two files in
> +Traditionally an LLD for the SCSI subsystem has been at least two files in
> 
> I disagree with this change.  LLD isn't a word or a pronouncable
> abbreviation, it's an acronym.

I disagree with the disagreement. LLD gets pronounced as "El El Dee" so
its "an", "a El" doesn't flow and requires a stop. Btw it should be
L.L.D. I suspect ;)