diff options
Diffstat (limited to 'Documentation/scsi')
| -rw-r--r-- | Documentation/scsi/scsi_mid_low_api.txt | 122 |
1 files changed, 1 insertions, 121 deletions
diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 2c31d9ee6776..177c031763c0 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -114,9 +114,7 @@ called "xxx" could be defined as "static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }" ** the scsi_host_alloc() function is a replacement for the rather vaguely -named scsi_register() function in most situations. The scsi_register() -and scsi_unregister() functions remain to support legacy LLDs that use -the passive initialization model. +named scsi_register() function in most situations. Hotplug initialization model @@ -228,79 +226,6 @@ slave_configure() callbacks). Such instances are "owned" by the mid-level. struct scsi_device instances are freed after slave_destroy(). -Passive initialization model -============================ -These older LLDs include a file called "scsi_module.c" [yes the ".c" is a -little surprising] in their source code. For that file to work an -instance of struct scsi_host_template with the name "driver_template" -needs to be defined. Here is a typical code sequence used in this model: - static struct scsi_host_template driver_template = { - ... - }; - #include "scsi_module.c" - -The scsi_module.c file contains two functions: - - init_this_scsi_driver() which is executed when the LLD is - initialized (i.e. boot time or module load time) - - exit_this_scsi_driver() which is executed when the LLD is shut - down (i.e. module unload time) -Note: since these functions are tagged with __init and __exit qualifiers -an LLD should not call them explicitly (since the kernel does that). - -Here is an example of an initialization sequence when two hosts are -detected (so detect() returns 2) and the SCSI bus scan on each host -finds 1 SCSI device (and a second device does not respond). - -LLD mid level LLD -===----------------------=========-----------------===------ -init_this_scsi_driver() ----+ - | - detect() -----------------+ - | | - | scsi_register() - | scsi_register() - | - slave_alloc() - slave_configure() --> scsi_change_queue_depth() - slave_alloc() *** - slave_destroy() *** - | - slave_alloc() - slave_configure() - slave_alloc() *** - slave_destroy() *** ------------------------------------------------------------- - -The mid level invokes scsi_change_queue_depth() with "cmd_per_lun" for that -host as the queue length. These settings can be overridden by a -slave_configure() supplied by the LLD. - -*** For scsi devices that the mid level tries to scan but do not - respond, a slave_alloc(), slave_destroy() pair is called. - -Here is an LLD shutdown sequence: - -LLD mid level LLD -===----------------------=========-----------------===------ -exit_this_scsi_driver() ----+ - | - slave_destroy() - release() --> scsi_unregister() - | - slave_destroy() - release() --> scsi_unregister() ------------------------------------------------------------- - -An LLD need not define slave_destroy() (i.e. it is optional). - -The shortcoming of the "passive initialization model" is that host -registration and de-registration are (typically) tied to LLD initialization -and shutdown. Once the LLD is initialized then a new host that appears -(e.g. via hotplugging) cannot easily be added without a redundant -driver shutdown and re-initialization. It may be possible to write an LLD -that uses both initialization models. - - Reference Counting ================== The Scsi_Host structure has had reference counting infrastructure added. @@ -738,7 +663,6 @@ 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 @@ -748,7 +672,6 @@ Summary: 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 @@ -785,28 +708,6 @@ Details: /** - * 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 * @@ -1074,27 +975,6 @@ Details: /** - * release - release all resources associated with given host - * @shp: host to be released. - * - * Return value ignored (could soon be a function returning void). - * - * Locks: none held - * - * Calling context: process - * - * Notes: Invoked from scsi_module.c's exit_this_scsi_driver(). - * LLD's implementation of this function should call - * scsi_unregister(shp) prior to returning. - * Only needed for old-style host templates. - * - * Defined in: LLD (required in "passive initialization model", - * should not be defined in hotplug model) - **/ - int release(struct Scsi_Host * shp) - - -/** * 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) |