scsi_mid_low_api.txt

linux 内核源代码

Well written, tested and documented code, need not be re-formatted to
comply with the above conventions. For example, the aic7xxx driver
comes to Linux from FreeBSD and Adaptec's own labs. No doubt FreeBSD
and Adaptec have their own coding conventions.


Mid level supplied functions
============================
These functions are supplied by the SCSI mid level for use by LLDs.
The names (i.e. entry points) of these functions are exported 
so an LLD that is a module can access them. The kernel will
arrange for the SCSI mid level to be loaded and initialized before any LLD
is initialized. The functions below are listed alphabetically and their
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 set up transport class
   scsi_adjust_queue_depth - change the queue depth on a SCSI device
   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_host_alloc - return a new scsi_host instance whose refcount==1
   scsi_host_get - increments Scsi_Host instance's refcount
   scsi_host_put - decrements Scsi_Host instance's refcount (free if 0)
   scsi_partsize - parse partition table into cylinders, heads + sectors
   scsi_register - create and register a scsi host adapter instance.
   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()]


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)
 * @id:      target id number
 * @lun:     logical unit number
 *
 *      Returns pointer to new struct scsi_device instance or 
 *      ERR_PTR(-ENODEV) (or some other bent pointer) if something is
 *      wrong (e.g. no lu responds at given address)
 *
 *      Might block: yes
 *
 *      Notes: This call is usually performed internally during a scsi
 *      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
 *      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
 **/
struct scsi_device * scsi_add_device(struct Scsi_Host *shost, 
                                     unsigned int channel,
                                     unsigned int id, unsigned int lun)


/**
 * 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
 *
 *      Returns 0 on success, negative errno of failure (e.g. -ENOMEM)
 *
 *      Might block: no
 *
 *      Notes: Only required in "hotplug initialization model" after a
 *      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
 **/
int scsi_add_host(struct Scsi_Host *shost, struct device * dev)


/**
 * 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 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
 *              in non-tagged mode (as per cmd_per_lun).
 *
 *      Returns nothing
 *
 *      Might block: no
 *
 *      Notes: Can be invoked any time on a SCSI device controlled by this
 *      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. See also scsi_activate_tcq() and scsi_deactivate_tcq().
 *
 *      Defined in: drivers/scsi/scsi.c [see source code for more notes]
 *
 **/
void scsi_adjust_queue_depth(struct scsi_device * sdev, int tagged, 
                             int tags)


/**
 * scsi_bios_ptable - return copy of block device's partition table
 * @dev:        pointer to block device
 *
 *      Returns pointer to partition table, or NULL for failure
 *
 *      Might block: yes
 *
 *      Notes: Caller owns memory returned (free with kfree() )
 *
 *      Defined in: drivers/scsi/scsicam.c
 **/
unsigned char *scsi_bios_ptable(struct block_device *dev)


/**
 * scsi_block_requests - prevent further commands being queued to given host
 *
 * @shost: pointer to host to block commands on
 *
 *      Returns nothing
 *
 *      Might block: no
 *
 *      Notes: There is no timer nor any other means by which the requests
 *      get unblocked other than the LLD calling scsi_unblock_requests().
 *
 *      Defined in: drivers/scsi/scsi_lib.c
**/
void scsi_block_requests(struct Scsi_Host * shost)


/**
 * 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_host_alloc - create a scsi host adapter instance and perform basic
 *                   initialization.
 * @sht:        pointer to scsi host template
 * @privsize:   extra bytes to allocate in hostdata array (which is the
 *              last member of the returned Scsi_Host instance)
 *
 *      Returns pointer to new Scsi_Host instance or NULL on failure
 *
 *      Might block: yes
 *
 *      Notes: When this call returns to the LLD, the SCSI bus scan on
 *      this host has _not_ yet been done.
 *      The hostdata array (by default zero length) is a per host scratch 
 *      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() and scsi_scan_host() are called.
 *
 *      Defined in: drivers/scsi/hosts.c .
 **/
struct Scsi_Host * scsi_host_alloc(struct scsi_host_template * sht,
                                   int privsize)


/**
 * scsi_host_get - increment Scsi_Host instance refcount
 * @shost:   pointer to struct Scsi_Host instance
 *
 *      Returns nothing
 *
 *      Might block: currently may block but may be changed to not block
 *
 *      Notes: Actually increments the counts in two sub-objects
 *
 *      Defined in: drivers/scsi/hosts.c
 **/
void scsi_host_get(struct Scsi_Host *shost)


/**
 * scsi_host_put - decrement Scsi_Host instance refcount, free if 0
 * @shost:   pointer to struct Scsi_Host instance
 *
 *      Returns nothing
 *
 *      Might block: currently may block but may be changed to not block
 *
 *      Notes: Actually decrements the counts in two sub-objects. If the
 *      latter refcount reaches 0, the Scsi_Host instance is freed.
 *      The LLD need not worry exactly when the Scsi_Host instance is
 *      freed, it just shouldn't access the instance after it has balanced
 *      out its refcount usage.
 *
 *      Defined in: drivers/scsi/hosts.c
 **/
void scsi_host_put(struct Scsi_Host *shost)


/**
 * scsi_partsize - parse partition table into cylinders, heads + sectors
 * @buf: pointer to partition table
 * @capacity: size of (total) disk in 512 byte sectors
 * @cyls: outputs number of cylinders calculated via this pointer
 * @hds: outputs number of heads calculated via this pointer
 * @secs: outputs number of sectors calculated via this pointer
 *
 *      Returns 0 on success, -1 on failure
 *
 *      Might block: no
 *
 *      Notes: Caller owns memory returned (free with kfree() )
 *
 *      Defined in: drivers/scsi/scsicam.c
 **/
int scsi_partsize(unsigned char *buf, unsigned long capacity,
                  unsigned int *cyls, unsigned int *hds, unsigned int *secs)


/**
 * scsi_register - create and register a scsi host adapter instance.
 * @sht:        pointer to scsi host template
 * @privsize:   extra bytes to allocate in hostdata array (which is the
 *              last member of the returned Scsi_Host instance)
 *
 *      Returns pointer to new Scsi_Host instance or NULL on failure
 *
 *      Might block: yes
 *
 *      Notes: When this call returns to the LLD, the SCSI bus scan on
 *      this host has _not_ yet been done.
 *      The hostdata array (by default zero length) is a per host scratch 
 *      area for the LLD.
 *
 *      Defined in: drivers/scsi/hosts.c .
 **/
struct Scsi_Host * scsi_register(struct scsi_host_template * sht,
                                 int privsize)


/**
 * scsi_remove_device - detach and remove a SCSI device
 * @sdev:      a pointer to a scsi device instance
 *
 *      Returns value: 0 on success, -EINVAL if device not attached
 *
 *      Might block: yes
 *
 *      Notes: If an LLD becomes aware that a scsi device (lu) has
 *      been removed but its host is still present then it can request
 *      the removal of that scsi device. If successful this call will
 *      lead to the slave_destroy() callback being invoked. sdev is an 
 *      invalid pointer after this call.
 *
 *      Defined in: drivers/scsi/scsi_sysfs.c .
 **/
int scsi_remove_device(struct scsi_device *sdev)


/**
 * scsi_remove_host - detach and remove all SCSI devices owned by host
 * @shost:      a pointer to a scsi host instance
 *
 *      Returns value: 0 on success, 1 on failure (e.g. LLD busy ??)
 *
 *      Might block: yes
 *
 *      Notes: Should only be invoked if the "hotplug initialization
 *      model" is being used. It should be called _prior_ to  
 *      scsi_unregister().
 *
 *      Defined in: drivers/scsi/hosts.c .
 **/
int scsi_remove_host(struct Scsi_Host *shost)


/**
 * scsi_report_bus_reset - report scsi _bus_ reset observed
 * @shost: a pointer to a scsi host involved
 * @channel: channel (within) host on which scsi bus reset occurred
 *
 *      Returns nothing
 *
 *      Might block: no
 *
 *      Notes: This only needs to be called if the reset is one which
 *      originates from an unknown location.  Resets originated by the 
 *      mid level itself don't need to call this, but there should be 
 *      no harm.  The main purpose of this is to make sure that a
 *      CHECK_CONDITION is properly treated.
 *
 *      Defined in: drivers/scsi/scsi_error.c .
 **/
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.
 * @sdev:  pointer to SCSI device instance
 * @depth: Current number of outstanding SCSI commands on this device,
 *         not counting the one returned as QUEUE_FULL.
 *