X-Git-Url: http://pilppa.org/gitweb/gitweb.cgi?a=blobdiff_plain;f=Documentation%2Fscsi%2Fscsi_mid_low_api.txt;h=6f70f2b9327e1f0db7bc05bdbf2d6ce3b2fcbdcf;hb=c6686ff9df086f9473663c2e61c1173c56788b2e;hp=da176c95d0fb62618ff5c3684f5768a935f9dd0f;hpb=54522b6613a03807f057fd567794a31267ef85cb;p=linux-2.6-omap-h63xx.git diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index da176c95d0f..6f70f2b9327 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -150,7 +150,8 @@ scsi devices of which only the first 2 respond: LLD mid level LLD ===-------------------=========--------------------===------ scsi_host_alloc() --> -scsi_add_host() --------+ +scsi_add_host() ----> +scsi_scan_host() -------+ | slave_alloc() slave_configure() --> scsi_adjust_queue_depth() @@ -196,7 +197,7 @@ 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_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: @@ -346,7 +347,7 @@ 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_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 @@ -372,14 +373,11 @@ 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 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) @@ -388,7 +386,7 @@ Summary: 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()] @@ -428,10 +426,10 @@ void scsi_activate_tcq(struct scsi_device *sdev, int depth) * 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 @@ -442,7 +440,7 @@ struct scsi_device * scsi_add_device(struct Scsi_Host *shost, /** - * 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 * @@ -451,34 +449,17 @@ struct scsi_device * scsi_add_device(struct Scsi_Host *shost, * 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 **/ int scsi_add_host(struct Scsi_Host *shost, struct device * dev) -/** - * 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 @@ -506,20 +487,6 @@ void scsi_adjust_queue_depth(struct scsi_device * sdev, int tagged, int tags) -/** - * 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 @@ -566,24 +533,6 @@ void scsi_block_requests(struct Scsi_Host * shost) void scsi_deactivate_tcq(struct scsi_device *sdev, int depth) -/** - * 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. @@ -601,7 +550,7 @@ int scsi_delete_timer(struct scsi_cmnd *scmd) * 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 . **/ @@ -741,17 +690,16 @@ void scsi_report_bus_reset(struct Scsi_Host * shost, int channel) /** - * 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) /** @@ -774,7 +722,7 @@ void scsi_set_device(struct Scsi_Host * shost, struct device * dev) * * 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) /** @@ -841,7 +789,6 @@ Summary: 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} @@ -1006,24 +953,6 @@ Details: int eh_host_reset_handler(struct scsi_cmnd * scp) -/** - * 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 @@ -1422,17 +1351,11 @@ Locks 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 ========= @@ -1489,7 +1412,7 @@ The following people have contributed to this document: Christoph Hellwig Doug Ledford Andries Brouwer - Randy Dunlap + Randy Dunlap Alan Stern