|author||Hannes Reinecke <firstname.lastname@example.org>||2013-11-11 13:44:57 +0100|
|committer||James Bottomley <JBottomley@Parallels.com>||2013-12-19 07:39:03 -0800|
[SCSI] Update documentation
The documentation has gone out-of-sync, so update it to the current status. Signed-off-by: Hannes Reinecke <email@example.com> Signed-off-by: James Bottomley <JBottomley@Parallels.com>
Diffstat (limited to 'Documentation/scsi')
2 files changed, 46 insertions, 32 deletions
diff --git a/Documentation/scsi/scsi_eh.txt b/Documentation/scsi/scsi_eh.txt
index 6ff16b620d84..a0c85110a07e 100644
@@ -42,20 +42,14 @@ discussion.
Once LLDD gets hold of a scmd, either the LLDD will complete the
command by calling scsi_done callback passed from midlayer when
-invoking hostt->queuecommand() or SCSI midlayer will time it out.
+invoking hostt->queuecommand() or the block layer will time it out.
[1-2-1] Completing a scmd w/ scsi_done
For all non-EH commands, scsi_done() is the completion callback. It
-does the following.
- 1. Delete timeout timer. If it fails, it means that timeout timer
- has expired and is going to finish the command. Just return.
- 2. Link scmd to per-cpu scsi_done_q using scmd->en_entry
- 3. Raise SCSI_SOFTIRQ
+just calls blk_complete_request() to delete the block layer timer and
SCSI_SOFTIRQ handler scsi_softirq calls scsi_decide_disposition() to
determine what to do with the command. scsi_decide_disposition()
@@ -64,10 +58,12 @@ with the command.
scsi_finish_command() is invoked for the command. The
- function does some maintenance choirs and notify completion by
- calling scmd->done() callback, which, for fs requests, would
- be HLD completion callback - sd:sd_rw_intr, sr:rw_intr,
+ function does some maintenance chores and then calls
+ scsi_io_completion() to finish the I/O.
+ scsi_io_completion() then notifies the block layer on
+ the completed request by calling blk_end_request and
+ friends or figures out what to do with the remainder
+ of the data in case of an error.
@@ -86,33 +82,45 @@ function
1. invokes optional hostt->eh_timed_out() callback. Return value can
be one of
- - EH_HANDLED
- This indicates that eh_timed_out() dealt with the timeout. The
- scmd is passed to __scsi_done() and thus linked into per-cpu
- scsi_done_q. Normal command completion described in [1-2-1]
+ - BLK_EH_HANDLED
+ This indicates that eh_timed_out() dealt with the timeout.
+ The command is passed back to the block layer and completed
+ via __blk_complete_requests().
+ *NOTE* After returning BLK_EH_HANDLED the SCSI layer is
+ assumed to be finished with the command, and no other
+ functions from the SCSI layer will be called. So this
+ should typically only be returned if the eh_timed_out()
+ handler raced with normal completion.
- - EH_RESET_TIMER
+ - BLK_EH_RESET_TIMER
This indicates that more time is required to finish the
command. Timer is restarted. This action is counted as a
retry and only allowed scmd->allowed + 1(!) times. Once the
- limit is reached, action for EH_NOT_HANDLED is taken instead.
+ limit is reached, action for BLK_EH_NOT_HANDLED is taken instead.
- *NOTE* This action is racy as the LLDD could finish the scmd
- after the timeout has expired but before it's added back. In
- such cases, scsi_done() would think that timeout has occurred
- and return without doing anything. We lose completion and the
- command will time out again.
- - EH_NOT_HANDLED
- This is the same as when eh_timed_out() callback doesn't exist.
+ - BLK_EH_NOT_HANDLED
+ eh_timed_out() callback did not handle the command.
Step #2 is taken.
+ 2. If the host supports asynchronous completion (as indicated by the
+ no_async_abort setting in the host template) scsi_abort_command()
+ is invoked to schedule an asynchrous abort. If that fails
+ Step #3 is taken.
2. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the
command. See [1-3] for more information.
+[1-3] Asynchronous command aborts
+ After a timeout occurs a command abort is scheduled from
+ scsi_abort_command(). If the abort is successful the command
+ will either be retried (if the number of retries is not exhausted)
+ or terminated with DID_TIME_OUT.
+ Otherwise scsi_eh_scmd_add() is invoked for the command.
+ See [1-4] for more information.
-[1-3] How EH takes over
+[1-4] How EH takes over
scmds enter EH via scsi_eh_scmd_add(), which does the following.
@@ -320,7 +328,8 @@ scmd->allowed.
- This action is taken for each timed out command.
+ This action is taken for each timed out command when
+ no_async_abort is enabled in the host template.
hostt->eh_abort_handler() is invoked for each scmd. The
handler returns SUCCESS if it has succeeded to make LLDD and
all related hardware forget about the scmd.
diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt
index 2b06aba4fa0f..d6a9bdeee7f2 100644
@@ -882,8 +882,11 @@ Details:
* Calling context: kernel thread
- * Notes: Invoked from scsi_eh thread. No other commands will be
- * queued on current host during eh.
+ * 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
@@ -1257,6 +1260,8 @@ of interest:
use_clustering - 1=>SCSI commands in mid level's queue can be merged,
0=>disallow SCSI command merging
+ no_async_abort - 1=>Asynchronous aborts are not supported
+ 0=>Timed-out commands will be aborted asynchronously
hostt - pointer to driver's struct scsi_host_template from which
this struct Scsi_Host instance was spawned
hostt->proc_name - name of LLD. This is the driver name that sysfs uses