sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget /translations/zh_CN/scsi/scsi_ehmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/zh_TW/scsi/scsi_ehmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/it_IT/scsi/scsi_ehmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/ja_JP/scsi/scsi_ehmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/ko_KR/scsi/scsi_ehmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget /translations/sp_SP/scsi/scsi_ehmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhh:/var/lib/git/docbuild/linux/Documentation/scsi/scsi_eh.rsthKubhsection)}(hhh](htitle)}(hSCSI EHh]hSCSI EH}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThis document describes SCSI midlayer error handling infrastructure. Please refer to Documentation/scsi/scsi_mid_low_api.rst for more information regarding SCSI midlayer.h]hThis document describes SCSI midlayer error handling infrastructure. Please refer to Documentation/scsi/scsi_mid_low_api.rst for more information regarding SCSI midlayer.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXTABLE OF CONTENTS [1] How SCSI commands travel through the midlayer and to EH [1-1] struct scsi_cmnd [1-2] How do scmd's get completed? [1-2-1] Completing a scmd w/ scsi_done [1-2-2] Completing a scmd w/ timeout [1-3] How EH takes over [2] How SCSI EH works [2-1] EH through fine-grained callbacks [2-1-1] Overview [2-1-2] Flow of scmds through EH [2-1-3] Flow of control [2-2] EH through transportt->eh_strategy_handler() [2-2-1] Pre transportt->eh_strategy_handler() SCSI midlayer conditions [2-2-2] Post transportt->eh_strategy_handler() SCSI midlayer conditions [2-2-3] Things to considerh]hXTABLE OF CONTENTS [1] How SCSI commands travel through the midlayer and to EH [1-1] struct scsi_cmnd [1-2] How do scmd's get completed? [1-2-1] Completing a scmd w/ scsi_done [1-2-2] Completing a scmd w/ timeout [1-3] How EH takes over [2] How SCSI EH works [2-1] EH through fine-grained callbacks [2-1-1] Overview [2-1-2] Flow of scmds through EH [2-1-3] Flow of control [2-2] EH through transportt->eh_strategy_handler() [2-2-1] Pre transportt->eh_strategy_handler() SCSI midlayer conditions [2-2-2] Post transportt->eh_strategy_handler() SCSI midlayer conditions [2-2-3] Things to consider}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhKubh)}(hhh](h)}(h:1. How SCSI commands travel through the midlayer and to EHh]h:1. How SCSI commands travel through the midlayer and to EH}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h1.1 struct scsi_cmndh]h1.1 struct scsi_cmnd}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK"ubh)}(hXEach SCSI command is represented with struct scsi_cmnd (== scmd). A scmd has two list_head's to link itself into lists. The two are scmd->list and scmd->eh_entry. The former is used for free list or per-device allocated scmd list and not of much interest to this EH discussion. The latter is used for completion and EH lists and unless otherwise stated scmds are always linked using scmd->eh_entry in this discussion.h]hXEach SCSI command is represented with struct scsi_cmnd (== scmd). A scmd has two list_head’s to link itself into lists. The two are scmd->list and scmd->eh_entry. The former is used for free list or per-device allocated scmd list and not of much interest to this EH discussion. The latter is used for completion and EH lists and unless otherwise stated scmds are always linked using scmd->eh_entry in this discussion.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK$hhhhubeh}(h]struct-scsi-cmndah ]h"]1.1 struct scsi_cmndah$]h&]uh1hhhhhhhhK"ubh)}(hhh](h)}(h 1.2 How do scmd's get completed?h]h"1.2 How do scmd’s get completed?}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK.ubh)}(hOnce 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 the block layer will time it out.h]hOnce 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 the block layer will time it out.}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK0hjhhubh)}(hhh](h)}(h$1.2.1 Completing a scmd w/ scsi_doneh]h$1.2.1 Completing a scmd w/ scsi_done}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>hhhhhK6ubh)}(hFor all non-EH commands, scsi_done() is the completion callback. It just calls blk_mq_complete_request() to delete the block layer timer and raise BLOCK_SOFTIRQ.h]hFor all non-EH commands, scsi_done() is the completion callback. It just calls blk_mq_complete_request() to delete the block layer timer and raise BLOCK_SOFTIRQ.}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK8hj>hhubh)}(hThe BLOCK_SOFTIRQ indirectly calls scsi_complete(), which calls scsi_decide_disposition() to determine what to do with the command. scsi_decide_disposition() looks at the scmd->result value and sense data to determine what to do with the command.h]hThe BLOCK_SOFTIRQ indirectly calls scsi_complete(), which calls scsi_decide_disposition() to determine what to do with the command. scsi_decide_disposition() looks at the scmd->result value and sense data to determine what to do with the command.}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubh block_quote)}(hXR- SUCCESS scsi_finish_command() is invoked for the command. The 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. - NEEDS_RETRY - ADD_TO_MLQUEUE scmd is requeued to blk queue. - otherwise scsi_eh_scmd_add(scmd) is invoked for the command. See [1-3] for details of this function. h]h bullet_list)}(hhh](h list_item)}(hXSUCCESS scsi_finish_command() is invoked for the command. The 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. h](h)}(hSUCCESSh]hSUCCESS}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKAhjxubjl)}(hXUscsi_finish_command() is invoked for the command. The 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. h]h)}(hXTscsi_finish_command() is invoked for the command. The 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.h]hXTscsi_finish_command() is invoked for the command. The 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKChjubah}(h]h ]h"]h$]h&]uh1jkhhhKChjxubeh}(h]h ]h"]h$]h&]uh1jvhjsubjw)}(h NEEDS_RETRY h]h)}(h NEEDS_RETRYh]h NEEDS_RETRY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKKhjubah}(h]h ]h"]h$]h&]uh1jvhjsubjw)}(h4ADD_TO_MLQUEUE scmd is requeued to blk queue. h](h)}(hADD_TO_MLQUEUEh]hADD_TO_MLQUEUE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKMhjubjl)}(hscmd is requeued to blk queue. h]h)}(hscmd is requeued to blk queue.h]hscmd is requeued to blk queue.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjubah}(h]h ]h"]h$]h&]uh1jkhhhKOhjubeh}(h]h ]h"]h$]h&]uh1jvhjsubjw)}(hrotherwise scsi_eh_scmd_add(scmd) is invoked for the command. See [1-3] for details of this function. h](h)}(h otherwiseh]h otherwise}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKQhjubjl)}(h]scsi_eh_scmd_add(scmd) is invoked for the command. See [1-3] for details of this function. h]h)}(h[scsi_eh_scmd_add(scmd) is invoked for the command. See [1-3] for details of this function.h]h[scsi_eh_scmd_add(scmd) is invoked for the command. See [1-3] for details of this function.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShjubah}(h]h ]h"]h$]h&]uh1jkhhhKShjubeh}(h]h ]h"]h$]h&]uh1jvhjsubeh}(h]h ]h"]h$]h&]bullet-uh1jqhhhKAhjmubah}(h]h ]h"]h$]h&]uh1jkhhhKAhj>hhubeh}(h]completing-a-scmd-w-scsi-doneah ]h"]$1.2.1 completing a scmd w/ scsi_doneah$]h&]uh1hhjhhhhhK6ubh)}(hhh](h)}(h"1.2.2 Completing a scmd w/ timeouth]h"1.2.2 Completing a scmd w/ timeout}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6hhhhhKXubh)}(hLThe timeout handler is scsi_timeout(). When a timeout occurs, this functionh]hLThe timeout handler is scsi_timeout(). When a timeout occurs, this function}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKZhj6hhubjl)}(hX1. invokes optional hostt->eh_timed_out() callback. Return value can be one of - SCSI_EH_RESET_TIMER This indicates that more time is required to finish the command. Timer is restarted. - SCSI_EH_NOT_HANDLED eh_timed_out() callback did not handle the command. Step #2 is taken. - SCSI_EH_DONE eh_timed_out() completed the command. 2. scsi_abort_command() is invoked to schedule an asynchronous abort which may issue a retry scmd->allowed + 1 times. Asynchronous aborts are not invoked for commands for which the SCSI_EH_ABORT_SCHEDULED flag is set (this indicates that the command already had been aborted once, and this is a retry which failed), when retries are exceeded, or when the EH deadline is expired. In these cases Step #3 is taken. 3. scsi_eh_scmd_add(scmd) is invoked for the command. See [1-4] for more information. h]henumerated_list)}(hhh](jw)}(hXainvokes optional hostt->eh_timed_out() callback. Return value can be one of - SCSI_EH_RESET_TIMER This indicates that more time is required to finish the command. Timer is restarted. - SCSI_EH_NOT_HANDLED eh_timed_out() callback did not handle the command. Step #2 is taken. - SCSI_EH_DONE eh_timed_out() completed the command. h](h)}(hLinvokes optional hostt->eh_timed_out() callback. Return value can be one ofh]hLinvokes optional hostt->eh_timed_out() callback. Return value can be one of}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hj^ubjr)}(hhh](jw)}(hnSCSI_EH_RESET_TIMER This indicates that more time is required to finish the command. Timer is restarted. h]hdefinition_list)}(hhh]hdefinition_list_item)}(hjSCSI_EH_RESET_TIMER This indicates that more time is required to finish the command. Timer is restarted. h](hterm)}(hSCSI_EH_RESET_TIMERh]hSCSI_EH_RESET_TIMER}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKahj~ubh definition)}(hhh]h)}(hUThis indicates that more time is required to finish the command. Timer is restarted.h]hUThis indicates that more time is required to finish the command. Timer is restarted.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK`hjubah}(h]h ]h"]h$]h&]uh1jhj~ubeh}(h]h ]h"]h$]h&]uh1j|hhhKahjyubah}(h]h ]h"]h$]h&]uh1jwhjsubah}(h]h ]h"]h$]h&]uh1jvhjpubjw)}(h^SCSI_EH_NOT_HANDLED eh_timed_out() callback did not handle the command. Step #2 is taken. h]jx)}(hhh]j})}(hZSCSI_EH_NOT_HANDLED eh_timed_out() callback did not handle the command. Step #2 is taken. h](j)}(hSCSI_EH_NOT_HANDLEDh]hSCSI_EH_NOT_HANDLED}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKehjubj)}(hhh]h)}(hEeh_timed_out() callback did not handle the command. Step #2 is taken.h]hEeh_timed_out() callback did not handle the command. Step #2 is taken.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKdhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j|hhhKehjubah}(h]h ]h"]h$]h&]uh1jwhjubah}(h]h ]h"]h$]h&]uh1jvhjpubjw)}(h5SCSI_EH_DONE eh_timed_out() completed the command. h]jx)}(hhh]j})}(h3SCSI_EH_DONE eh_timed_out() completed the command. h](j)}(h SCSI_EH_DONEh]h SCSI_EH_DONE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhhjubj)}(hhh]h)}(h%eh_timed_out() completed the command.h]h%eh_timed_out() completed the command.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j|hhhKhhjubah}(h]h ]h"]h$]h&]uh1jwhjubah}(h]h ]h"]h$]h&]uh1jvhjpubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhK_hj^ubeh}(h]h ]h"]h$]h&]uh1jvhj[ubjw)}(hXscsi_abort_command() is invoked to schedule an asynchronous abort which may issue a retry scmd->allowed + 1 times. Asynchronous aborts are not invoked for commands for which the SCSI_EH_ABORT_SCHEDULED flag is set (this indicates that the command already had been aborted once, and this is a retry which failed), when retries are exceeded, or when the EH deadline is expired. In these cases Step #3 is taken. h]h)}(hXscsi_abort_command() is invoked to schedule an asynchronous abort which may issue a retry scmd->allowed + 1 times. Asynchronous aborts are not invoked for commands for which the SCSI_EH_ABORT_SCHEDULED flag is set (this indicates that the command already had been aborted once, and this is a retry which failed), when retries are exceeded, or when the EH deadline is expired. In these cases Step #3 is taken.h]hXscsi_abort_command() is invoked to schedule an asynchronous abort which may issue a retry scmd->allowed + 1 times. Asynchronous aborts are not invoked for commands for which the SCSI_EH_ABORT_SCHEDULED flag is set (this indicates that the command already had been aborted once, and this is a retry which failed), when retries are exceeded, or when the EH deadline is expired. In these cases Step #3 is taken.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjMubah}(h]h ]h"]h$]h&]uh1jvhj[ubjw)}(hTscsi_eh_scmd_add(scmd) is invoked for the command. See [1-4] for more information. h]h)}(hSscsi_eh_scmd_add(scmd) is invoked for the command. See [1-4] for more information.h]hSscsi_eh_scmd_add(scmd) is invoked for the command. See [1-4] for more information.}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKqhjeubah}(h]h ]h"]h$]h&]uh1jvhj[ubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jYhjUubah}(h]h ]h"]h$]h&]uh1jkhhhK\hj6hhubeh}(h]completing-a-scmd-w-timeoutah ]h"]"1.2.2 completing a scmd w/ timeoutah$]h&]uh1hhjhhhhhKXubeh}(h]how-do-scmd-s-get-completedah ]h"] 1.2 how do scmd's get completed?ah$]h&]uh1hhhhhhhhK.ubh)}(hhh](h)}(h1.3 Asynchronous command abortsh]h1.3 Asynchronous command aborts}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKuubjl)}(hX4After 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. h](h)}(hAfter 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.h]hAfter 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKwhjubh)}(hXOtherwise scsi_eh_scmd_add() is invoked for the command. See [1-4] for more information.h]hXOtherwise scsi_eh_scmd_add() is invoked for the command. See [1-4] for more information.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK|hjubeh}(h]h ]h"]h$]h&]uh1jkhhhKwhjhhubeh}(h]asynchronous-command-abortsah ]h"]1.3 asynchronous command abortsah$]h&]uh1hhhhhhhhKuubh)}(hhh](h)}(h1.4 How EH takes overh]h1.4 How EH takes over}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(h@scmds enter EH via scsi_eh_scmd_add(), which does the following.h]h@scmds enter EH via scsi_eh_scmd_add(), which does the following.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjl)}(h1. Links scmd->eh_entry to shost->eh_cmd_q 2. Sets SHOST_RECOVERY bit in shost->shost_state 3. Increments shost->host_failed 4. Wakes up SCSI EH thread if shost->host_busy == shost->host_failed h]jZ)}(hhh](jw)}(h(Links scmd->eh_entry to shost->eh_cmd_q h]h)}(h'Links scmd->eh_entry to shost->eh_cmd_qh]h'Links scmd->eh_entry to shost->eh_cmd_q}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(h.Sets SHOST_RECOVERY bit in shost->shost_state h]h)}(h-Sets SHOST_RECOVERY bit in shost->shost_stateh]h-Sets SHOST_RECOVERY bit in shost->shost_state}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hIncrements shost->host_failed h]h)}(hIncrements shost->host_failedh]hIncrements shost->host_failed}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj3ubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hBWakes up SCSI EH thread if shost->host_busy == shost->host_failed h]h)}(hAWakes up SCSI EH thread if shost->host_busy == shost->host_failedh]hAWakes up SCSI EH thread if shost->host_busy == shost->host_failed}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjKubah}(h]h ]h"]h$]h&]uh1jvhjubeh}(h]h ]h"]h$]h&]jjjhjjuh1jYhjubah}(h]h ]h"]h$]h&]uh1jkhhhKhjhhubh)}(hX<As can be seen above, once any scmd is added to shost->eh_cmd_q, SHOST_RECOVERY shost_state bit is turned on. This prevents any new scmd to be issued from blk queue to the host; eventually, all scmds on the host either complete normally, fail and get added to eh_cmd_q, or time out and get added to shost->eh_cmd_q.h]hX<As can be seen above, once any scmd is added to shost->eh_cmd_q, SHOST_RECOVERY shost_state bit is turned on. This prevents any new scmd to be issued from blk queue to the host; eventually, all scmds on the host either complete normally, fail and get added to eh_cmd_q, or time out and get added to shost->eh_cmd_q.}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX6If all scmds either complete or fail, the number of in-flight scmds becomes equal to the number of failed scmds - i.e. shost->host_busy == shost->host_failed. This wakes up SCSI EH thread. So, once woken up, SCSI EH thread can expect that all in-flight commands have failed and are linked on shost->eh_cmd_q.h]hX6If all scmds either complete or fail, the number of in-flight scmds becomes equal to the number of failed scmds - i.e. shost->host_busy == shost->host_failed. This wakes up SCSI EH thread. So, once woken up, SCSI EH thread can expect that all in-flight commands have failed and are linked on shost->eh_cmd_q.}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXNote that this does not mean lower layers are quiescent. If a LLDD completed a scmd with error status, the LLDD and lower layers are assumed to forget about the scmd at that point. However, if a scmd has timed out, unless hostt->eh_timed_out() made lower layers forget about the scmd, which currently no LLDD does, the command is still active as long as lower layers are concerned and completion could occur at any time. Of course, all such completions are ignored as the timer has already expired.h]hXNote that this does not mean lower layers are quiescent. If a LLDD completed a scmd with error status, the LLDD and lower layers are assumed to forget about the scmd at that point. However, if a scmd has timed out, unless hostt->eh_timed_out() made lower layers forget about the scmd, which currently no LLDD does, the command is still active as long as lower layers are concerned and completion could occur at any time. Of course, all such completions are ignored as the timer has already expired.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(heWe'll talk about how SCSI EH takes actions to abort - make LLDD forget about - timed out scmds later.h]hgWe’ll talk about how SCSI EH takes actions to abort - make LLDD forget about - timed out scmds later.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]how-eh-takes-overah ]h"]1.4 how eh takes overah$]h&]uh1hhhhhhhhKubeh}(h]7how-scsi-commands-travel-through-the-midlayer-and-to-ehah ]h"]:1. how scsi commands travel through the midlayer and to ehah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h2. How SCSI EH worksh]h2. How SCSI EH works}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hFLLDD's can implement SCSI EH actions in one of the following two ways.h]hHLLDD’s can implement SCSI EH actions in one of the following two ways.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjl)}(hX- Fine-grained EH callbacks LLDD can implement fine-grained EH callbacks and let SCSI midlayer drive error handling and call appropriate callbacks. This will be discussed further in [2-1]. - eh_strategy_handler() callback This is one big callback which should perform whole error handling. As such, it should do all chores the SCSI midlayer performs during recovery. This will be discussed in [2-2]. h]jr)}(hhh](jw)}(hFine-grained EH callbacks LLDD can implement fine-grained EH callbacks and let SCSI midlayer drive error handling and call appropriate callbacks. This will be discussed further in [2-1]. h]jx)}(hhh]j})}(hFine-grained EH callbacks LLDD can implement fine-grained EH callbacks and let SCSI midlayer drive error handling and call appropriate callbacks. This will be discussed further in [2-1]. h](j)}(hFine-grained EH callbacksh]hFine-grained EH callbacks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh]h)}(hLLDD can implement fine-grained EH callbacks and let SCSI midlayer drive error handling and call appropriate callbacks. This will be discussed further in [2-1].h]hLLDD can implement fine-grained EH callbacks and let SCSI midlayer drive error handling and call appropriate callbacks. This will be discussed further in [2-1].}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j|hhhKhjubah}(h]h ]h"]h$]h&]uh1jwhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(heh_strategy_handler() callback This is one big callback which should perform whole error handling. As such, it should do all chores the SCSI midlayer performs during recovery. This will be discussed in [2-2]. h]jx)}(hhh]j})}(heh_strategy_handler() callback This is one big callback which should perform whole error handling. As such, it should do all chores the SCSI midlayer performs during recovery. This will be discussed in [2-2]. h](j)}(heh_strategy_handler() callbackh]heh_strategy_handler() callback}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj&ubj)}(hhh]h)}(hThis is one big callback which should perform whole error handling. As such, it should do all chores the SCSI midlayer performs during recovery. This will be discussed in [2-2].h]hThis is one big callback which should perform whole error handling. As such, it should do all chores the SCSI midlayer performs during recovery. This will be discussed in [2-2].}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj8ubah}(h]h ]h"]h$]h&]uh1jhj&ubeh}(h]h ]h"]h$]h&]uh1j|hhhKhj#ubah}(h]h ]h"]h$]h&]uh1jwhjubah}(h]h ]h"]h$]h&]uh1jvhjubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhKhjubah}(h]h ]h"]h$]h&]uh1jkhhhKhjhhubh)}(hgOnce recovery is complete, SCSI EH resumes normal operation by calling scsi_restart_operations(), whichh]hgOnce recovery is complete, SCSI EH resumes normal operation by calling scsi_restart_operations(), which}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjl)}(hX|1. Checks if door locking is needed and locks door. 2. Clears SHOST_RECOVERY shost_state bit 3. Wakes up waiters on shost->host_wait. This occurs if someone calls scsi_block_when_processing_errors() on the host. (*QUESTION* why is it needed? All operations will be blocked anyway after it reaches blk queue.) 4. Kicks queues in all devices on the host in the asses h]jZ)}(hhh](jw)}(h1Checks if door locking is needed and locks door. h]h)}(h0Checks if door locking is needed and locks door.h]h0Checks if door locking is needed and locks door.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(h&Clears SHOST_RECOVERY shost_state bit h]h)}(h%Clears SHOST_RECOVERY shost_state bith]h%Clears SHOST_RECOVERY shost_state bit}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hWakes up waiters on shost->host_wait. This occurs if someone calls scsi_block_when_processing_errors() on the host. (*QUESTION* why is it needed? All operations will be blocked anyway after it reaches blk queue.) h]h)}(hWakes up waiters on shost->host_wait. This occurs if someone calls scsi_block_when_processing_errors() on the host. (*QUESTION* why is it needed? All operations will be blocked anyway after it reaches blk queue.)h](hvWakes up waiters on shost->host_wait. This occurs if someone calls scsi_block_when_processing_errors() on the host. (}(hjhhhNhNubhemphasis)}(h *QUESTION*h]hQUESTION}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhV why is it needed? All operations will be blocked anyway after it reaches blk queue.)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(h6Kicks queues in all devices on the host in the asses h]h)}(h4Kicks queues in all devices on the host in the assesh]h4Kicks queues in all devices on the host in the asses}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jvhjubeh}(h]h ]h"]h$]h&]jjjhjjuh1jYhj{ubah}(h]h ]h"]h$]h&]uh1jkhhhKhjhhubh)}(hhh](h)}(h%2.1 EH through fine-grained callbacksh]h%2.1 EH through fine-grained callbacks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h2.1.1 Overviewh]h2.1.1 Overview}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXYIf eh_strategy_handler() is not present, SCSI midlayer takes charge of driving error handling. EH's goals are two - make LLDD, host and device forget about timed out scmds and make them ready for new commands. A scmd is said to be recovered if the scmd is forgotten by lower layers and lower layers are ready to process or fail the scmd again.h]hX[If eh_strategy_handler() is not present, SCSI midlayer takes charge of driving error handling. EH’s goals are two - make LLDD, host and device forget about timed out scmds and make them ready for new commands. A scmd is said to be recovered if the scmd is forgotten by lower layers and lower layers are ready to process or fail the scmd again.}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX(To achieve these goals, EH performs recovery actions with increasing severity. Some actions are performed by issuing SCSI commands and others are performed by invoking one of the following fine-grained hostt EH callbacks. Callbacks may be omitted and omitted ones are considered to fail always.h]hX(To achieve these goals, EH performs recovery actions with increasing severity. Some actions are performed by issuing SCSI commands and others are performed by invoking one of the following fine-grained hostt EH callbacks. Callbacks may be omitted and omitted ones are considered to fail always.}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh literal_block)}(hint (* eh_abort_handler)(struct scsi_cmnd *); int (* eh_device_reset_handler)(struct scsi_cmnd *); int (* eh_bus_reset_handler)(struct scsi_cmnd *); int (* eh_host_reset_handler)(struct scsi_cmnd *);h]hint (* eh_abort_handler)(struct scsi_cmnd *); int (* eh_device_reset_handler)(struct scsi_cmnd *); int (* eh_bus_reset_handler)(struct scsi_cmnd *); int (* eh_host_reset_handler)(struct scsi_cmnd *);}hjBsbah}(h]h ]h"]h$]h&]hhuh1j@hhhKhjhhubh)}(hHigher-severity actions are taken only when lower-severity actions cannot recover some of failed scmds. Also, note that failure of the highest-severity action means EH failure and results in offlining of all unrecovered devices.h]hHigher-severity actions are taken only when lower-severity actions cannot recover some of failed scmds. Also, note that failure of the highest-severity action means EH failure and results in offlining of all unrecovered devices.}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h1During recovery, the following rules are followedh]h1During recovery, the following rules are followed}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjl)}(hXM- Recovery actions are performed on failed scmds on the to do list, eh_work_q. If a recovery action succeeds for a scmd, recovered scmds are removed from eh_work_q. Note that single recovery action on a scmd can recover multiple scmds. e.g. resetting a device recovers all failed scmds on the device. - Higher severity actions are taken iff eh_work_q is not empty after lower severity actions are complete. - EH reuses failed scmds to issue commands for recovery. For timed-out scmds, SCSI EH ensures that LLDD forgets about a scmd before reusing it for EH commands. h]jr)}(hhh](jw)}(hX.Recovery actions are performed on failed scmds on the to do list, eh_work_q. If a recovery action succeeds for a scmd, recovered scmds are removed from eh_work_q. Note that single recovery action on a scmd can recover multiple scmds. e.g. resetting a device recovers all failed scmds on the device. h](h)}(hRecovery actions are performed on failed scmds on the to do list, eh_work_q. If a recovery action succeeds for a scmd, recovered scmds are removed from eh_work_q.h]hRecovery actions are performed on failed scmds on the to do list, eh_work_q. If a recovery action succeeds for a scmd, recovered scmds are removed from eh_work_q.}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjsubh)}(hNote that single recovery action on a scmd can recover multiple scmds. e.g. resetting a device recovers all failed scmds on the device.h]hNote that single recovery action on a scmd can recover multiple scmds. e.g. resetting a device recovers all failed scmds on the device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjsubeh}(h]h ]h"]h$]h&]uh1jvhjpubjw)}(hhHigher severity actions are taken iff eh_work_q is not empty after lower severity actions are complete. h]h)}(hgHigher severity actions are taken iff eh_work_q is not empty after lower severity actions are complete.h]hgHigher severity actions are taken iff eh_work_q is not empty after lower severity actions are complete.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jvhjpubjw)}(hEH reuses failed scmds to issue commands for recovery. For timed-out scmds, SCSI EH ensures that LLDD forgets about a scmd before reusing it for EH commands. h]h)}(hEH reuses failed scmds to issue commands for recovery. For timed-out scmds, SCSI EH ensures that LLDD forgets about a scmd before reusing it for EH commands.h]hEH reuses failed scmds to issue commands for recovery. For timed-out scmds, SCSI EH ensures that LLDD forgets about a scmd before reusing it for EH commands.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jvhjpubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhKhjlubah}(h]h ]h"]h$]h&]uh1jkhhhKhjhhubh)}(hXWhen a scmd is recovered, the scmd is moved from eh_work_q to EH local eh_done_q using scsi_eh_finish_cmd(). After all scmds are recovered (eh_work_q is empty), scsi_eh_flush_done_q() is invoked to either retry or error-finish (notify upper layer of failure) recovered scmds.h]hXWhen a scmd is recovered, the scmd is moved from eh_work_q to EH local eh_done_q using scsi_eh_finish_cmd(). After all scmds are recovered (eh_work_q is empty), scsi_eh_flush_done_q() is invoked to either retry or error-finish (notify upper layer of failure) recovered scmds.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hscmds are retried iff its sdev is still online (not offlined during EH), REQ_FAILFAST is not set and ++scmd->retries is less than scmd->allowed.h]hscmds are retried iff its sdev is still online (not offlined during EH), REQ_FAILFAST is not set and ++scmd->retries is less than scmd->allowed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]overviewah ]h"]2.1.1 overviewah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h2.1.2 Flow of scmds through EHh]h2.1.2 Flow of scmds through EH}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubjl)}(hX1. Error completion / time out :ACTION: scsi_eh_scmd_add() is invoked for scmd - add scmd to shost->eh_cmd_q - set SHOST_RECOVERY - shost->host_failed++ :LOCKING: shost->host_lock 2. EH starts :ACTION: move all scmds to EH's local eh_work_q. shost->eh_cmd_q is cleared. :LOCKING: shost->host_lock (not strictly necessary, just for consistency) 3. scmd recovered :ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd - move from local eh_work_q to local eh_done_q :LOCKING: none :CONCURRENCY: at most one thread per separate eh_work_q to keep queue manipulation lockless 4. EH completes :ACTION: scsi_eh_flush_done_q() retries scmds or notifies upper layer of failure. May be called concurrently but must have a no more than one thread per separate eh_work_q to manipulate the queue locklessly - scmd is removed from eh_done_q and scmd->eh_entry is cleared - if retry is necessary, scmd is requeued using scsi_queue_insert() - otherwise, scsi_finish_command() is invoked for scmd - zero shost->host_failed :LOCKING: queue or finish function performs appropriate locking h]jZ)}(hhh](jw)}(hError completion / time out :ACTION: scsi_eh_scmd_add() is invoked for scmd - add scmd to shost->eh_cmd_q - set SHOST_RECOVERY - shost->host_failed++ :LOCKING: shost->host_lock h](h)}(hError completion / time outh]hError completion / time out}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh field_list)}(hhh](hfield)}(hhh](h field_name)}(hACTIONh]hACTION}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj*hhhKubh field_body)}(hrscsi_eh_scmd_add() is invoked for scmd - add scmd to shost->eh_cmd_q - set SHOST_RECOVERY - shost->host_failed++ h](h)}(h&scsi_eh_scmd_add() is invoked for scmdh]h&scsi_eh_scmd_add() is invoked for scmd}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj?ubjr)}(hhh](jw)}(hadd scmd to shost->eh_cmd_qh]h)}(hjVh]hadd scmd to shost->eh_cmd_q}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjTubah}(h]h ]h"]h$]h&]uh1jvhjQubjw)}(hset SHOST_RECOVERYh]h)}(hjmh]hset SHOST_RECOVERY}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjkubah}(h]h ]h"]h$]h&]uh1jvhjQubjw)}(hshost->host_failed++ h]h)}(hshost->host_failed++h]hshost->host_failed++}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjQubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhMhj?ubeh}(h]h ]h"]h$]h&]uh1j=hj*ubeh}(h]h ]h"]h$]h&]uh1j(hhhMhj%ubj))}(hhh](j.)}(hLOCKINGh]hLOCKING}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjhhhKubj>)}(hshost->host_lock h]h)}(hshost->host_lockh]hshost->host_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubah}(h]h ]h"]h$]h&]uh1j=hjubeh}(h]h ]h"]h$]h&]uh1j(hhhM hj%ubeh}(h]h ]h"]h$]h&]uh1j#hjubeh}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hEH starts :ACTION: move all scmds to EH's local eh_work_q. shost->eh_cmd_q is cleared. :LOCKING: shost->host_lock (not strictly necessary, just for consistency) h](h)}(h EH startsh]h EH starts}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubj$)}(hhh](j))}(hhh](j.)}(hACTIONh]hACTION}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjhhhKubj>)}(hEmove all scmds to EH's local eh_work_q. shost->eh_cmd_q is cleared. h]h)}(hDmove all scmds to EH's local eh_work_q. shost->eh_cmd_q is cleared.h]hFmove all scmds to EH’s local eh_work_q. shost->eh_cmd_q is cleared.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j=hjubeh}(h]h ]h"]h$]h&]uh1j(hhhMhjubj))}(hhh](j.)}(hLOCKINGh]hLOCKING}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj+hhhKubj>)}(h@shost->host_lock (not strictly necessary, just for consistency) h]h)}(h?shost->host_lock (not strictly necessary, just for consistency)h]h?shost->host_lock (not strictly necessary, just for consistency)}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj<ubah}(h]h ]h"]h$]h&]uh1j=hj+ubeh}(h]h ]h"]h$]h&]uh1j(hhhMhjubeh}(h]h ]h"]h$]h&]uh1j#hjubeh}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hscmd recovered :ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd - move from local eh_work_q to local eh_done_q :LOCKING: none :CONCURRENCY: at most one thread per separate eh_work_q to keep queue manipulation lockless h](h)}(hscmd recoveredh]hscmd recovered}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjfubj$)}(hhh](j))}(hhh](j.)}(hACTIONh]hACTION}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj{hhhKubj>)}(hbscsi_eh_finish_cmd() is invoked to EH-finish scmd - move from local eh_work_q to local eh_done_q h](h)}(h1scsi_eh_finish_cmd() is invoked to EH-finish scmdh]h1scsi_eh_finish_cmd() is invoked to EH-finish scmd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubjr)}(hhh]jw)}(h-move from local eh_work_q to local eh_done_q h]h)}(h,move from local eh_work_q to local eh_done_qh]h,move from local eh_work_q to local eh_done_q}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjubah}(h]h ]h"]h$]h&]j&j'uh1jqhhhMhjubeh}(h]h ]h"]h$]h&]uh1j=hj{ubeh}(h]h ]h"]h$]h&]uh1j(hhhMhjxubj))}(hhh](j.)}(hLOCKINGh]hLOCKING}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjhhhKubj>)}(hnone h]h)}(hnoneh]hnone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j=hjubeh}(h]h ]h"]h$]h&]uh1j(hhhMhjxubj))}(hhh](j.)}(h CONCURRENCYh]h CONCURRENCY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjhhhKubj>)}(hNat most one thread per separate eh_work_q to keep queue manipulation lockless h]h)}(hMat most one thread per separate eh_work_q to keep queue manipulation locklessh]hMat most one thread per separate eh_work_q to keep queue manipulation lockless}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j=hjubeh}(h]h ]h"]h$]h&]uh1j(hhhMhjxubeh}(h]h ]h"]h$]h&]uh1j#hjfubeh}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hX>EH completes :ACTION: scsi_eh_flush_done_q() retries scmds or notifies upper layer of failure. May be called concurrently but must have a no more than one thread per separate eh_work_q to manipulate the queue locklessly - scmd is removed from eh_done_q and scmd->eh_entry is cleared - if retry is necessary, scmd is requeued using scsi_queue_insert() - otherwise, scsi_finish_command() is invoked for scmd - zero shost->host_failed :LOCKING: queue or finish function performs appropriate locking h](h)}(h EH completesh]h EH completes}(hj9 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj5 ubj$)}(hhh](j))}(hhh](j.)}(hACTIONh]hACTION}(hjM hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hjJ hhhKubj>)}(hXscsi_eh_flush_done_q() retries scmds or notifies upper layer of failure. May be called concurrently but must have a no more than one thread per separate eh_work_q to manipulate the queue locklessly - scmd is removed from eh_done_q and scmd->eh_entry is cleared - if retry is necessary, scmd is requeued using scsi_queue_insert() - otherwise, scsi_finish_command() is invoked for scmd - zero shost->host_failed h](h)}(hscsi_eh_flush_done_q() retries scmds or notifies upper layer of failure. May be called concurrently but must have a no more than one thread per separate eh_work_q to manipulate the queue locklesslyh]hscsi_eh_flush_done_q() retries scmds or notifies upper layer of failure. May be called concurrently but must have a no more than one thread per separate eh_work_q to manipulate the queue locklessly}(hj_ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM!hj[ ubjr)}(hhh](jw)}(heh_entry is clearedh]h)}(hjr h]heh_entry is cleared}(hjt hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hjp ubah}(h]h ]h"]h$]h&]uh1jvhjm ubjw)}(hAif retry is necessary, scmd is requeued using scsi_queue_insert()h]h)}(hAif retry is necessary, scmd is requeued using scsi_queue_insert()h]hAif retry is necessary, scmd is requeued using scsi_queue_insert()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM'hj ubah}(h]h ]h"]h$]h&]uh1jvhjm ubjw)}(h4otherwise, scsi_finish_command() is invoked for scmdh]h)}(hj h]h4otherwise, scsi_finish_command() is invoked for scmd}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM)hj ubah}(h]h ]h"]h$]h&]uh1jvhjm ubjw)}(hzero shost->host_failed h]h)}(hzero shost->host_failedh]hzero shost->host_failed}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hj ubah}(h]h ]h"]h$]h&]uh1jvhjm ubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhM&hj[ ubeh}(h]h ]h"]h$]h&]uh1j=hjJ ubeh}(h]h ]h"]h$]h&]uh1j(hhhM!hjG ubj))}(hhh](j.)}(hLOCKINGh]hLOCKING}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j-hj hhhKubj>)}(h7queue or finish function performs appropriate locking h]h)}(h5queue or finish function performs appropriate lockingh]h5queue or finish function performs appropriate locking}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hj ubah}(h]h ]h"]h$]h&]uh1j=hj ubeh}(h]h ]h"]h$]h&]uh1j(hhhM,hjG ubeh}(h]h ]h"]h$]h&]uh1j#hj5 ubeh}(h]h ]h"]h$]h&]uh1jvhjubeh}(h]h ]h"]h$]h&]jjjhjjuh1jYhj ubah}(h]h ]h"]h$]h&]uh1jkhhhMhjhhubeh}(h]flow-of-scmds-through-ehah ]h"]2.1.2 flow of scmds through ehah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h2.1.3 Flow of controlh]h2.1.3 Flow of control}(hj2 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj/ hhhhhM0ubjl)}(h@EH through fine-grained callbacks start from scsi_unjam_host(). h]h)}(h?EH through fine-grained callbacks start from scsi_unjam_host().h]h?EH through fine-grained callbacks start from scsi_unjam_host().}(hjD hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hj@ ubah}(h]h ]h"]h$]h&]uh1jkhhhM2hj/ hhubh)}(h``scsi_unjam_host``h]hliteral)}(hjZ h]hscsi_unjam_host}(hj^ hhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hjX ubah}(h]h ]h"]h$]h&]uh1hhhhM4hj/ hhubjl)}(hX1. Lock shost->host_lock, splice_init shost->eh_cmd_q into local eh_work_q and unlock host_lock. Note that shost->eh_cmd_q is cleared by this action. 2. Invoke scsi_eh_get_sense. ``scsi_eh_get_sense`` This action is taken for each error-completed command without valid sense data. Most SCSI transports/LLDDs automatically acquire sense data on command failures (autosense). Autosense is recommended for performance reasons and as sense information could get out of sync between occurrence of CHECK CONDITION and this action. Note that if autosense is not supported, scmd->sense_buffer contains invalid sense data when error-completing the scmd with scsi_done(). scsi_decide_disposition() always returns FAILED in such cases thus invoking SCSI EH. When the scmd reaches here, sense data is acquired and scsi_decide_disposition() is called again. 1. Invoke scsi_request_sense() which issues REQUEST_SENSE command. If fails, no action. Note that taking no action causes higher-severity recovery to be taken for the scmd. 2. Invoke scsi_decide_disposition() on the scmd - SUCCESS scmd->retries is set to scmd->allowed preventing scsi_eh_flush_done_q() from retrying the scmd and scsi_eh_finish_cmd() is invoked. - NEEDS_RETRY scsi_eh_finish_cmd() invoked - otherwise No action. 4. If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs() ``scsi_eh_ready_devs`` This function takes four increasingly more severe measures to make failed sdevs ready for new commands. 1. Invoke scsi_eh_stu() ``scsi_eh_stu`` For each sdev which has failed scmds with valid sense data of which scsi_check_sense()'s verdict is FAILED, START STOP UNIT command is issued w/ start=1. Note that as we explicitly choose error-completed scmds, it is known that lower layers have forgotten about the scmd and we can reuse it for STU. If STU succeeds and the sdev is either offline or ready, all failed scmds on the sdev are EH-finished with scsi_eh_finish_cmd(). *NOTE* If hostt->eh_abort_handler() isn't implemented or failed, we may still have timed out scmds at this point and STU doesn't make lower layers forget about those scmds. Yet, this function EH-finish all scmds on the sdev if STU succeeds leaving lower layers in an inconsistent state. It seems that STU action should be taken only when a sdev has no timed out scmd. 2. If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset(). ``scsi_eh_bus_device_reset`` This action is very similar to scsi_eh_stu() except that, instead of issuing STU, hostt->eh_device_reset_handler() is used. Also, as we're not issuing SCSI commands and resetting clears all scmds on the sdev, there is no need to choose error-completed scmds. 3. If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset() ``scsi_eh_bus_reset`` hostt->eh_bus_reset_handler() is invoked for each channel with failed scmds. If bus reset succeeds, all failed scmds on all ready or offline sdevs on the channel are EH-finished. 4. If !list_empty(&eh_work_q), invoke scsi_eh_host_reset() ``scsi_eh_host_reset`` This is the last resort. hostt->eh_host_reset_handler() is invoked. If host reset succeeds, all failed scmds on all ready or offline sdevs on the host are EH-finished. 5. If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs() ``scsi_eh_offline_sdevs`` Take all sdevs which still have unrecovered scmds offline and EH-finish the scmds. 5. Invoke scsi_eh_flush_done_q(). ``scsi_eh_flush_done_q`` At this point all scmds are recovered (or given up) and put on eh_done_q by scsi_eh_finish_cmd(). This function flushes eh_done_q by either retrying or notifying upper layer of failure of the scmds. h](jZ)}(hhh](jw)}(hLock shost->host_lock, splice_init shost->eh_cmd_q into local eh_work_q and unlock host_lock. Note that shost->eh_cmd_q is cleared by this action. h]h)}(hLock shost->host_lock, splice_init shost->eh_cmd_q into local eh_work_q and unlock host_lock. Note that shost->eh_cmd_q is cleared by this action.h]hLock shost->host_lock, splice_init shost->eh_cmd_q into local eh_work_q and unlock host_lock. Note that shost->eh_cmd_q is cleared by this action.}(hj| hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hjx ubah}(h]h ]h"]h$]h&]uh1jvhju ubjw)}(hInvoke scsi_eh_get_sense. h]h)}(hInvoke scsi_eh_get_sense.h]hInvoke scsi_eh_get_sense.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM:hj ubah}(h]h ]h"]h$]h&]uh1jvhju ubeh}(h]h ]h"]h$]h&]jjjhjjuh1jYhjq ubh)}(h``scsi_eh_get_sense``h]j] )}(hj h]hscsi_eh_get_sense}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hj ubah}(h]h ]h"]h$]h&]uh1hhhhM<hjq ubjl)}(hXtThis action is taken for each error-completed command without valid sense data. Most SCSI transports/LLDDs automatically acquire sense data on command failures (autosense). Autosense is recommended for performance reasons and as sense information could get out of sync between occurrence of CHECK CONDITION and this action. Note that if autosense is not supported, scmd->sense_buffer contains invalid sense data when error-completing the scmd with scsi_done(). scsi_decide_disposition() always returns FAILED in such cases thus invoking SCSI EH. When the scmd reaches here, sense data is acquired and scsi_decide_disposition() is called again. 1. Invoke scsi_request_sense() which issues REQUEST_SENSE command. If fails, no action. Note that taking no action causes higher-severity recovery to be taken for the scmd. 2. Invoke scsi_decide_disposition() on the scmd - SUCCESS scmd->retries is set to scmd->allowed preventing scsi_eh_flush_done_q() from retrying the scmd and scsi_eh_finish_cmd() is invoked. - NEEDS_RETRY scsi_eh_finish_cmd() invoked - otherwise No action. h](h)}(hXEThis action is taken for each error-completed command without valid sense data. Most SCSI transports/LLDDs automatically acquire sense data on command failures (autosense). Autosense is recommended for performance reasons and as sense information could get out of sync between occurrence of CHECK CONDITION and this action.h]hXEThis action is taken for each error-completed command without valid sense data. Most SCSI transports/LLDDs automatically acquire sense data on command failures (autosense). Autosense is recommended for performance reasons and as sense information could get out of sync between occurrence of CHECK CONDITION and this action.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM>hj ubh)}(hXANote that if autosense is not supported, scmd->sense_buffer contains invalid sense data when error-completing the scmd with scsi_done(). scsi_decide_disposition() always returns FAILED in such cases thus invoking SCSI EH. When the scmd reaches here, sense data is acquired and scsi_decide_disposition() is called again.h]hXANote that if autosense is not supported, scmd->sense_buffer contains invalid sense data when error-completing the scmd with scsi_done(). scsi_decide_disposition() always returns FAILED in such cases thus invoking SCSI EH. When the scmd reaches here, sense data is acquired and scsi_decide_disposition() is called again.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhj ubjZ)}(hhh](jw)}(hInvoke scsi_request_sense() which issues REQUEST_SENSE command. If fails, no action. Note that taking no action causes higher-severity recovery to be taken for the scmd. h]h)}(hInvoke scsi_request_sense() which issues REQUEST_SENSE command. If fails, no action. Note that taking no action causes higher-severity recovery to be taken for the scmd.h]hInvoke scsi_request_sense() which issues REQUEST_SENSE command. If fails, no action. Note that taking no action causes higher-severity recovery to be taken for the scmd.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhj ubah}(h]h ]h"]h$]h&]uh1jvhj ubjw)}(hXInvoke scsi_decide_disposition() on the scmd - SUCCESS scmd->retries is set to scmd->allowed preventing scsi_eh_flush_done_q() from retrying the scmd and scsi_eh_finish_cmd() is invoked. - NEEDS_RETRY scsi_eh_finish_cmd() invoked - otherwise No action. h](h)}(h,Invoke scsi_decide_disposition() on the scmdh]h,Invoke scsi_decide_disposition() on the scmd}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMPhj ubjr)}(hhh](jw)}(hSUCCESS scmd->retries is set to scmd->allowed preventing scsi_eh_flush_done_q() from retrying the scmd and scsi_eh_finish_cmd() is invoked. h]jx)}(hhh]j})}(hSUCCESS scmd->retries is set to scmd->allowed preventing scsi_eh_flush_done_q() from retrying the scmd and scsi_eh_finish_cmd() is invoked. h](j)}(hSUCCESSh]hSUCCESS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMUhj ubj)}(hhh]h)}(hscmd->retries is set to scmd->allowed preventing scsi_eh_flush_done_q() from retrying the scmd and scsi_eh_finish_cmd() is invoked.h]hscmd->retries is set to scmd->allowed preventing scsi_eh_flush_done_q() from retrying the scmd and scsi_eh_finish_cmd() is invoked.}(hj1 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMShj. ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j|hhhMUhj ubah}(h]h ]h"]h$]h&]uh1jwhj ubah}(h]h ]h"]h$]h&]uh1jvhj ubjw)}(h,NEEDS_RETRY scsi_eh_finish_cmd() invoked h]jx)}(hhh]j})}(h)NEEDS_RETRY scsi_eh_finish_cmd() invoked h](j)}(h NEEDS_RETRYh]h NEEDS_RETRY}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMXhj^ ubj)}(hhh]h)}(hscsi_eh_finish_cmd() invokedh]hscsi_eh_finish_cmd() invoked}(hjs hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjp ubah}(h]h ]h"]h$]h&]uh1jhj^ ubeh}(h]h ]h"]h$]h&]uh1j|hhhMXhj[ ubah}(h]h ]h"]h$]h&]uh1jwhjW ubah}(h]h ]h"]h$]h&]uh1jvhj ubjw)}(hotherwise No action. h]jx)}(hhh]j})}(hotherwise No action. h](j)}(h otherwiseh]h otherwise}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM[hj ubj)}(hhh]h)}(h No action.h]h No action.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM[hj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j|hhhM[hj ubah}(h]h ]h"]h$]h&]uh1jwhj ubah}(h]h ]h"]h$]h&]uh1jvhj ubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhMRhj ubeh}(h]h ]h"]h$]h&]uh1jvhj ubeh}(h]h ]h"]h$]h&]jjjhjjuh1jYhj ubeh}(h]h ]h"]h$]h&]uh1jkhhhM>hjq ubjZ)}(hhh]jw)}(h8If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs() h]h)}(h7If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs()h]h7If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM]hj ubah}(h]h ]h"]h$]h&]uh1jvhj ubah}(h]h ]h"]h$]h&]jjjhjjstartKuh1jYhjq ubh)}(h``scsi_eh_ready_devs``h]j] )}(hj h]hscsi_eh_ready_devs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hj ubah}(h]h ]h"]h$]h&]uh1hhhhM_hjq ubjl)}(hXGThis function takes four increasingly more severe measures to make failed sdevs ready for new commands. 1. Invoke scsi_eh_stu() ``scsi_eh_stu`` For each sdev which has failed scmds with valid sense data of which scsi_check_sense()'s verdict is FAILED, START STOP UNIT command is issued w/ start=1. Note that as we explicitly choose error-completed scmds, it is known that lower layers have forgotten about the scmd and we can reuse it for STU. If STU succeeds and the sdev is either offline or ready, all failed scmds on the sdev are EH-finished with scsi_eh_finish_cmd(). *NOTE* If hostt->eh_abort_handler() isn't implemented or failed, we may still have timed out scmds at this point and STU doesn't make lower layers forget about those scmds. Yet, this function EH-finish all scmds on the sdev if STU succeeds leaving lower layers in an inconsistent state. It seems that STU action should be taken only when a sdev has no timed out scmd. 2. If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset(). ``scsi_eh_bus_device_reset`` This action is very similar to scsi_eh_stu() except that, instead of issuing STU, hostt->eh_device_reset_handler() is used. Also, as we're not issuing SCSI commands and resetting clears all scmds on the sdev, there is no need to choose error-completed scmds. 3. If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset() ``scsi_eh_bus_reset`` hostt->eh_bus_reset_handler() is invoked for each channel with failed scmds. If bus reset succeeds, all failed scmds on all ready or offline sdevs on the channel are EH-finished. 4. If !list_empty(&eh_work_q), invoke scsi_eh_host_reset() ``scsi_eh_host_reset`` This is the last resort. hostt->eh_host_reset_handler() is invoked. If host reset succeeds, all failed scmds on all ready or offline sdevs on the host are EH-finished. 5. If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs() ``scsi_eh_offline_sdevs`` Take all sdevs which still have unrecovered scmds offline and EH-finish the scmds. h](h)}(hgThis function takes four increasingly more severe measures to make failed sdevs ready for new commands.h]hgThis function takes four increasingly more severe measures to make failed sdevs ready for new commands.}(hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMahj, ubjZ)}(hhh]jw)}(hInvoke scsi_eh_stu() h]h)}(hInvoke scsi_eh_stu()h]hInvoke scsi_eh_stu()}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMdhjA ubah}(h]h ]h"]h$]h&]uh1jvhj> ubah}(h]h ]h"]h$]h&]jjjhjjuh1jYhj, ubh)}(h``scsi_eh_stu``h]j] )}(hja h]h scsi_eh_stu}(hjc hhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hj_ ubah}(h]h ]h"]h$]h&]uh1hhhhMfhj, ubjl)}(hX"For each sdev which has failed scmds with valid sense data of which scsi_check_sense()'s verdict is FAILED, START STOP UNIT command is issued w/ start=1. Note that as we explicitly choose error-completed scmds, it is known that lower layers have forgotten about the scmd and we can reuse it for STU. If STU succeeds and the sdev is either offline or ready, all failed scmds on the sdev are EH-finished with scsi_eh_finish_cmd(). *NOTE* If hostt->eh_abort_handler() isn't implemented or failed, we may still have timed out scmds at this point and STU doesn't make lower layers forget about those scmds. Yet, this function EH-finish all scmds on the sdev if STU succeeds leaving lower layers in an inconsistent state. It seems that STU action should be taken only when a sdev has no timed out scmd. [h](h)}(hX,For each sdev which has failed scmds with valid sense data of which scsi_check_sense()'s verdict is FAILED, START STOP UNIT command is issued w/ start=1. Note that as we explicitly choose error-completed scmds, it is known that lower layers have forgotten about the scmd and we can reuse it for STU.h]hX.For each sdev which has failed scmds with valid sense data of which scsi_check_sense()’s verdict is FAILED, START STOP UNIT command is issued w/ start=1. Note that as we explicitly choose error-completed scmds, it is known that lower layers have forgotten about the scmd and we can reuse it for STU.}(hjz hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhhjv ubh)}(hIf STU succeeds and the sdev is either offline or ready, all failed scmds on the sdev are EH-finished with scsi_eh_finish_cmd().h]hIf STU succeeds and the sdev is either offline or ready, all failed scmds on the sdev are EH-finished with scsi_eh_finish_cmd().}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMohjv ubh)}(hXq*NOTE* If hostt->eh_abort_handler() isn't implemented or failed, we may still have timed out scmds at this point and STU doesn't make lower layers forget about those scmds. Yet, this function EH-finish all scmds on the sdev if STU succeeds leaving lower layers in an inconsistent state. It seems that STU action should be taken only when a sdev has no timed out scmd.h](j)}(h*NOTE*h]hNOTE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhXo If hostt->eh_abort_handler() isn’t implemented or failed, we may still have timed out scmds at this point and STU doesn’t make lower layers forget about those scmds. Yet, this function EH-finish all scmds on the sdev if STU succeeds leaving lower layers in an inconsistent state. It seems that STU action should be taken only when a sdev has no timed out scmd.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMshjv ubeh}(h]h ]h"]h$]h&]uh1jkhhhMhhj, ubjZ)}(hhh]jw)}(h?If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset(). h]h)}(h>If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset().h]h>If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset().}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM{hj ubah}(h]h ]h"]h$]h&]uh1jvhj ubah}(h]h ]h"]h$]h&]jjjhjjj Kuh1jYhj, ubh)}(h``scsi_eh_bus_device_reset``h]j] )}(hj h]hscsi_eh_bus_device_reset}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hj ubah}(h]h ]h"]h$]h&]uh1hhhhM}hj, ubjl)}(hXThis action is very similar to scsi_eh_stu() except that, instead of issuing STU, hostt->eh_device_reset_handler() is used. Also, as we're not issuing SCSI commands and resetting clears all scmds on the sdev, there is no need to choose error-completed scmds. h]h)}(hXThis action is very similar to scsi_eh_stu() except that, instead of issuing STU, hostt->eh_device_reset_handler() is used. Also, as we're not issuing SCSI commands and resetting clears all scmds on the sdev, there is no need to choose error-completed scmds.h]hXThis action is very similar to scsi_eh_stu() except that, instead of issuing STU, hostt->eh_device_reset_handler() is used. Also, as we’re not issuing SCSI commands and resetting clears all scmds on the sdev, there is no need to choose error-completed scmds.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jkhhhMhj, ubjZ)}(hhh]jw)}(h7If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset() h]h)}(h6If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset()h]h6If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jvhj ubah}(h]h ]h"]h$]h&]jjjhjjj Kuh1jYhj, ubh)}(h``scsi_eh_bus_reset``h]j] )}(hj+ h]hscsi_eh_bus_reset}(hj- hhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hj) ubah}(h]h ]h"]h$]h&]uh1hhhhMhj, ubjl)}(hhostt->eh_bus_reset_handler() is invoked for each channel with failed scmds. If bus reset succeeds, all failed scmds on all ready or offline sdevs on the channel are EH-finished. h]h)}(hhostt->eh_bus_reset_handler() is invoked for each channel with failed scmds. If bus reset succeeds, all failed scmds on all ready or offline sdevs on the channel are EH-finished.h]hhostt->eh_bus_reset_handler() is invoked for each channel with failed scmds. If bus reset succeeds, all failed scmds on all ready or offline sdevs on the channel are EH-finished.}(hjD hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj@ ubah}(h]h ]h"]h$]h&]uh1jkhhhMhj, ubjZ)}(hhh]jw)}(h8If !list_empty(&eh_work_q), invoke scsi_eh_host_reset() h]h)}(h7If !list_empty(&eh_work_q), invoke scsi_eh_host_reset()h]h7If !list_empty(&eh_work_q), invoke scsi_eh_host_reset()}(hj_ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj[ ubah}(h]h ]h"]h$]h&]uh1jvhjX ubah}(h]h ]h"]h$]h&]jjjhjjj Kuh1jYhj, ubh)}(h``scsi_eh_host_reset``h]j] )}(hj{ h]hscsi_eh_host_reset}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hjy ubah}(h]h ]h"]h$]h&]uh1hhhhMhj, ubjl)}(hThis is the last resort. hostt->eh_host_reset_handler() is invoked. If host reset succeeds, all failed scmds on all ready or offline sdevs on the host are EH-finished. h]h)}(hThis is the last resort. hostt->eh_host_reset_handler() is invoked. If host reset succeeds, all failed scmds on all ready or offline sdevs on the host are EH-finished.h]hThis is the last resort. hostt->eh_host_reset_handler() is invoked. If host reset succeeds, all failed scmds on all ready or offline sdevs on the host are EH-finished.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jkhhhMhj, ubjZ)}(hhh]jw)}(h;If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs() h]h)}(h:If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs()h]h:If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jvhj ubah}(h]h ]h"]h$]h&]jjjhjjj Kuh1jYhj, ubh)}(h``scsi_eh_offline_sdevs``h]j] )}(hj h]hscsi_eh_offline_sdevs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hj ubah}(h]h ]h"]h$]h&]uh1hhhhMhj, ubjl)}(hSTake all sdevs which still have unrecovered scmds offline and EH-finish the scmds. h]h)}(hRTake all sdevs which still have unrecovered scmds offline and EH-finish the scmds.h]hRTake all sdevs which still have unrecovered scmds offline and EH-finish the scmds.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jkhhhMhj, ubeh}(h]h ]h"]h$]h&]uh1jkhhhMahjq ubjZ)}(hhh]jw)}(hXInvoke scsi_eh_flush_done_q(). ``scsi_eh_flush_done_q`` At this point all scmds are recovered (or given up) and put on eh_done_q by scsi_eh_finish_cmd(). This function flushes eh_done_q by either retrying or notifying upper layer of failure of the scmds. h](h)}(hInvoke scsi_eh_flush_done_q().h]hInvoke scsi_eh_flush_done_q().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubjl)}(h``scsi_eh_flush_done_q`` At this point all scmds are recovered (or given up) and put on eh_done_q by scsi_eh_finish_cmd(). This function flushes eh_done_q by either retrying or notifying upper layer of failure of the scmds. h](h)}(h``scsi_eh_flush_done_q``h]j] )}(hjh]hscsi_eh_flush_done_q}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j\ hjubah}(h]h ]h"]h$]h&]uh1hhhhMhjubjl)}(hAt this point all scmds are recovered (or given up) and put on eh_done_q by scsi_eh_finish_cmd(). This function flushes eh_done_q by either retrying or notifying upper layer of failure of the scmds. h]h)}(hAt this point all scmds are recovered (or given up) and put on eh_done_q by scsi_eh_finish_cmd(). This function flushes eh_done_q by either retrying or notifying upper layer of failure of the scmds.h]hAt this point all scmds are recovered (or given up) and put on eh_done_q by scsi_eh_finish_cmd(). This function flushes eh_done_q by either retrying or notifying upper layer of failure of the scmds.}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj.ubah}(h]h ]h"]h$]h&]uh1jkhhhMhjubeh}(h]h ]h"]h$]h&]uh1jkhhhMhjubeh}(h]h ]h"]h$]h&]uh1jvhj ubah}(h]h ]h"]h$]h&]jjjhjjj Kuh1jYhjq ubeh}(h]h ]h"]h$]h&]uh1jkhhhM6hj/ hhubeh}(h]flow-of-controlah ]h"]2.1.3 flow of controlah$]h&]uh1hhjhhhhhM0ubeh}(h]!eh-through-fine-grained-callbacksah ]h"]%2.1 eh through fine-grained callbacksah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h02.2 EH through transportt->eh_strategy_handler()h]h02.2 EH through transportt->eh_strategy_handler()}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjnhhhhhMubh)}(hXtransportt->eh_strategy_handler() is invoked in the place of scsi_unjam_host() and it is responsible for whole recovery process. On completion, the handler should have made lower layers forget about all failed scmds and either ready for new commands or offline. Also, it should perform SCSI EH maintenance chores to maintain integrity of SCSI midlayer. IOW, of the steps described in [2-1-2], all steps except for #1 must be implemented by eh_strategy_handler().h]hXtransportt->eh_strategy_handler() is invoked in the place of scsi_unjam_host() and it is responsible for whole recovery process. On completion, the handler should have made lower layers forget about all failed scmds and either ready for new commands or offline. Also, it should perform SCSI EH maintenance chores to maintain integrity of SCSI midlayer. IOW, of the steps described in [2-1-2], all steps except for #1 must be implemented by eh_strategy_handler().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjnhhubh)}(hhh](h)}(hD2.2.1 Pre transportt->eh_strategy_handler() SCSI midlayer conditionsh]hD2.2.1 Pre transportt->eh_strategy_handler() SCSI midlayer conditions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubjl)}(hThe following conditions are true on entry to the handler. - Each failed scmd's eh_flags field is set appropriately. - Each failed scmd is linked on scmd->eh_cmd_q by scmd->eh_entry. - SHOST_RECOVERY is set. - shost->host_failed == shost->host_busy h](h)}(h:The following conditions are true on entry to the handler.h]h:The following conditions are true on entry to the handler.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubjr)}(hhh](jw)}(h8Each failed scmd's eh_flags field is set appropriately. h]h)}(h7Each failed scmd's eh_flags field is set appropriately.h]h9Each failed scmd’s eh_flags field is set appropriately.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(h@Each failed scmd is linked on scmd->eh_cmd_q by scmd->eh_entry. h]h)}(h?Each failed scmd is linked on scmd->eh_cmd_q by scmd->eh_entry.h]h?Each failed scmd is linked on scmd->eh_cmd_q by scmd->eh_entry.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hSHOST_RECOVERY is set. h]h)}(hSHOST_RECOVERY is set.h]hSHOST_RECOVERY is set.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(h(shost->host_failed == shost->host_busy h]h)}(h&shost->host_failed == shost->host_busyh]h&shost->host_failed == shost->host_busy}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhMhjubeh}(h]h ]h"]h$]h&]uh1jkhhhMhjhhubeh}(h];pre-transportt-eh-strategy-handler-scsi-midlayer-conditionsah ]h"]D2.2.1 pre transportt->eh_strategy_handler() scsi midlayer conditionsah$]h&]uh1hhjnhhhhhMubh)}(hhh](h)}(hE2.2.2 Post transportt->eh_strategy_handler() SCSI midlayer conditionsh]hE2.2.2 Post transportt->eh_strategy_handler() SCSI midlayer conditions}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj'hhhhhMubjl)}(hXWThe following conditions must be true on exit from the handler. - shost->host_failed is zero. - shost->eh_cmd_q is cleared. - Each scmd->eh_entry is cleared. - Either scsi_queue_insert() or scsi_finish_command() is called on each scmd. Note that the handler is free to use scmd->retries and ->allowed to limit the number of retries. h](h)}(h?The following conditions must be true on exit from the handler.h]h?The following conditions must be true on exit from the handler.}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj8ubjr)}(hhh](jw)}(hshost->host_failed is zero. h]h)}(hshost->host_failed is zero.h]hshost->host_failed is zero.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjMubah}(h]h ]h"]h$]h&]uh1jvhjJubjw)}(hshost->eh_cmd_q is cleared. h]h)}(hshost->eh_cmd_q is cleared.h]hshost->eh_cmd_q is cleared.}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjeubah}(h]h ]h"]h$]h&]uh1jvhjJubjw)}(h Each scmd->eh_entry is cleared. h]h)}(hEach scmd->eh_entry is cleared.h]hEach scmd->eh_entry is cleared.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj}ubah}(h]h ]h"]h$]h&]uh1jvhjJubjw)}(hEither scsi_queue_insert() or scsi_finish_command() is called on each scmd. Note that the handler is free to use scmd->retries and ->allowed to limit the number of retries. h]h)}(hEither scsi_queue_insert() or scsi_finish_command() is called on each scmd. Note that the handler is free to use scmd->retries and ->allowed to limit the number of retries.h]hEither scsi_queue_insert() or scsi_finish_command() is called on each scmd. Note that the handler is free to use scmd->retries and ->allowed to limit the number of retries.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjJubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhMhj8ubeh}(h]h ]h"]h$]h&]uh1jkhhhMhj'hhubeh}(h]eh_strategy_handler() scsi midlayer conditionsah$]h&]uh1hhjnhhhhhMubh)}(hhh](h)}(h2.2.3 Things to considerh]h2.2.3 Things to consider}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubjl)}(hX- Know that timed out scmds are still active on lower layers. Make lower layers forget about them before doing anything else with those scmds. - For consistency, when accessing/modifying shost data structure, grab shost->host_lock. - On completion, each failed sdev must have forgotten about all active scmds. - On completion, each failed sdev must be ready for new commands or offline. h]jr)}(hhh](jw)}(hKnow that timed out scmds are still active on lower layers. Make lower layers forget about them before doing anything else with those scmds. h]h)}(hKnow that timed out scmds are still active on lower layers. Make lower layers forget about them before doing anything else with those scmds.h]hKnow that timed out scmds are still active on lower layers. Make lower layers forget about them before doing anything else with those scmds.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hWFor consistency, when accessing/modifying shost data structure, grab shost->host_lock. h]h)}(hVFor consistency, when accessing/modifying shost data structure, grab shost->host_lock.h]hVFor consistency, when accessing/modifying shost data structure, grab shost->host_lock.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hLOn completion, each failed sdev must have forgotten about all active scmds. h]h)}(hKOn completion, each failed sdev must have forgotten about all active scmds.h]hKOn completion, each failed sdev must have forgotten about all active scmds.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jvhjubjw)}(hLOn completion, each failed sdev must be ready for new commands or offline. h]h)}(hJOn completion, each failed sdev must be ready for new commands or offline.h]hJOn completion, each failed sdev must be ready for new commands or offline.}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj!ubah}(h]h ]h"]h$]h&]uh1jvhjubeh}(h]h ]h"]h$]h&]j&j'uh1jqhhhMhjubah}(h]h ]h"]h$]h&]uh1jkhhhMhjhhubh)}(hTejun Heo htejun@gmail.comh](h Tejun Heo }(hjEhhhNhNubh reference)}(hhtejun@gmail.comh]hhtejun@gmail.com}(hjOhhhNhNubah}(h]h ]h"]h$]h&]refurimailto:htejun@gmail.comuh1jMhjEubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h11th September 2005h]h11th September 2005}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]things-to-considerah ]h"]2.2.3 things to considerah$]h&]uh1hhjnhhhhhMubeh}(h])eh-through-transportt-eh-strategy-handlerah ]h"]02.2 eh through transportt->eh_strategy_handler()ah$]h&]uh1hhjhhhhhMubeh}(h]how-scsi-eh-worksah ]h"]2. how scsi eh worksah$]h&]uh1hhhhhhhhKubeh}(h]scsi-ehah ]h"]scsi ehah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjjjjjjjj3j0jjjjjjjjjkjhjjj, j) jcj`jj}j$j!jjjxjuu nametypes}(jjjjj3jjjjjkjj, jcjj$jjxuh}(jhjhjhjjj0j>jj6jjjjjjjhjjjj) jj`j/ j}jnj!jjj'juju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages](hsystem_message)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "4" (ordinal 4)h]h>Enumerated list start value not ordinal-1: “4” (ordinal 4)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKuh1jhjq ubj)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "2" (ordinal 2)h]h>Enumerated list start value not ordinal-1: “2” (ordinal 2)}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6ubah}(h]h ]h"]h$]h&]levelKtypej3sourcehlineKuh1jhj, ubj)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "3" (ordinal 3)h]h>Enumerated list start value not ordinal-1: “3” (ordinal 3)}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjQubah}(h]h ]h"]h$]h&]levelKtypej3sourcehlineKuh1jhj, ubj)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "4" (ordinal 4)h]h>Enumerated list start value not ordinal-1: “4” (ordinal 4)}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhjlubah}(h]h ]h"]h$]h&]levelKtypej3sourcehlineKuh1jhj, ubj)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "5" (ordinal 5)h]h>Enumerated list start value not ordinal-1: “5” (ordinal 5)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypej3sourcehlineKuh1jhj, ubj)}(hhh]h)}(h:Enumerated list start value not ordinal-1: "5" (ordinal 5)h]h>Enumerated list start value not ordinal-1: “5” (ordinal 5)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypej3sourcehlineKuh1jhjq ubetransform_messages] transformerN include_log] decorationNhhub.