scsi: docs: update notes about scsi_times_out

Commit Message

Khazhy Kumykov Dec. 8, 2021, 10:56 p.m. UTC

eh_timed_out() is not limited by scmd->allowed, and can reset timer
forever, and retries happen in the abort handler.

Fixes: c829c394165f ("[SCSI] FC transport : Avoid device offline cases by stalling aborts until device unblocked")

Signed-off-by: Khazhismel Kumykov <[e-mail]>
---
 Documentation/scsi/scsi_eh.rst | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

I'm by no means a scsi expert, but this section didn't seem to line up
with the code that's actually written. Aiming to at least save the
confusion for the next person :) As written, it seems like scsi drivers
implementing eh_timed_out can only issue RESET_TIMER a finite number of
times, but e.g. virtio_scsi relies on being able to reset indefinitely.

(thanks bart for the pointer to where the RESET_TIMER change happened!)

Comments

Bart Van Assche Dec. 9, 2021, 7:44 p.m. UTC | #1

On 12/8/21 2:56 PM, Khazhismel Kumykov wrote:
> + 2. scsi_abort_command() is invoked to schedule an asynchrous abort. which may
                                                                       ^^^^^^^
                                                            Should the dot perhaps be removed?
> +    issue a retry scmd->allowed + 1 times.  Asynchronous abort are not invoked
                                                             ^^^^
                                                        abort -> aborts?
> +    for commands which the SCSI_EH_ABORT_SCHEDULED flag is set (this indicates
                     ^^^^^
                 which -> for which?
> +    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 case Step #3 is taken.
>   
>    3. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the
>       command.  See [1-4] for more information.

Thanks,

Bart.

Patch

diff --git a/Documentation/scsi/scsi_eh.rst b/Documentation/scsi/scsi_eh.rst
index 7d78c2475615..4c56a33a716f 100644
--- a/Documentation/scsi/scsi_eh.rst
+++ b/Documentation/scsi/scsi_eh.rst
@@ -95,19 +95,18 @@  function
 
     - BLK_EH_RESET_TIMER
 	This indicates that more time is required to finish the
-	command.  Timer is restarted.  This action is counted as a
-	retry and only allowed scmd->allowed + 1(!) times.  Once the
-	limit is reached, action for BLK_EH_DONE is taken instead.
+	command.  Timer is restarted.
 
     - BLK_EH_DONE
         eh_timed_out() callback did not handle the command.
 	Step #2 is taken.
 
- 2. scsi_abort_command() is invoked to schedule an asynchrous abort.
-    Asynchronous abort are not invoked for commands 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),
-    or when the EH deadline is expired. In these case Step #3 is taken.
+ 2. scsi_abort_command() is invoked to schedule an asynchrous abort. which may
+    issue a retry scmd->allowed + 1 times.  Asynchronous abort are not invoked
+    for commands 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 case Step #3 is taken.
 
  3. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the
     command.  See [1-4] for more information.