scsi_mid_low_api.txt

linux 内核源代码

 *      Returns 0  - no change needed
 *              >0 - adjust queue depth to this new depth
 *              -1 - drop back to untagged operation using host->cmd_per_lun
 *                   as the untagged command depth
 *
 *      Might block: no
 *
 *      Notes: LLDs may call this at any time and we will do "The Right
 *              Thing"; interrupt context safe. 
 *
 *      Defined in: drivers/scsi/scsi.c .
 **/
int scsi_track_queue_full(struct scsi_device *sdev, int depth)


/**
 * scsi_unblock_requests - allow further commands to be queued to given host
 *
 * @shost: pointer to host to unblock commands on
 *
 *      Returns nothing
 *
 *      Might block: no
 *
 *      Defined in: drivers/scsi/scsi_lib.c .
**/
void scsi_unblock_requests(struct Scsi_Host * shost)


/**
 * scsi_unregister - unregister and free memory used by host instance
 * @shp:        pointer to scsi host instance to unregister.
 *
 *      Returns nothing
 *
 *      Might block: no
 *
 *      Notes: Should not be invoked if the "hotplug initialization
 *      model" is being used. Called internally by exit_this_scsi_driver()
 *      in the "passive initialization model". Hence a LLD has no need to
 *      call this function directly.
 *
 *      Defined in: drivers/scsi/hosts.c .
 **/
void scsi_unregister(struct Scsi_Host * shp)




Interface Functions
===================
Interface functions are supplied (defined) by LLDs and their function
pointers are placed in an instance of struct scsi_host_template which
is passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()].
Some are mandatory. Interface functions should be declared static. The
accepted convention is that driver "xyz" will declare its slave_configure() 
function as:
    static int xyz_slave_configure(struct scsi_device * sdev);
and so forth for all interface functions listed below.

A pointer to this function should be placed in the 'slave_configure' member
of a "struct scsi_host_template" instance. A pointer to such an instance
should be passed to the mid level's scsi_host_alloc() [or scsi_register() /
init_this_scsi_driver()].

The interface functions are also described in the include/scsi/scsi_host.h
file immediately above their definition point in "struct scsi_host_template".
In some cases more detail is given in scsi_host.h than below.

The interface functions are listed below in alphabetical order.

Summary:
   bios_param - fetch head, sector, cylinder info for a disk
   detect - detects HBAs this driver wants to control
   eh_timed_out - notify the host that a command timer expired
   eh_abort_handler - abort given command
   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)
   info - supply information about given host
   ioctl - driver can respond to ioctls
   proc_info - supports /proc/scsi/{driver_name}/{host_no}
   queuecommand - queue scsi command, invoke 'done' on completion
   release - release all resources associated with given host
   slave_alloc - prior to any commands being sent to a new device 
   slave_configure - driver fine tuning for given device after attach
   slave_destroy - given device is about to be shut down


Details:

/**
 *      bios_param - fetch head, sector, cylinder info for a disk
 *      @sdev: pointer to scsi device context (defined in 
 *             include/scsi/scsi_device.h)
 *      @bdev: pointer to block device context (defined in fs.h)
 *      @capacity:  device size (in 512 byte sectors)
 *      @params: three element array to place output:
 *              params[0] number of heads (max 255)
 *              params[1] number of sectors (max 63)
 *              params[2] number of cylinders 
 *
 *      Return value is ignored
 *
 *      Locks: none
 *
 *      Calling context: process (sd)
 *
 *      Notes: an arbitrary geometry (based on READ CAPACITY) is used
 *      if this function is not provided. The params array is
 *      pre-initialized with made up values just in case this function 
 *      doesn't output anything.
 *
 *      Optionally defined in: LLD
 **/
    int bios_param(struct scsi_device * sdev, struct block_device *bdev,
                   sector_t capacity, int params[3])


