scsi: docs: convert scsi_eh.txt to ReST

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

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.

Origins of commands

   ppa

   qlogicfas

   scsi-changer

   scsi_eh

   scsi_transport_srp/figures

.. SPDX-License-Identifier: GPL-2.0

=======

SCSI EH

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

=======

This document describes SCSI midlayer error handling infrastructure.

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

information regarding SCSI midlayer.

TABLE OF CONTENTS

.. TABLE OF CONTENTS

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

       [1-1] struct scsi_cmnd

   	[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

scmd has two list_head's to link itself into lists.  The two are

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

command by calling scsi_done callback passed from midlayer when

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

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

with the command.

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

	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.

[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

function

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

    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

 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.

[1-4] How EH takes over

1.4 How EH takes over

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

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

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

ways.

 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

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

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

considered to fail always.

::

    int (* eh_abort_handler)(struct scsi_cmnd *);

    int (* eh_device_reset_handler)(struct scsi_cmnd *);

    int (* eh_bus_reset_handler)(struct scsi_cmnd *);

scmd->allowed.

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

2.1.2 Flow of scmds through EH

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

 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

	- set SHOST_RECOVERY

	- shost->host_failed++

    LOCKING: shost->host_lock

    :LOCKING: shost->host_lock

 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.

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

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

             consistency)

 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()

	- 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

 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

	     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

    :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().

<<scsi_unjam_host>>

``scsi_unjam_host``

    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

    2. Invoke scsi_eh_get_sense.

    <<scsi_eh_get_sense>>

    ``scsi_eh_get_sense``

	This action is taken for each error-completed

	(!SCSI_EH_CANCEL_CMD) commands without valid sense data.  Most

    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

	no_async_abort is enabled in the host template.

    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

	make failed sdevs ready for new commands.

	1. Invoke scsi_eh_stu()

	<<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,

	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,

	    instead of issuing STU, hostt->eh_device_reset_handler()

	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

	    with failed scmds.  If bus reset succeeds, all failed

	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()

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

	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

	    and EH-finish the scmds.

    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

	    put on eh_done_q by scsi_eh_finish_cmd().  This function

	    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

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

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.

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

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

   lower layers forget about them before doing anything else with

   offline.

--

Tejun Heo

htejun@gmail.com

11th September 2005