Re: 2.5 scsi mid level - lower level interface description

Re: 2.5 scsi mid level - lower level interface description

[Mike Anderson]

Douglas Gilbert [dougg@torque.net] wrote:
> The attachment attempts to describe the interface between
> the scsi mid level and lower level drivers in the lk 2.5
> series.
> 
> It is a text file which I plan to place in the drivers/scsi
> directory. At the same time the rather dated callback
> function documentation in hosts.h could be removed and replaced 
> with a reference to this text file.

Good Document...

What about storing just part of the document in drivers/scsi?

Since the function descriptions are marked up for kernel-doc and kernel-doc runs on
your text document with a little bit of error output what about creating a
template portion of this document and then a api portion? 

The api portion could remain in the scsi directory and be included with a
!Edrivers/scsi/scsi_mid_low_api.txt. The struct data you reference could
also be obtained from the hosts.h, scsi.h, etc.

Using this method might help keep documentation in sync with the structs /
interfaces.

-Mike

-- 
Michael Anderson
andmike@us.ibm.com

Re: 2.5 scsi mid level - lower level interface description

[Patrick Mansfield]

On Tue, Apr 23, 2002 at 10:10:41PM -0400, Douglas Gilbert wrote:
> The attachment attempts to describe the interface between
> the scsi mid level and lower level drivers in the lk 2.5
> series.
> 
> It is a text file which I plan to place in the drivers/scsi
> directory. At the same time the rather dated callback
> function documentation in hosts.h could be removed and replaced 
> with a reference to this text file.
> 
> Criticisms, corrections and contributions are welcome.
> 
> Doug Gilbert

Doug,

Nice document.

I have a few suggested changes:

--- scsi_ll_inf.txt-orig	Wed Apr 24 09:41:05 2002
+++ scsi_ll_inf.txt	Wed Apr 24 17:08:47 2002
@@ -267,11 +267,9 @@
  *      @scp: pointer to scsi command object
  *      @done: function pointer to be invoked on completion
  *
- *      Returns an int with four component bytes: scsi_byte, msg_byte, 
- *      host_byte, driver_byte (status_byte is in the lsb). A value of
- *      0 is an unqualified success.
+ *      Returns 1 if the adapter is busy, else returns 0.
  *
- *      Required: if Scsi_Host::can_queue can ever by set (one)
+ *      Required: if Scsi_Host::can_queue is ever non-zero
  *                then this function is required.
  *
  *      Locks: Scsi_Host::host_lock held on entry (with "irqsave") and
@@ -281,7 +279,7 @@
  *      not wait for IO to complete. Hence the 'done' callback is invoked 
  *      (often directly from an interrupt service routine) sometime after
  *      this command has returned. In some cases (e.g. pseudo adapter 
- *      drivers the manufacture the response to a scsi INQUIRY)
+ *      drivers that manufacture the response to a scsi INQUIRY)
  *      the 'done' callback may be invoked before this function returns.
  *      If the 'done' callback is not invoked within a certain period
  *      the scsi mid level will commence error processing.
@@ -399,7 +397,8 @@
                    this host. Issued in ascending order from 0 (and the
                    positioning can be influenced by the scsihosts
                    kernel boot (or module) parameter
-    can_queue    - 1->use queuecommand(), 0->use command()
+    can_queue    - 0->use command(), greater than 0->use queuecommand() and do
+                   not send more than can_queue commands to the adapter.
     this_id      - scsi id of host (scsi initiator) or -1 if not known
     sg_tablesize - maximum scatter gather elements allowed by host.
                    0 implies scatter gather not supported by host
@@ -423,9 +422,9 @@
 
 Scsi_Device
 -----------
-There is one instance of this structure for each attached scsi (target) 
-device on a host. Scsi devices are uniquely identified within a host by 
-bus number, target id and logical unit number (lun).
+Generally, there is one instance of this structure for each scsi logical unit
+on a host. Scsi devices are uniquely identified within a host by bus number,
+target id and logical unit number (lun).
 The structure is defined in scsi.h
 
 Scsi_Cmnd
@@ -466,7 +465,7 @@
 -----
 [1] invoked during kernel initialization when built in or during module
     initialization. The scsi mid level will already be initialized.
-[2] detect() calls scsi_register() for each HBA is wants to control
+[2] detect() calls scsi_register() for each HBA it wants to control
     (if not scsi_register_host() will do it instead)
 [3] called as part of scsi bus scan during discovery of devices. This scan
     will be done for each host. Scsi commands such as INQUIRY, MODE SENSE


-- Patrick

Re: 2.5 scsi mid level - lower level interface description

[Douglas Gilbert]

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

Patrick Mansfield wrote:
> 
> On Tue, Apr 23, 2002 at 10:10:41PM -0400, Douglas Gilbert wrote:
> > The attachment attempts to describe the interface between
> > the scsi mid level and lower level drivers in the lk 2.5
> > series.
> >
> > It is a text file which I plan to place in the drivers/scsi
> > directory. At the same time the rather dated callback
> > function documentation in hosts.h could be removed and replaced
> > with a reference to this text file.
> >
> > Criticisms, corrections and contributions are welcome.
> >
> > Doug Gilbert
> 
> Doug,
> 
> Nice document.
> 
> I have a few suggested changes:

<snip/>

Patrick,
I have applied your patch and moved in the direction
that Mike has suggested. The functions headers have been
cleaned up so they go through the "!E" filter.
The attachment contains the following files:
   Documentation/DocBook/Makefile
   Documentation/DocBook/scsidrivers.tmpl
   drivers/scsi/scsi_mid_low_api.txt

It would be wise to take a copy of your tree's
Documentation/DocBook/Makefile before untarring in
your source tree. Then (if the docbook packages are
installed on your box) "make htmldocs" in the
/usr/src/linux directory should built multi-page html
in the /usr/src/linux/Documentation/DocBook/scsidrivers/
directory. "make psdocs" and "make pdfdocs" should also
work although the latter breaks with my toolset.

BTW the Makefile above was borrowed from 2.5.9-dj1 .

Doug Gilbert

[-- Attachment #2: scsi_mid_low_api.tgz --]
[-- Type: application/octet-stream, Size: 8999 bytes --]