scsi_mid_low_api.txt

linux 内核源代码

                          Linux Kernel 2.6 series
                 SCSI mid_level - lower_level driver interface
                 =============================================

Introduction
============
This document outlines the interface between the Linux SCSI mid level and
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 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
SCSI subsystem LLD is a software bridge to the other driver subsystem.
Examples are the usb-storage driver (found in the drivers/usb/storage
directory) and the ieee1394/sbp2 driver (found in the drivers/ieee1394
directory).

For example, the aic7xxx LLD controls Adaptec SCSI parallel interface
(SPI) controllers based on that company's 7xxx chip series. The aic7xxx
LLD can be built into the kernel or loaded as a module. There can only be
one aic7xxx LLD running in a Linux system but it may be controlling many 
HBAs. These HBAs might be either on PCI daughter-boards or built into 
the motherboard (or both). Some aic7xxx based HBAs are dual controllers
and thus represent two hosts. Like most modern HBAs, each aic7xxx host
has its own PCI device address. [The one-to-one correspondence between
a SCSI host and a PCI device is common but not required (e.g. with
ISA or MCA adapters).]

The SCSI mid level isolates an LLD from other layers such as the SCSI
upper layer drivers and the block layer.

This version of the document roughly matches linux kernel version 2.6.8 .

Documentation
=============
There is a SCSI documentation directory within the kernel source tree, 
typically Documentation/scsi . Most documents are in plain
(i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be 
found in that directory. A more recent copy of this document may be found
at http://www.torque.net/scsi/scsi_mid_low_api.txt.gz . 
Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is
briefly described in scsi.txt which contains a url to a document 
describing the SCSI subsystem in the lk 2.4 series. Two upper level 
drivers have documents in that directory: st.txt (SCSI tape driver) and 
scsi-generic.txt (for the sg driver).

Some documentation (or urls) for LLDs may be found in the C source code
or in the same directory as the C source code. For example to find a url
about the USB mass storage driver see the 
/usr/src/linux/drivers/usb/storage directory.

The Linux kernel source Documentation/DocBook/scsidrivers.tmpl file
refers to this file. With the appropriate DocBook tool-set, this permits
users to generate html, ps and pdf renderings of information within this
file (e.g. the interface functions).

Driver structure
================
Traditionally an LLD for the SCSI subsystem has been at least two files in
the drivers/scsi directory. For example, a driver called "xyz" has a header
file "xyz.h" and a source file "xyz.c". [Actually there is no good reason
why this couldn't all be in one file; the header file is superfluous.] Some
drivers that have been ported to several operating systems have more than
two files. For example the aic7xxx driver has separate files for generic 
and OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have
their own directory under the drivers/scsi directory.

When a new LLD is being added to Linux, the following files (found in the
drivers/scsi directory) will need some attention: Makefile and Kconfig .
It is probably best to study how existing LLDs are organized.

As the 2.5 series development kernels evolve into the 2.6 series
production series, changes are being introduced into this interface. An
example of this is driver initialization code where there are now 2 models
available. The older one, similar to what was found in the lk 2.4 series,
is based on hosts that are detected at HBA driver load time. This will be
referred to the "passive" initialization model. The newer model allows HBAs
to be hot plugged (and unplugged) during the lifetime of the LLD and will
be referred to as the "hotplug" initialization model. The newer model is
preferred as it can handle both traditional SCSI equipment that is
permanently connected as well as modern "SCSI" devices (e.g. USB or
IEEE 1394 connected digital cameras) that are hotplugged. Both 
initialization models are discussed in the following sections.

An LLD interfaces to the SCSI subsystem several ways:
  a) directly invoking functions supplied by the mid level
  b) passing a set of function pointers to a registration function
     supplied by the mid level. The mid level will then invoke these
     functions at some point in the future. The LLD will supply
     implementations of these functions.
  c) direct access to instances of well known data structures maintained
     by the mid level

Those functions in group a) are listed in a section entitled "Mid level
supplied functions" below.

Those functions in group b) are listed in a section entitled "Interface
functions" below. Their function pointers are placed in the members of
"struct scsi_host_template", an instance of which is passed to
scsi_host_alloc() ** .  Those interface functions that the LLD does not 
wish to supply should have NULL placed in the corresponding member of 
struct scsi_host_template.  Defining an instance of struct 
scsi_host_template at file scope will cause NULL to be  placed in function
 pointer members not explicitly initialized.