/**
 *      detect - detects HBAs this driver wants to control
 *      @shtp: host template for this driver.
 *
 *      Returns number of hosts this driver wants to control. 0 means no
 *      suitable hosts found.
 *
 *      Locks: none held
 *
 *      Calling context: process [invoked from init_this_scsi_driver()]
 *
 *      Notes: First function called from the SCSI mid level on this
 *      driver. Upper level drivers (e.g. sd) may not (yet) be present.
 *      For each host found, this method should call scsi_register() 
 *      [see hosts.c].
 *
 *      Defined in: LLD (required if "passive initialization mode" is used,
 *                       not invoked in "hotplug initialization mode")
 **/
    int detect(struct scsi_host_template * shtp)


/**
 *      eh_timed_out - The timer for the command has just fired
 *      @scp: identifies command timing out
 *
 *      Returns:
 *
 *      EH_HANDLED:             I fixed the error, please complete the command
 *      EH_RESET_TIMER:         I need more time, reset the timer and
 *                              begin counting again
 *      EH_NOT_HANDLED          Begin normal error recovery
 *
 *
 *      Locks: None held
 *
 *      Calling context: interrupt
 *
 *      Notes: This is to give the LLD an opportunity to do local recovery.
 *      This recovery is limited to determining if the outstanding command
 *      will ever complete.  You may not abort and restart the command from
 *      this callback.
 *
 *      Optionally defined in: LLD
 **/
     int eh_timed_out(struct scsi_cmnd * scp)


/**
 *      eh_abort_handler - abort command associated with scp
 *      @scp: identifies command to be aborted
 *
 *      Returns SUCCESS if command aborted else FAILED
 *
 *      Locks: None held
 *
 *      Calling context: kernel thread
 *
 *      Notes: Invoked from scsi_eh thread. No other commands will be
 *      queued on current host during eh.
 *
 *      Optionally defined in: LLD
 **/
     int eh_abort_handler(struct scsi_cmnd * scp)


/**
 *      eh_bus_reset_handler - issue SCSI bus reset
 *      @scp: SCSI bus that contains this device should be reset
 *
 *      Returns SUCCESS if command aborted else FAILED
 *
 *      Locks: None held
 *
 *      Calling context: kernel thread
 *
 *      Notes: Invoked from scsi_eh thread. No other commands will be
 *      queued on current host during eh.
 *
 *      Optionally defined in: LLD
 **/
     int eh_bus_reset_handler(struct scsi_cmnd * scp)


/**
 *      eh_device_reset_handler - issue SCSI device reset
 *      @scp: identifies SCSI device to be reset
 *
 *      Returns SUCCESS if command aborted else FAILED
 *
 *      Locks: None held
 *
 *      Calling context: kernel thread
 *
 *      Notes: Invoked from scsi_eh thread. No other commands will be
 *      queued on current host during eh.
 *
 *      Optionally defined in: LLD
 **/
     int eh_device_reset_handler(struct scsi_cmnd * scp)


/**
 *      eh_host_reset_handler - reset host (host bus adapter)
 *      @scp: SCSI host that contains this device should be reset
 *
 *      Returns SUCCESS if command aborted else FAILED
 *
 *      Locks: None held
 *
 *      Calling context: kernel thread
 *
 *      Notes: Invoked from scsi_eh thread. No other commands will be
 *      queued on current host during eh. 
 *      With the default eh_strategy in place, if none of the _abort_, 
 *      _device_reset_, _bus_reset_ or this eh handler function are 
 *      defined (or they all return FAILED) then the device in question 
 *      will be set offline whenever eh is invoked.
 *
 *      Optionally defined in: LLD
 **/
     int eh_host_reset_handler(struct scsi_cmnd * scp)


