Lines Matching +full:fine +full:- +full:grained
1 .. SPDX-License-Identifier: GPL-2.0
14 [1-1] struct scsi_cmnd
15 [1-2] How do scmd's get completed?
16 [1-2-1] Completing a scmd w/ scsi_done
17 [1-2-2] Completing a scmd w/ timeout
18 [1-3] How EH takes over
20 [2-1] EH through fine-grained callbacks
21 [2-1-1] Overview
22 [2-1-2] Flow of scmds through EH
23 [2-1-3] Flow of control
24 [2-2] EH through transportt->eh_strategy_handler()
25 [2-2-1] Pre transportt->eh_strategy_handler() SCSI midlayer conditions
26 [2-2-2] Post transportt->eh_strategy_handler() SCSI midlayer conditions
27 [2-2-3] Things to consider
34 --------------------
38 scmd->list and scmd->eh_entry. The former is used for free list or
39 per-device allocated scmd list and not of much interest to this EH
41 otherwise stated scmds are always linked using scmd->eh_entry in this
46 --------------------------------
50 invoking hostt->queuecommand() or the block layer will time it out.
56 For all non-EH commands, scsi_done() is the completion callback. It
62 looks at the scmd->result value and sense data to determine what to do
65 - SUCCESS
75 - NEEDS_RETRY
77 - ADD_TO_MLQUEUE
81 - otherwise
84 [1-3] for details of this function.
92 1. invokes optional hostt->eh_timed_out() callback. Return value can
95 - SCSI_EH_RESET_TIMER
99 - SCSI_EH_NOT_HANDLED
103 - SCSI_EH_DONE
107 issue a retry scmd->allowed + 1 times. Asynchronous aborts are not invoked
114 command. See [1-4] for more information.
117 -------------------------------
125 See [1-4] for more information.
128 ---------------------
132 1. Links scmd->eh_entry to shost->eh_cmd_q
134 2. Sets SHOST_RECOVERY bit in shost->shost_state
136 3. Increments shost->host_failed
138 4. Wakes up SCSI EH thread if shost->host_busy == shost->host_failed
140 As can be seen above, once any scmd is added to shost->eh_cmd_q,
144 time out and get added to shost->eh_cmd_q.
146 If all scmds either complete or fail, the number of in-flight scmds
147 becomes equal to the number of failed scmds - i.e. shost->host_busy ==
148 shost->host_failed. This wakes up SCSI EH thread. So, once woken up,
149 SCSI EH thread can expect that all in-flight commands have failed and
150 are linked on shost->eh_cmd_q.
155 has timed out, unless hostt->eh_timed_out() made lower layers forget
161 We'll talk about how SCSI EH takes actions to abort - make LLDD
162 forget about - timed out scmds later.
171 - Fine-grained EH callbacks
172 LLDD can implement fine-grained EH callbacks and let SCSI
174 This will be discussed further in [2-1].
176 - eh_strategy_handler() callback
179 performs during recovery. This will be discussed in [2-2].
188 3. Wakes up waiters on shost->host_wait. This occurs if someone
196 2.1 EH through fine-grained callbacks
197 -------------------------------------
203 of driving error handling. EH's goals are two - make LLDD, host and
211 others are performed by invoking one of the following fine-grained
222 Higher-severity actions are taken only when lower-severity actions
224 highest-severity action means EH failure and results in offlining of
229 - Recovery actions are performed on failed scmds on the to do list,
237 - Higher severity actions are taken iff eh_work_q is not empty after
240 - EH reuses failed scmds to issue commands for recovery. For
241 timed-out scmds, SCSI EH ensures that LLDD forgets about a scmd
247 either retry or error-finish (notify upper layer of failure) recovered
251 EH), REQ_FAILFAST is not set and ++scmd->retries is less than
252 scmd->allowed.
262 - add scmd to shost->eh_cmd_q
263 - set SHOST_RECOVERY
264 - shost->host_failed++
266 :LOCKING: shost->host_lock
270 :ACTION: move all scmds to EH's local eh_work_q. shost->eh_cmd_q
273 :LOCKING: shost->host_lock (not strictly necessary, just for
278 :ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd
280 - scsi_setup_cmd_retry()
281 - move from local eh_work_q to local eh_done_q
295 - scmd is removed from eh_done_q and scmd->eh_entry is cleared
296 - if retry is necessary, scmd is requeued using
298 - otherwise, scsi_finish_command() is invoked for scmd
299 - zero shost->host_failed
307 EH through fine-grained callbacks start from scsi_unjam_host().
311 1. Lock shost->host_lock, splice_init shost->eh_cmd_q into local
312 eh_work_q and unlock host_lock. Note that shost->eh_cmd_q is
319 This action is taken for each error-completed
326 Note that if autosense is not supported, scmd->sense_buffer
327 contains invalid sense data when error-completing the scmd
335 causes higher-severity recovery to be taken for the scmd.
339 - SUCCESS
340 scmd->retries is set to scmd->allowed preventing
344 - NEEDS_RETRY
347 - otherwise
356 hostt->eh_abort_handler() is invoked for each scmd. The
363 higher-severity actions.
388 as we explicitly choose error-completed scmds, it is known
393 all failed scmds on the sdev are EH-finished with
396 *NOTE* If hostt->eh_abort_handler() isn't implemented or
399 scmds. Yet, this function EH-finish all scmds on the sdev
409 instead of issuing STU, hostt->eh_device_reset_handler()
412 to choose error-completed scmds.
418 hostt->eh_bus_reset_handler() is invoked for each channel
421 EH-finished.
427 This is the last resort. hostt->eh_host_reset_handler()
429 all ready or offline sdevs on the host are EH-finished.
436 and EH-finish the scmds.
448 2.2 EH through transportt->eh_strategy_handler()
449 ------------------------------------------------
451 transportt->eh_strategy_handler() is invoked in the place of
456 SCSI midlayer. IOW, of the steps described in [2-1-2], all steps
460 2.2.1 Pre transportt->eh_strategy_handler() SCSI midlayer conditions
465 - Each failed scmd's eh_flags field is set appropriately.
467 - Each failed scmd is linked on scmd->eh_cmd_q by scmd->eh_entry.
469 - SHOST_RECOVERY is set.
471 - shost->host_failed == shost->host_busy
474 2.2.2 Post transportt->eh_strategy_handler() SCSI midlayer conditions
479 - shost->host_failed is zero.
481 - Each scmd is in such a state that scsi_setup_cmd_retry() on the
484 - shost->eh_cmd_q is cleared.
486 - Each scmd->eh_entry is cleared.
488 - Either scsi_queue_insert() or scsi_finish_command() is called on
489 each scmd. Note that the handler is free to use scmd->retries and
490 ->allowed to limit the number of retries.
496 - Know that timed out scmds are still active on lower layers. Make
500 - For consistency, when accessing/modifying shost data structure,
501 grab shost->host_lock.
503 - On completion, each failed sdev must have forgotten about all
506 - On completion, each failed sdev must be ready for new commands or