Those usages in group c) should be handled with care, especially in a
"hotplug" environment. LLDs should be aware of the lifetime of instances
that are shared with the mid level and other layers.

All functions defined within an LLD and all data defined at file scope
should be static. For example the slave_alloc() function in an LLD
called "xxx" could be defined as 
"static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }"

** the scsi_host_alloc() function is a replacement for the rather vaguely
named scsi_register() function in most situations. The scsi_register()
and scsi_unregister() functions remain to support legacy LLDs that use
the passive initialization model.


Hotplug initialization model
============================
In this model an LLD controls when SCSI hosts are introduced and removed
from the SCSI subsystem. Hosts can be introduced as early as driver
initialization and removed as late as driver shutdown. Typically a driver
will respond to a sysfs probe() callback that indicates an HBA has been
detected. After confirming that the new device is one that the LLD wants
to control, the LLD will initialize the HBA and then register a new host
with the SCSI mid level.

During LLD initialization the driver should register itself with the
appropriate IO bus on which it expects to find HBA(s) (e.g. the PCI bus).
This can probably be done via sysfs. Any driver parameters (especially
those that are writable after the driver is loaded) could also be
registered with sysfs at this point. The SCSI mid level first becomes
aware of an LLD when that LLD registers its first HBA.

At some later time, the LLD becomes aware of an HBA and what follows
is a typical sequence of calls between the LLD and the mid level.
This example shows the mid level scanning the newly introduced HBA for 3 
scsi devices of which only the first 2 respond:

     HBA PROBE: assume 2 SCSI devices found in scan
LLD                   mid level                    LLD
===-------------------=========--------------------===------
scsi_host_alloc()  -->
scsi_add_host()  ---->
scsi_scan_host()  -------+
                         |
                    slave_alloc()
                    slave_configure() -->  scsi_adjust_queue_depth()
                         |
                    slave_alloc()
                    slave_configure()
                         |
                    slave_alloc()   ***
                    slave_destroy() ***
------------------------------------------------------------

If the LLD wants to adjust the default queue settings, it can invoke
scsi_adjust_queue_depth() in its slave_configure() routine.

*** For scsi devices that the mid level tries to scan but do not
    respond, a slave_alloc(), slave_destroy() pair is called.

When an HBA is being removed it could be as part of an orderly shutdown
associated with the LLD module being unloaded (e.g. with the "rmmod"
command) or in response to a "hot unplug" indicated by sysfs()'s
remove() callback being invoked. In either case, the sequence is the
same:

        HBA REMOVE: assume 2 SCSI devices attached
LLD                      mid level                 LLD
===----------------------=========-----------------===------
scsi_remove_host() ---------+
                            |
                     slave_destroy()
                     slave_destroy()
scsi_host_put()
------------------------------------------------------------
                     
It may be useful for a LLD to keep track of struct Scsi_Host instances
(a pointer is returned by scsi_host_alloc()). Such instances are "owned"
by the mid-level.  struct Scsi_Host instances are freed from
scsi_host_put() when the reference count hits zero.

Hot unplugging an HBA that controls a disk which is processing SCSI
commands on a mounted file system is an interesting situation. Reference
counting logic is being introduced into the mid level to cope with many
of the issues involved. See the section on reference counting below.


The hotplug concept may be extended to SCSI devices. Currently, when an
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:

                 SCSI DEVICE hotplug
LLD                   mid level                    LLD
===-------------------=========--------------------===------
scsi_add_device()  ------+
                         |
                    slave_alloc()
                    slave_configure()   [--> scsi_adjust_queue_depth()]
------------------------------------------------------------

In a similar fashion, an LLD may become aware that a SCSI device has been
removed (unplugged) or the connection to it has been interrupted. Some
existing SCSI transports (e.g. SPI) may not become aware that a SCSI
device has been removed until a subsequent SCSI command fails which will
probably cause that device to be set offline by the mid level. An LLD that
detects the removal of a SCSI device can instigate its removal from
upper layers with this sequence:

                  SCSI DEVICE hot unplug
LLD                      mid level                 LLD
===----------------------=========-----------------===------
scsi_remove_device() -------+
                            |
                     slave_destroy()
------------------------------------------------------------

It may be useful for an LLD to keep track of struct scsi_device instances
(a pointer is passed as the parameter to slave_alloc() and
slave_configure() callbacks). Such instances are "owned" by the mid-level.
struct scsi_device instances are freed after slave_destroy().