/**
 *      info - supply information about given host: driver name plus data
 *             to distinguish given host
 *      @shp: host to supply information about
 *
 *      Return ASCII null terminated string. [This driver is assumed to
 *      manage the memory pointed to and maintain it, typically for the
 *      lifetime of this host.]
 *
 *      Locks: none
 *
 *      Calling context: process
 *
 *      Notes: Often supplies PCI or ISA information such as IO addresses
 *      and interrupt numbers. If not supplied struct Scsi_Host::name used
 *      instead. It is assumed the returned information fits on one line 
 *      (i.e. does not included embedded newlines).
 *      The SCSI_IOCTL_PROBE_HOST ioctl yields the string returned by this
 *      function (or struct Scsi_Host::name if this function is not
 *      available).
 *      In a similar manner, init_this_scsi_driver() outputs to the console
 *      each host's "info" (or name) for the driver it is registering.
 *      Also if proc_info() is not supplied, the output of this function
 *      is used instead.
 *
 *      Optionally defined in: LLD
 **/
    const char * info(struct Scsi_Host * shp)


/**
 *      ioctl - driver can respond to ioctls
 *      @sdp: device that ioctl was issued for
 *      @cmd: ioctl number
 *      @arg: pointer to read or write data from. Since it points to
 *            user space, should use appropriate kernel functions
 *            (e.g. copy_from_user() ). In the Unix style this argument
 *            can also be viewed as an unsigned long.
 *
 *      Returns negative "errno" value when there is a problem. 0 or a
 *      positive value indicates success and is returned to the user space.
 *
 *      Locks: none
 *
 *      Calling context: process
 *
 *      Notes: The SCSI subsystem uses a "trickle down" ioctl model.
 *      The user issues an ioctl() against an upper level driver
 *      (e.g. /dev/sdc) and if the upper level driver doesn't recognize
 *      the 'cmd' then it is passed to the SCSI mid level. If the SCSI
 *      mid level does not recognize it, then the LLD that controls
 *      the device receives the ioctl. According to recent Unix standards
 *      unsupported ioctl() 'cmd' numbers should return -ENOTTY.
 *
 *      Optionally defined in: LLD
 **/
    int ioctl(struct scsi_device *sdp, int cmd, void *arg)


/**
 *      proc_info - supports /proc/scsi/{driver_name}/{host_no}
 *      @buffer: anchor point to output to (0==writeto1_read0) or fetch from
 *               (1==writeto1_read0).
 *      @start: where "interesting" data is written to. Ignored when
 *              1==writeto1_read0.
 *      @offset: offset within buffer 0==writeto1_read0 is actually
 *               interested in. Ignored when 1==writeto1_read0 .
 *      @length: maximum (or actual) extent of buffer
 *      @host_no: host number of interest (struct Scsi_Host::host_no)
 *      @writeto1_read0: 1 -> data coming from user space towards driver
 *                            (e.g. "echo some_string > /proc/scsi/xyz/2")
 *                       0 -> user what data from this driver
 *                            (e.g. "cat /proc/scsi/xyz/2")
 *
 *      Returns length when 1==writeto1_read0. Otherwise number of chars
 *      output to buffer past offset.
 *
 *      Locks: none held
 *
 *      Calling context: process
 *
 *      Notes: Driven from scsi_proc.c which interfaces to proc_fs. proc_fs
 *      support can now be configured out of the scsi subsystem.
 *
 *      Optionally defined in: LLD
 **/
    int proc_info(char * buffer, char ** start, off_t offset, 
                  int length, int host_no, int writeto1_read0)


/**
 *      queuecommand - queue scsi command, invoke 'done' on completion
 *      @scp: pointer to scsi command object
 *      @done: function pointer to be invoked on completion
 *
 *      Returns 0 on success.
 *
 *      If there's a failure, return either:
 *
 *      SCSI_MLQUEUE_DEVICE_BUSY if the device queue is full, or
 *      SCSI_MLQUEUE_HOST_BUSY if the entire host queue is full
 *
 *      On both of these returns, the mid-layer will requeue the I/O
 *
 *      - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular
 *      device will be paused, and it will be unpaused when a command to
 *      the device returns (or after a brief delay if there are no more
 *      outstanding commands to it).  Commands to other devices continue
 *      to be processed normally.
 *
 *      - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host
 *      is paused and will be unpaused when any command returns from
 *      the host (or after a brief delay if there are no outstanding