scsi: docs: convert scsi_eh.txt to ReST

==============

==============

This chapter describes how errors are handled under libata. Readers are

This chapter describes how errors are handled under libata. Readers are

advised to read SCSI EH (Documentation/scsi/scsi_eh.txt) and ATA

advised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATA

exceptions doc first.

exceptions doc first.

Origins of commands

Origins of commands

   ppa

   ppa

   qlogicfas

   qlogicfas

   scsi-changer

   scsi-changer

   scsi_eh

   scsi_transport_srp/figures

   scsi_transport_srp/figures

.. SPDX-License-Identifier: GPL-2.0

=======

SCSI EH

SCSI EH

======================================

=======

This document describes SCSI midlayer error handling infrastructure.

This document describes SCSI midlayer error handling infrastructure.

Please refer to Documentation/scsi/scsi_mid_low_api.txt for more

Please refer to Documentation/scsi/scsi_mid_low_api.txt for more

information regarding SCSI midlayer.

information regarding SCSI midlayer.

TABLE OF CONTENTS

.. TABLE OF CONTENTS

   [1] How SCSI commands travel through the midlayer and to EH

   [1] How SCSI commands travel through the midlayer and to EH

       [1-1] struct scsi_cmnd

       [1-1] struct scsi_cmnd

   	[2-2-3] Things to consider

   	[2-2-3] Things to consider

[1] How SCSI commands travel through the midlayer and to EH

1. How SCSI commands travel through the midlayer and to EH

==========================================================

[1-1] struct scsi_cmnd

1.1 struct scsi_cmnd

--------------------

Each SCSI command is represented with struct scsi_cmnd (== scmd).  A

Each 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 has two list_head's to link itself into lists.  The two are

discussion.

discussion.

[1-2] How do scmd's get completed?

1.2 How do scmd's get completed?

--------------------------------

Once LLDD gets hold of a scmd, either the LLDD will complete the

Once LLDD gets hold of a scmd, either the LLDD will complete the

command by calling scsi_done callback passed from midlayer when

command by calling scsi_done callback passed from midlayer when

invoking hostt->queuecommand() or the block layer will time it out.

invoking hostt->queuecommand() or the block layer will time it out.

[1-2-1] Completing a scmd w/ scsi_done

1.2.1 Completing a scmd w/ scsi_done

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For all non-EH commands, scsi_done() is the completion callback.  It

For all non-EH commands, scsi_done() is the completion callback.  It

just calls blk_complete_request() to delete the block layer timer and

just calls blk_complete_request() to delete the block layer timer and

with the command.

with the command.

 - SUCCESS

 - SUCCESS

	scsi_finish_command() is invoked for the command.  The

	scsi_finish_command() is invoked for the command.  The

	function does some maintenance chores and then calls

	function does some maintenance chores and then calls

	scsi_io_completion() to finish the I/O.

	scsi_io_completion() to finish the I/O.

	of the data in case of an error.

	of the data in case of an error.

 - NEEDS_RETRY

 - NEEDS_RETRY

 - ADD_TO_MLQUEUE

 - ADD_TO_MLQUEUE

	scmd is requeued to blk queue.

	scmd is requeued to blk queue.

 - otherwise

 - otherwise

	scsi_eh_scmd_add(scmd) is invoked for the command.  See

	scsi_eh_scmd_add(scmd) is invoked for the command.  See

	[1-3] for details of this function.

	[1-3] for details of this function.

[1-2-2] Completing a scmd w/ timeout

1.2.2 Completing a scmd w/ timeout

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The timeout handler is scsi_times_out().  When a timeout occurs, this

The timeout handler is scsi_times_out().  When a timeout occurs, this

function

function

 3. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the

 3. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the

    command.  See [1-4] for more information.

    command.  See [1-4] for more information.

[1-3] Asynchronous command aborts

1.3 Asynchronous command aborts

-------------------------------

 After a timeout occurs a command abort is scheduled from

 After a timeout occurs a command abort is scheduled from

 scsi_abort_command(). If the abort is successful the command

 scsi_abort_command(). If the abort is successful the command

 will either be retried (if the number of retries is not exhausted)

 will either be retried (if the number of retries is not exhausted)

 or terminated with DID_TIME_OUT.

 or terminated with DID_TIME_OUT.

 Otherwise scsi_eh_scmd_add() is invoked for the command.

 Otherwise scsi_eh_scmd_add() is invoked for the command.

 See [1-4] for more information.

 See [1-4] for more information.

[1-4] How EH takes over

1.4 How EH takes over

---------------------

scmds enter EH via scsi_eh_scmd_add(), which does the following.

scmds enter EH via scsi_eh_scmd_add(), which does the following.

forget about - timed out scmds later.

forget about - timed out scmds later.

[2] How SCSI EH works

2. How SCSI EH works

====================

LLDD's can implement SCSI EH actions in one of the following two

