^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) SCSI EH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) This document describes SCSI midlayer error handling infrastructure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Please refer to Documentation/scsi/scsi_mid_low_api.rst for more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) information regarding SCSI midlayer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) .. TABLE OF CONTENTS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) [1] How SCSI commands travel through the midlayer and to EH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) [1-1] struct scsi_cmnd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) [1-2] How do scmd's get completed?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) [1-2-1] Completing a scmd w/ scsi_done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) [1-2-2] Completing a scmd w/ timeout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) [1-3] How EH takes over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) [2] How SCSI EH works
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) [2-1] EH through fine-grained callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) [2-1-1] Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) [2-1-2] Flow of scmds through EH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) [2-1-3] Flow of control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) [2-2] EH through transportt->eh_strategy_handler()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) [2-2-1] Pre transportt->eh_strategy_handler() SCSI midlayer conditions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) [2-2-2] Post transportt->eh_strategy_handler() SCSI midlayer conditions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) [2-2-3] Things to consider
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) 1. How SCSI commands travel through the midlayer and to EH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) ==========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) 1.1 struct scsi_cmnd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Each SCSI command is represented with struct scsi_cmnd (== scmd). A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) scmd has two list_head's to link itself into lists. The two are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) scmd->list and scmd->eh_entry. The former is used for free list or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) per-device allocated scmd list and not of much interest to this EH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) discussion. The latter is used for completion and EH lists and unless
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) otherwise stated scmds are always linked using scmd->eh_entry in this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) discussion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) 1.2 How do scmd's get completed?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) Once LLDD gets hold of a scmd, either the LLDD will complete the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) command by calling scsi_done callback passed from midlayer when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) invoking hostt->queuecommand() or the block layer will time it out.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 1.2.1 Completing a scmd w/ scsi_done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) For all non-EH commands, scsi_done() is the completion callback. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) just calls blk_complete_request() to delete the block layer timer and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) raise SCSI_SOFTIRQ
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) SCSI_SOFTIRQ handler scsi_softirq calls scsi_decide_disposition() to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) determine what to do with the command. scsi_decide_disposition()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) looks at the scmd->result value and sense data to determine what to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) with the command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) - SUCCESS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) scsi_finish_command() is invoked for the command. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) function does some maintenance chores and then calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) scsi_io_completion() to finish the I/O.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) scsi_io_completion() then notifies the block layer on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) the completed request by calling blk_end_request and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) friends or figures out what to do with the remainder
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) of the data in case of an error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) - NEEDS_RETRY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) - ADD_TO_MLQUEUE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) scmd is requeued to blk queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) - otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) scsi_eh_scmd_add(scmd) is invoked for the command. See
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) [1-3] for details of this function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) 1.2.2 Completing a scmd w/ timeout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) The timeout handler is scsi_times_out(). When a timeout occurs, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) 1. invokes optional hostt->eh_timed_out() callback. Return value can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) be one of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) - BLK_EH_RESET_TIMER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) This indicates that more time is required to finish the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) command. Timer is restarted. This action is counted as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) retry and only allowed scmd->allowed + 1(!) times. Once the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) limit is reached, action for BLK_EH_DONE is taken instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) - BLK_EH_DONE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) eh_timed_out() callback did not handle the command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) Step #2 is taken.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) 2. scsi_abort_command() is invoked to schedule an asynchrous abort.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) Asynchronous abort are not invoked for commands which the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) SCSI_EH_ABORT_SCHEDULED flag is set (this indicates that the command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) already had been aborted once, and this is a retry which failed),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) or when the EH deadline is expired. In these case Step #3 is taken.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 3. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) command. See [1-4] for more information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) 1.3 Asynchronous command aborts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) After a timeout occurs a command abort is scheduled from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) scsi_abort_command(). If the abort is successful the command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) will either be retried (if the number of retries is not exhausted)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) or terminated with DID_TIME_OUT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) Otherwise scsi_eh_scmd_add() is invoked for the command.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) See [1-4] for more information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 1.4 How EH takes over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) scmds enter EH via scsi_eh_scmd_add(), which does the following.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 1. Links scmd->eh_entry to shost->eh_cmd_q
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 2. Sets SHOST_RECOVERY bit in shost->shost_state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 3. Increments shost->host_failed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 4. Wakes up SCSI EH thread if shost->host_busy == shost->host_failed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) As can be seen above, once any scmd is added to shost->eh_cmd_q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) SHOST_RECOVERY shost_state bit is turned on. This prevents any new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) scmd to be issued from blk queue to the host; eventually, all scmds on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) the host either complete normally, fail and get added to eh_cmd_q, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) time out and get added to shost->eh_cmd_q.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) If all scmds either complete or fail, the number of in-flight scmds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) becomes equal to the number of failed scmds - i.e. shost->host_busy ==
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) shost->host_failed. This wakes up SCSI EH thread. So, once woken up,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) SCSI EH thread can expect that all in-flight commands have failed and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) are linked on shost->eh_cmd_q.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) Note that this does not mean lower layers are quiescent. If a LLDD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) completed a scmd with error status, the LLDD and lower layers are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) assumed to forget about the scmd at that point. However, if a scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) has timed out, unless hostt->eh_timed_out() made lower layers forget
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) about the scmd, which currently no LLDD does, the command is still
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) active as long as lower layers are concerned and completion could
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) occur at any time. Of course, all such completions are ignored as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) timer has already expired.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) We'll talk about how SCSI EH takes actions to abort - make LLDD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) forget about - timed out scmds later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 2. How SCSI EH works
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) LLDD's can implement SCSI EH actions in one of the following two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) ways.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) - Fine-grained EH callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) LLDD can implement fine-grained EH callbacks and let SCSI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) midlayer drive error handling and call appropriate callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) This will be discussed further in [2-1].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) - eh_strategy_handler() callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) This is one big callback which should perform whole error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) handling. As such, it should do all chores the SCSI midlayer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) performs during recovery. This will be discussed in [2-2].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) Once recovery is complete, SCSI EH resumes normal operation by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) calling scsi_restart_operations(), which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) 1. Checks if door locking is needed and locks door.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) 2. Clears SHOST_RECOVERY shost_state bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) 3. Wakes up waiters on shost->host_wait. This occurs if someone
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) calls scsi_block_when_processing_errors() on the host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) (*QUESTION* why is it needed? All operations will be blocked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) anyway after it reaches blk queue.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) 4. Kicks queues in all devices on the host in the asses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) 2.1 EH through fine-grained callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) -------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 2.1.1 Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) ^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) If eh_strategy_handler() is not present, SCSI midlayer takes charge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) of driving error handling. EH's goals are two - make LLDD, host and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) device forget about timed out scmds and make them ready for new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) commands. A scmd is said to be recovered if the scmd is forgotten by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) lower layers and lower layers are ready to process or fail the scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) To achieve these goals, EH performs recovery actions with increasing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) severity. Some actions are performed by issuing SCSI commands and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) others are performed by invoking one of the following fine-grained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) hostt EH callbacks. Callbacks may be omitted and omitted ones are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) considered to fail always.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) int (* eh_abort_handler)(struct scsi_cmnd *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) int (* eh_device_reset_handler)(struct scsi_cmnd *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) int (* eh_bus_reset_handler)(struct scsi_cmnd *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) int (* eh_host_reset_handler)(struct scsi_cmnd *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) Higher-severity actions are taken only when lower-severity actions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) cannot recover some of failed scmds. Also, note that failure of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) highest-severity action means EH failure and results in offlining of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) all unrecovered devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) During recovery, the following rules are followed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) - Recovery actions are performed on failed scmds on the to do list,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) eh_work_q. If a recovery action succeeds for a scmd, recovered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) scmds are removed from eh_work_q.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Note that single recovery action on a scmd can recover multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) scmds. e.g. resetting a device recovers all failed scmds on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) - Higher severity actions are taken iff eh_work_q is not empty after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) lower severity actions are complete.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) - EH reuses failed scmds to issue commands for recovery. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) timed-out scmds, SCSI EH ensures that LLDD forgets about a scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) before reusing it for EH commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) When a scmd is recovered, the scmd is moved from eh_work_q to EH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) local eh_done_q using scsi_eh_finish_cmd(). After all scmds are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) recovered (eh_work_q is empty), scsi_eh_flush_done_q() is invoked to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) either retry or error-finish (notify upper layer of failure) recovered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) scmds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) scmds are retried iff its sdev is still online (not offlined during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) EH), REQ_FAILFAST is not set and ++scmd->retries is less than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) scmd->allowed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) 2.1.2 Flow of scmds through EH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) 1. Error completion / time out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) :ACTION: scsi_eh_scmd_add() is invoked for scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) - add scmd to shost->eh_cmd_q
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) - set SHOST_RECOVERY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) - shost->host_failed++
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) :LOCKING: shost->host_lock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) 2. EH starts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) :ACTION: move all scmds to EH's local eh_work_q. shost->eh_cmd_q
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) is cleared.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) :LOCKING: shost->host_lock (not strictly necessary, just for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) consistency)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) 3. scmd recovered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) :ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) - scsi_setup_cmd_retry()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) - move from local eh_work_q to local eh_done_q
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) :LOCKING: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) :CONCURRENCY: at most one thread per separate eh_work_q to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) keep queue manipulation lockless
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 4. EH completes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) :ACTION: scsi_eh_flush_done_q() retries scmds or notifies upper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) layer of failure. May be called concurrently but must have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) a no more than one thread per separate eh_work_q to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) manipulate the queue locklessly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) - scmd is removed from eh_done_q and scmd->eh_entry is cleared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) - if retry is necessary, scmd is requeued using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) scsi_queue_insert()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) - otherwise, scsi_finish_command() is invoked for scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) - zero shost->host_failed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) :LOCKING: queue or finish function performs appropriate locking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) 2.1.3 Flow of control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) ^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) EH through fine-grained callbacks start from scsi_unjam_host().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) ``scsi_unjam_host``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) 1. Lock shost->host_lock, splice_init shost->eh_cmd_q into local
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) eh_work_q and unlock host_lock. Note that shost->eh_cmd_q is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) cleared by this action.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) 2. Invoke scsi_eh_get_sense.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) ``scsi_eh_get_sense``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) This action is taken for each error-completed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) (!SCSI_EH_CANCEL_CMD) commands without valid sense data. Most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) SCSI transports/LLDDs automatically acquire sense data on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) command failures (autosense). Autosense is recommended for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) performance reasons and as sense information could get out of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) sync between occurrence of CHECK CONDITION and this action.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) Note that if autosense is not supported, scmd->sense_buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) contains invalid sense data when error-completing the scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) with scsi_done(). scsi_decide_disposition() always returns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) FAILED in such cases thus invoking SCSI EH. When the scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) reaches here, sense data is acquired and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) scsi_decide_disposition() is called again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) 1. Invoke scsi_request_sense() which issues REQUEST_SENSE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) command. If fails, no action. Note that taking no action
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) causes higher-severity recovery to be taken for the scmd.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) 2. Invoke scsi_decide_disposition() on the scmd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) - SUCCESS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) scmd->retries is set to scmd->allowed preventing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) scsi_eh_flush_done_q() from retrying the scmd and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) scsi_eh_finish_cmd() is invoked.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) - NEEDS_RETRY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) scsi_eh_finish_cmd() invoked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) - otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) No action.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) 3. If !list_empty(&eh_work_q), invoke scsi_eh_abort_cmds().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) ``scsi_eh_abort_cmds``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) This action is taken for each timed out command when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) no_async_abort is enabled in the host template.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) hostt->eh_abort_handler() is invoked for each scmd. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) handler returns SUCCESS if it has succeeded to make LLDD and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) all related hardware forget about the scmd.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) If a timedout scmd is successfully aborted and the sdev is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) either offline or ready, scsi_eh_finish_cmd() is invoked for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) the scmd. Otherwise, the scmd is left in eh_work_q for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) higher-severity actions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) Note that both offline and ready status mean that the sdev is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) ready to process new scmds, where processing also implies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) immediate failing; thus, if a sdev is in one of the two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) states, no further recovery action is needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) Device readiness is tested using scsi_eh_tur() which issues
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) TEST_UNIT_READY command. Note that the scmd must have been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) aborted successfully before reusing it for TEST_UNIT_READY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) 4. If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) ``scsi_eh_ready_devs``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) This function takes four increasingly more severe measures to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) make failed sdevs ready for new commands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) 1. Invoke scsi_eh_stu()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) ``scsi_eh_stu``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) For each sdev which has failed scmds with valid sense data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) of which scsi_check_sense()'s verdict is FAILED,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) START_STOP_UNIT command is issued w/ start=1. Note that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) as we explicitly choose error-completed scmds, it is known
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) that lower layers have forgotten about the scmd and we can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) reuse it for STU.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) If STU succeeds and the sdev is either offline or ready,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) all failed scmds on the sdev are EH-finished with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) scsi_eh_finish_cmd().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) *NOTE* If hostt->eh_abort_handler() isn't implemented or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) failed, we may still have timed out scmds at this point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) and STU doesn't make lower layers forget about those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) scmds. Yet, this function EH-finish all scmds on the sdev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) if STU succeeds leaving lower layers in an inconsistent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) state. It seems that STU action should be taken only when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) a sdev has no timed out scmd.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) 2. If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) ``scsi_eh_bus_device_reset``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) This action is very similar to scsi_eh_stu() except that,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) instead of issuing STU, hostt->eh_device_reset_handler()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) is used. Also, as we're not issuing SCSI commands and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) resetting clears all scmds on the sdev, there is no need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) to choose error-completed scmds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) 3. If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) ``scsi_eh_bus_reset``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) hostt->eh_bus_reset_handler() is invoked for each channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) with failed scmds. If bus reset succeeds, all failed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) scmds on all ready or offline sdevs on the channel are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) EH-finished.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) 4. If !list_empty(&eh_work_q), invoke scsi_eh_host_reset()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) ``scsi_eh_host_reset``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) This is the last resort. hostt->eh_host_reset_handler()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) is invoked. If host reset succeeds, all failed scmds on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) all ready or offline sdevs on the host are EH-finished.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) 5. If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) ``scsi_eh_offline_sdevs``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) Take all sdevs which still have unrecovered scmds offline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) and EH-finish the scmds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) 5. Invoke scsi_eh_flush_done_q().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) ``scsi_eh_flush_done_q``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) At this point all scmds are recovered (or given up) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) put on eh_done_q by scsi_eh_finish_cmd(). This function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) flushes eh_done_q by either retrying or notifying upper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) layer of failure of the scmds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) 2.2 EH through transportt->eh_strategy_handler()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) ------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) transportt->eh_strategy_handler() is invoked in the place of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) scsi_unjam_host() and it is responsible for whole recovery process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) On completion, the handler should have made lower layers forget about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) all failed scmds and either ready for new commands or offline. Also,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) it should perform SCSI EH maintenance chores to maintain integrity of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) SCSI midlayer. IOW, of the steps described in [2-1-2], all steps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) except for #1 must be implemented by eh_strategy_handler().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) 2.2.1 Pre transportt->eh_strategy_handler() SCSI midlayer conditions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) The following conditions are true on entry to the handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) - Each failed scmd's eh_flags field is set appropriately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) - Each failed scmd is linked on scmd->eh_cmd_q by scmd->eh_entry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) - SHOST_RECOVERY is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) - shost->host_failed == shost->host_busy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) 2.2.2 Post transportt->eh_strategy_handler() SCSI midlayer conditions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) The following conditions must be true on exit from the handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) - shost->host_failed is zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) - Each scmd is in such a state that scsi_setup_cmd_retry() on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) scmd doesn't make any difference.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) - shost->eh_cmd_q is cleared.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) - Each scmd->eh_entry is cleared.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) - Either scsi_queue_insert() or scsi_finish_command() is called on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) each scmd. Note that the handler is free to use scmd->retries and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) ->allowed to limit the number of retries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) 2.2.3 Things to consider
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) ^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) - Know that timed out scmds are still active on lower layers. Make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) lower layers forget about them before doing anything else with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) those scmds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) - For consistency, when accessing/modifying shost data structure,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) grab shost->host_lock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) - On completion, each failed sdev must have forgotten about all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) active scmds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) - On completion, each failed sdev must be ready for new commands or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) offline.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) Tejun Heo
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) htejun@gmail.com
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) 11th September 2005
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags