LLD mid level LLD
===-------------------=========--------------------===------
scsi_host_alloc() -->
-scsi_add_host() --------+
+scsi_add_host() ---->
+scsi_scan_host() -------+
|
slave_alloc()
slave_configure() --> scsi_adjust_queue_depth()
The hotplug concept may be extended to SCSI devices. Currently, when an
-HBA is added, the scsi_add_host() function causes a scan for SCSI devices
+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:
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_host_template Scsi_Host_Template;"
+"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
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 SCSI bus scan.
- scsi_add_timer - (re-)start timer on a SCSI command.
+ scsi_add_host - perform sysfs registration and set up transport class
scsi_adjust_queue_depth - change the queue depth on a SCSI device
- scsi_assign_lock - replace default host_lock with given lock
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_delete_timer - cancel timer on a SCSI command.
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_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_set_device - place device reference in host structure
+ 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()]
* Might block: yes
*
* Notes: This call is usually performed internally during a scsi
- * bus scan when an HBA is added (i.e. scsi_add_host()). So it
+ * 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_add_host() has completed. If successful
- * this call we lead to slave_alloc() and slave_configure() callbacks
+ * 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
/**
- * scsi_add_host - perform sysfs registration and SCSI bus scan.
+ * 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
*
* Might block: no
*
* Notes: Only required in "hotplug initialization model" after a
- * successful call to scsi_host_alloc().
+ * 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
**/
/**
- * scsi_add_timer - (re-)start timer on a SCSI command.
- * @scmd: pointer to scsi command instance
- * @timeout: duration of timeout in "jiffies"
- * @complete: pointer to function to call if timeout expires
- *
- * Returns nothing
- *
- * Might block: no
- *
- * Notes: Each scsi command has its own timer, and as it is added
- * to the queue, we set up the timer. When the command completes,
- * we cancel the timer. An LLD can use this function to change
- * the existing timeout value.
- *
- * Defined in: drivers/scsi/scsi_error.c
- **/
-void scsi_add_timer(struct scsi_cmnd *scmd, int timeout,
- void (*complete)(struct scsi_cmnd *))
-
-
-/**
* 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
/**
- * scsi_assign_lock - replace default host_lock with given lock
- * @shost: a pointer to a scsi host instance
- * @lock: pointer to lock to replace host_lock for this host
- *
- * Returns nothing
- *
- * Might block: no
- *
- * Defined in: include/scsi/scsi_host.h .
- **/
-void scsi_assign_lock(struct Scsi_Host *shost, spinlock_t *lock)
-
-
-/**
* scsi_bios_ptable - return copy of block device's partition table
* @dev: pointer to block device
*
/**
- * scsi_delete_timer - cancel timer on a SCSI command.
- * @scmd: pointer to scsi command instance
- *
- * Returns 1 if able to cancel timer else 0 (i.e. too late or already
- * cancelled).
- *
- * Might block: no [may in the future if it invokes del_timer_sync()]
- *
- * Notes: All commands issued by upper levels already have a timeout
- * associated with them. An LLD can use this function to cancel the
- * timer.
- *
- * Defined in: drivers/scsi/scsi_error.c
- **/
-int scsi_delete_timer(struct scsi_cmnd *scmd)
-
-
-/**
* scsi_host_alloc - create a scsi host adapter instance and perform basic
* initialization.
* @sht: pointer to scsi host template
* 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() is called.
+ * scsi_add_host() and scsi_scan_host() are called.
*
* Defined in: drivers/scsi/hosts.c .
**/
/**
- * scsi_set_device - place device reference in host structure
+ * scsi_scan_host - scan SCSI bus
* @shost: a pointer to a scsi host instance
- * @pdev: pointer to device instance to assign
*
- * Returns nothing
+ * Might block: yes
*
- * Might block: no
+ * Notes: Should be called after scsi_add_host()
*
- * Defined in: include/scsi/scsi_host.h .
+ * Defined in: drivers/scsi/scsi_scan.c
**/
-void scsi_set_device(struct Scsi_Host * shost, struct device * dev)
+void scsi_scan_host(struct Scsi_Host *shost)
/**
*
* Defined in: drivers/scsi/scsi.c .
**/
-int scsi_track_queue_full(Scsi_Device *sdev, int depth)
+int scsi_track_queue_full(struct scsi_device *sdev, int depth)
/**
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)
- eh_strategy_handler - driver supplied alternate to scsi_unjam_host()
info - supply information about given host
ioctl - driver can respond to ioctls
proc_info - supports /proc/scsi/{driver_name}/{host_no}
*
* Returns SUCCESS if command aborted else FAILED
*
- * Locks: struct Scsi_Host::host_lock held (with irqsave) on entry
- * and assumed to be held on return.
+ * Locks: None held
*
* Calling context: kernel thread
*
*
* Returns SUCCESS if command aborted else FAILED
*
- * Locks: struct Scsi_Host::host_lock held (with irqsave) on entry
- * and assumed to be held on return.
+ * Locks: None held
*
* Calling context: kernel thread
*
/**
- * eh_strategy_handler - driver supplied alternate to scsi_unjam_host()
- * @shp: host on which error has occurred
- *
- * Returns TRUE if host unjammed, else FALSE.
- *
- * Locks: none
- *
- * Calling context: kernel thread
- *
- * Notes: Invoked from scsi_eh thread. LLD supplied alternate to
- * scsi_unjam_host() found in scsi_error.c
- *
- * Optionally defined in: LLD
- **/
- int eh_strategy_handler(struct Scsi_Host * shp)
-
-
-/**
* info - supply information about given host: driver name plus data
* to distinguish given host
* @shp: host to supply information about
hostdata[0] - area reserved for LLD at end of struct Scsi_Host. Size
is set by the second argument (named 'xtr_bytes') to
scsi_host_alloc() or scsi_register().
+ vendor_id - a unique value that identifies the vendor supplying
+ the LLD for the Scsi_Host. Used most often in validating
+ vendor-specific message requests. Value consists of an
+ identifier type and a vendor-specific value.
+ See scsi_netlink.h for a description of valid formats.
The scsi_host structure is defined in include/scsi/scsi_host.h
Each struct Scsi_Host instance has a spin_lock called struct
Scsi_Host::default_lock which is initialized in scsi_host_alloc() [found in
hosts.c]. Within the same function the struct Scsi_Host::host_lock pointer
-is initialized to point at default_lock with the scsi_assign_lock() function.
-Thereafter lock and unlock operations performed by the mid level use the
-struct Scsi_Host::host_lock pointer.
-
-LLDs can override the use of struct Scsi_Host::default_lock by
-using scsi_assign_lock(). The earliest opportunity to do this would
-be in the detect() function after it has invoked scsi_register(). It
-could be replaced by a coarser grain lock (e.g. per driver) or a
-lock of equal granularity (i.e. per host). Using finer grain locks
-(e.g. per SCSI device) may be possible by juggling locks in
-queuecommand().
+is initialized to point at default_lock. Thereafter lock and unlock
+operations performed by the mid level use the struct Scsi_Host::host_lock
+pointer. Previously drivers could override the host_lock pointer but
+this is not allowed anymore.
+
Autosense
=========
=======
The following people have contributed to this document:
Mike Anderson <andmike at us dot ibm dot com>
- James Bottomley <James dot Bottomley at steeleye dot com>
+ James Bottomley <James dot Bottomley at hansenpartnership dot com>
Patrick Mansfield <patmans at us dot ibm dot com>
Christoph Hellwig <hch at infradead dot org>
Doug Ledford <dledford at redhat dot com>
Andries Brouwer <Andries dot Brouwer at cwi dot nl>
- Randy Dunlap <rddunlap at osdl dot org>
+ Randy Dunlap <rdunlap at xenotime dot net>
Alan Stern <stern at rowland dot harvard dot edu>
git://ftp.safe.ca / safe / jmp / linux-2.6 / blobdiff