LLDD's can implement SCSI EH actions in one of the following two

ways.

ways.

 4. Kicks queues in all devices on the host in the asses

 4. Kicks queues in all devices on the host in the asses

[2-1] EH through fine-grained callbacks

2.1 EH through fine-grained callbacks

-------------------------------------

[2-1-1] Overview

2.1.1 Overview

^^^^^^^^^^^^^^

If eh_strategy_handler() is not present, SCSI midlayer takes charge

If eh_strategy_handler() is not present, SCSI midlayer takes charge

of driving error handling.  EH's goals are two - make LLDD, host and

of driving error handling.  EH's goals are two - make LLDD, host and

hostt EH callbacks.  Callbacks may be omitted and omitted ones are

hostt EH callbacks.  Callbacks may be omitted and omitted ones are

considered to fail always.

considered to fail always.

::

    int (* eh_abort_handler)(struct scsi_cmnd *);

    int (* eh_abort_handler)(struct scsi_cmnd *);

    int (* eh_device_reset_handler)(struct scsi_cmnd *);

    int (* eh_device_reset_handler)(struct scsi_cmnd *);

    int (* eh_bus_reset_handler)(struct scsi_cmnd *);

    int (* eh_bus_reset_handler)(struct scsi_cmnd *);

scmd->allowed.

scmd->allowed.

[2-1-2] Flow of scmds through EH

2.1.2 Flow of scmds through EH

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 1. Error completion / time out

 1. Error completion / time out

    ACTION: scsi_eh_scmd_add() is invoked for scmd

    :ACTION: scsi_eh_scmd_add() is invoked for scmd

	- add scmd to shost->eh_cmd_q

	- add scmd to shost->eh_cmd_q

	- set SHOST_RECOVERY

	- set SHOST_RECOVERY

	- shost->host_failed++

	- shost->host_failed++

    LOCKING: shost->host_lock

    :LOCKING: shost->host_lock

 2. EH starts

 2. EH starts

    ACTION: move all scmds to EH's local eh_work_q.  shost->eh_cmd_q

    :ACTION: move all scmds to EH's local eh_work_q.  shost->eh_cmd_q

	     is cleared.

	     is cleared.

    LOCKING: shost->host_lock (not strictly necessary, just for

    :LOCKING: shost->host_lock (not strictly necessary, just for

             consistency)

             consistency)

 3. scmd recovered

 3. scmd recovered

    ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd

    :ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd

	- scsi_setup_cmd_retry()

	- scsi_setup_cmd_retry()

	- move from local eh_work_q to local eh_done_q

	- move from local eh_work_q to local eh_done_q

    LOCKING: none

    CONCURRENCY: at most one thread per separate eh_work_q to

    :LOCKING: none

    :CONCURRENCY: at most one thread per separate eh_work_q to

		  keep queue manipulation lockless

		  keep queue manipulation lockless

 4. EH completes

 4. EH completes

    ACTION: scsi_eh_flush_done_q() retries scmds or notifies upper

    :ACTION: scsi_eh_flush_done_q() retries scmds or notifies upper

	     layer of failure. May be called concurrently but must have

	     layer of failure. May be called concurrently but must have

	     a no more than one thread per separate eh_work_q to

	     a no more than one thread per separate eh_work_q to

	     manipulate the queue locklessly

	     manipulate the queue locklessly

	     - scmd is removed from eh_done_q and scmd->eh_entry is cleared

	     - scmd is removed from eh_done_q and scmd->eh_entry is cleared

	     - if retry is necessary, scmd is requeued using

	     - if retry is necessary, scmd is requeued using

	       scsi_queue_insert()

	       scsi_queue_insert()

	     - otherwise, scsi_finish_command() is invoked for scmd

	     - otherwise, scsi_finish_command() is invoked for scmd

	     - zero shost->host_failed

	     - zero shost->host_failed

    LOCKING: queue or finish function performs appropriate locking

    :LOCKING: queue or finish function performs appropriate locking

[2-1-3] Flow of control

2.1.3 Flow of control

^^^^^^^^^^^^^^^^^^^^^^

 EH through fine-grained callbacks start from scsi_unjam_host().

 EH through fine-grained callbacks start from scsi_unjam_host().

<<scsi_unjam_host>>

``scsi_unjam_host``

    1. Lock shost->host_lock, splice_init shost->eh_cmd_q into local

    1. 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

       eh_work_q and unlock host_lock.  Note that shost->eh_cmd_q is

    2. Invoke scsi_eh_get_sense.

    2. Invoke scsi_eh_get_sense.

    <<scsi_eh_get_sense>>

    ``scsi_eh_get_sense``

	This action is taken for each error-completed

	This action is taken for each error-completed

	(!SCSI_EH_CANCEL_CMD) commands without valid sense data.  Most

	(!SCSI_EH_CANCEL_CMD) commands without valid sense data.  Most

    3. If !list_empty(&eh_work_q), invoke scsi_eh_abort_cmds().

    3. If !list_empty(&eh_work_q), invoke scsi_eh_abort_cmds().

    <<scsi_eh_abort_cmds>>

    ``scsi_eh_abort_cmds``

	This action is taken for each timed out command when

	This action is taken for each timed out command when

	no_async_abort is enabled in the host template.

	no_async_abort is enabled in the host template.

    4. If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs()

    4. If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs()

    <<scsi_eh_ready_devs>>

    ``scsi_eh_ready_devs``

	This function takes four increasingly more severe measures to

	This function takes four increasingly more severe measures to

	make failed sdevs ready for new commands.

	make failed sdevs ready for new commands.

	1. Invoke scsi_eh_stu()

	1. Invoke scsi_eh_stu()

	<<scsi_eh_stu>>

	``scsi_eh_stu``

	    For each sdev which has failed scmds with valid sense data

	    For each sdev which has failed scmds with valid sense data

	    of which scsi_check_sense()'s verdict is FAILED,

	    of which scsi_check_sense()'s verdict is FAILED,

	2. If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset().

	2. If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset().

	<<scsi_eh_bus_device_reset>>

	``scsi_eh_bus_device_reset``

	    This action is very similar to scsi_eh_stu() except that,

	    This action is very similar to scsi_eh_stu() except that,

	    instead of issuing STU, hostt->eh_device_reset_handler()

	    instead of issuing STU, hostt->eh_device_reset_handler()

	3. If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset()

	3. If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset()

	<<scsi_eh_bus_reset>>

	``scsi_eh_bus_reset``

	    hostt->eh_bus_reset_handler() is invoked for each channel

	    hostt->eh_bus_reset_handler() is invoked for each channel

	    with failed scmds.  If bus reset succeeds, all failed

	    with failed scmds.  If bus reset succeeds, all failed

	4. If !list_empty(&eh_work_q), invoke scsi_eh_host_reset()

	4. If !list_empty(&eh_work_q), invoke scsi_eh_host_reset()

	<<scsi_eh_host_reset>>

	``scsi_eh_host_reset``

	    This is the last resort.  hostt->eh_host_reset_handler()

	    This is the last resort.  hostt->eh_host_reset_handler()

	    is invoked.  If host reset succeeds, all failed scmds on

	    is invoked.  If host reset succeeds, all failed scmds on

	5. If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs()

	5. If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs()

	<<scsi_eh_offline_sdevs>>

	``scsi_eh_offline_sdevs``

	    Take all sdevs which still have unrecovered scmds offline

	    Take all sdevs which still have unrecovered scmds offline

	    and EH-finish the scmds.

	    and EH-finish the scmds.

    5. Invoke scsi_eh_flush_done_q().

    5. Invoke scsi_eh_flush_done_q().

	<<scsi_eh_flush_done_q>>

	``scsi_eh_flush_done_q``

	    At this point all scmds are recovered (or given up) and

	    At this point all scmds are recovered (or given up) and

	    put on eh_done_q by scsi_eh_finish_cmd().  This function

	    put on eh_done_q by scsi_eh_finish_cmd().  This function

	    layer of failure of the scmds.

	    layer of failure of the scmds.

[2-2] EH through transportt->eh_strategy_handler()

2.2 EH through transportt->eh_strategy_handler()

------------------------------------------------

transportt->eh_strategy_handler() is invoked in the place of

transportt->eh_strategy_handler() is invoked in the place of

scsi_unjam_host() and it is responsible for whole recovery process.

scsi_unjam_host() and it is responsible for whole recovery process.

except for #1 must be implemented by eh_strategy_handler().

except for #1 must be implemented by eh_strategy_handler().

[2-2-1] Pre transportt->eh_strategy_handler() SCSI midlayer conditions

2.2.1 Pre transportt->eh_strategy_handler() SCSI midlayer conditions

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 The following conditions are true on entry to the handler.

 The following conditions are true on entry to the handler.

 - shost->host_failed == shost->host_busy

 - shost->host_failed == shost->host_busy

[2-2-2] Post transportt->eh_strategy_handler() SCSI midlayer conditions

2.2.2 Post transportt->eh_strategy_handler() SCSI midlayer conditions

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 The following conditions must be true on exit from the handler.

 The following conditions must be true on exit from the handler.

   ->allowed to limit the number of retries.

   ->allowed to limit the number of retries.

[2-2-3] Things to consider

2.2.3 Things to consider

^^^^^^^^^^^^^^^^^^^^^^^^

 - Know that timed out scmds are still active on lower layers.  Make

 - Know that timed out scmds are still active on lower layers.  Make

   lower layers forget about them before doing anything else with

   lower layers forget about them before doing anything else with

   offline.

   offline.

--

Tejun Heo

Tejun Heo

htejun@gmail.com

htejun@gmail.com

11th September 2005

11th September 2005