Passive initialization model
============================
These older LLDs include a file called "scsi_module.c" [yes the ".c" is a
little surprising] in their source code. For that file to work an
instance of struct scsi_host_template with the name "driver_template"
needs to be defined. Here is a typical code sequence used in this model:
    static struct scsi_host_template driver_template = {
        ...
    };
    #include "scsi_module.c"

The scsi_module.c file contains two functions:
  - init_this_scsi_driver() which is executed when the LLD is
    initialized (i.e. boot time or module load time)
  - exit_this_scsi_driver() which is executed when the LLD is shut
    down (i.e. module unload time)
Note: since these functions are tagged with __init and __exit qualifiers
an LLD should not call them explicitly (since the kernel does that).

Here is an example of an initialization sequence when two hosts are
detected (so detect() returns 2) and the SCSI bus scan on each host
finds 1 SCSI device (and a second device does not respond).

LLD                      mid level                 LLD
===----------------------=========-----------------===------
init_this_scsi_driver() ----+
                            |
                         detect()  -----------------+
                            |                       |
                            |                scsi_register()
                            |                scsi_register()
                            |
                      slave_alloc()
                      slave_configure()  -->  scsi_adjust_queue_depth()
                      slave_alloc()   ***
                      slave_destroy() ***
                            |
                      slave_alloc()
                      slave_configure()
                      slave_alloc()   ***
                      slave_destroy() ***
------------------------------------------------------------

The mid level invokes scsi_adjust_queue_depth() with tagged queuing off and
"cmd_per_lun" for that host as the queue length. These settings can be
overridden by a slave_configure() supplied by the LLD.

*** For scsi devices that the mid level tries to scan but do not
    respond, a slave_alloc(), slave_destroy() pair is called.

Here is an LLD shutdown sequence:

LLD                      mid level                 LLD
===----------------------=========-----------------===------
exit_this_scsi_driver() ----+
                            |
                     slave_destroy()
                        release()   -->   scsi_unregister()
                            |
                     slave_destroy()
                        release()   -->   scsi_unregister()
------------------------------------------------------------

An LLD need not define slave_destroy() (i.e. it is optional). 

The shortcoming of the "passive initialization model" is that host
registration and de-registration are (typically) tied to LLD initialization
and shutdown. Once the LLD is initialized then a new host that appears
(e.g. via hotplugging) cannot easily be added without a redundant
driver shutdown and re-initialization. It may be possible to write an LLD
that uses both initialization models.


Reference Counting
==================
The Scsi_Host structure has had reference counting infrastructure added.
This effectively spreads the ownership of struct Scsi_Host instances
across the various SCSI layers which use them. Previously such instances
were exclusively owned by the mid level. LLDs would not usually need to
directly manipulate these reference counts but there may be some cases
where they do.

There are 3 reference counting functions of interest associated with
struct Scsi_Host:
  - scsi_host_alloc(): returns a pointer to new instance of struct 
        Scsi_Host which has its reference count ^^ set to 1
  - scsi_host_get(): adds 1 to the reference count of the given instance
  - scsi_host_put(): decrements 1 from the reference count of the given
        instance. If the reference count reaches 0 then the given instance
        is freed

The Scsi_device structure has had reference counting infrastructure added.
This effectively spreads the ownership of struct Scsi_device instances
across the various SCSI layers which use them. Previously such instances
were exclusively owned by the mid level. See the access functions declared
towards the end of include/scsi/scsi_device.h . If an LLD wants to keep
a copy of a pointer to a Scsi_device instance it should use scsi_device_get()
to bump its reference count. When it is finished with the pointer it can
use scsi_device_put() to decrement its reference count (and potentially
delete it).

^^ struct Scsi_Host actually has 2 reference counts which are manipulated
in parallel by these functions.


Conventions
===========
First, Linus Torvalds's thoughts on C coding style can be found in the
Documentation/CodingStyle file. 

Next, there is a movement to "outlaw" typedefs introducing synonyms for 
struct tags. Both can be still found in the SCSI subsystem, but
the typedefs have been moved to a single file, scsi_typedefs.h to
make their future removal easier, for example: 
"typedef struct scsi_cmnd Scsi_Cmnd;"

Also, most C99 enhancements are encouraged to the extent they are supported
by the relevant gcc compilers. So C99 style structure and array
initializers are encouraged where appropriate. Don't go too far,
VLAs are not properly supported yet.  An exception to this is the use of
"//" style comments; /*...*/ comments are still preferred in Linux.