HBA PROBE: assume 2 SCSI devices found in scanLLD                   mid level                    LLD===-------------------=========--------------------===------scsi_host_alloc()  -->scsi_add_host()  ---->scsi_scan_host()  -------+                        |                    slave_alloc()                    slave_configure() -->  scsi_change_queue_depth()                        |                    slave_alloc()                    slave_configure()                        |                    slave_alloc()   ***                    slave_destroy() ****** For scsi devices that the mid level tries to scan but do not    respond, a slave_alloc(), slave_destroy() pair is called.

        HBA REMOVE: assume 2 SCSI devices attachedLLD                      mid level                 LLD===----------------------=========-----------------===------scsi_remove_host() ---------+                            |                    slave_destroy()                    slave_destroy()scsi_host_put()

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

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

/*** 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_change_queue_depth - allow LLD to change queue depth on a SCSI device* @sdev:       pointer to SCSI device to change queue depth on* @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.**      Defined in: drivers/scsi/scsi.c [see source code for more notes]***/int scsi_change_queue_depth(struct scsi_device *sdev, 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_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_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.**      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)

static int xyz_slave_configure(struct scsi_device * sdev);

/***      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])/***      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: If 'no_async_abort' is defined this callback*   will be invoked from scsi_eh thread. No other commands*   will then be queued on current host during eh.*   Otherwise it will be called whenever scsi_times_out()*      is called due to a command timeout.**      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 scp->scsi_done on completion*      @shost: pointer to the scsi host object*      @scp: pointer to scsi command object**      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*      commands to the host).**      For compatibility with earlier versions of queuecommand, any*      other return value is treated the same as*      SCSI_MLQUEUE_HOST_BUSY.**      Other types of errors that are detected immediately may be*      flagged by setting scp->result to an appropriate value,*      invoking the scp->scsi_done callback, and then returning 0*      from this function. If the command is not performed*      immediately (and the LLD is starting (or will start) the given*      command) then this function should place 0 in scp->result and*      return 0.**      Command ownership.  If the driver returns zero, it owns the*      command and must take responsibility for ensuring the*      scp->scsi_done callback is executed.  Note: the driver may*      call scp->scsi_done before returning zero, but after it has*      called scp->scsi_done, it may not return any value other than*      zero.  If the driver makes a non-zero return, it must not*      execute the command's scsi_done callback at any time.**      Locks: up to and including 2.6.36, struct Scsi_Host::host_lock*             held on entry (with "irqsave") and is expected to be*             held on return. From 2.6.37 onwards, queuecommand is*             called without any locks held.**      Calling context: in interrupt (soft irq) or process context**      Notes: This function should be relatively fast. Normally it*      will not wait for IO to complete. Hence the scp->scsi_done*      callback is invoked (often directly from an interrupt service*      routine) some time after this function has returned. In some*      cases (e.g. pseudo adapter drivers that manufacture the*      response to a SCSI INQUIRY) the scp->scsi_done callback may be*      invoked before this function returns.  If the scp->scsi_done*      callback is not invoked within a certain period the SCSI mid*      level will commence error processing.  If a status of CHECK*      CONDITION is placed in "result" when the scp->scsi_done*      callback is invoked, then the LLD driver should perform*      autosense and fill in the struct scsi_cmnd::sense_buffer*      array. The scsi_cmnd::sense_buffer array is zeroed prior to*      the mid level queuing a command to an LLD.**      Defined in: LLD**/    int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp)/***      slave_alloc -   prior to any commands being sent to a new device*                      (i.e. just prior to scan) this call is made*      @sdp: pointer to new device (about to be scanned)**      Returns 0 if ok. Any other return is assumed to be an error and*      the device is ignored.**      Locks: none**      Calling context: process**      Notes: Allows the driver to allocate any resources for a device*      prior to its initial scan. The corresponding scsi device may not*      exist but the mid level is just about to scan for it (i.e. send*      and INQUIRY command plus ...). If a device is found then*      slave_configure() will be called while if a device is not found*      slave_destroy() is called.*      For more details see the include/scsi/scsi_host.h file.**      Optionally defined in: LLD**/    int slave_alloc(struct scsi_device *sdp)/***      slave_configure - driver fine tuning for given device just after it*                     has been first scanned (i.e. it responded to an*                     INQUIRY)*      @sdp: device that has just been attached**      Returns 0 if ok. Any other return is assumed to be an error and*      the device is taken offline. [offline devices will _not_ have*      slave_destroy() called on them so clean up resources.]**      Locks: none**      Calling context: process**      Notes: Allows the driver to inspect the response to the initial*      INQUIRY done by the scanning code and take appropriate action.*      For more details see the include/scsi/scsi_host.h file.**      Optionally defined in: LLD**/    int slave_configure(struct scsi_device *sdp)/***      slave_destroy - given device is about to be shut down. All*                      activity has ceased on this device.*      @sdp: device that is about to be shut down**      Returns nothing**      Locks: none**      Calling context: process**      Notes: Mid level structures for given device are still in place*      but are about to be torn down. Any per device resources allocated*      by this driver for given device should be freed now. No further*      commands will be sent for this sdp instance. [However the device*      could be re-attached in the future in which case a new instance*      of struct scsi_device would be supplied by future slave_alloc()*      and slave_configure() calls.]**      Optionally defined in: LLD**/    void slave_destroy(struct scsi_device *sdp)