Documentation/scsi/scsi_eh.rst

Source file repositories/reference/linux-study-clean/Documentation/scsi/scsi_eh.rst

File Facts

System
Linux kernel
Corpus path
Documentation/scsi/scsi_eh.rst
Extension
.rst
Size
16356 bytes
Lines
486
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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.rst for more
information regarding SCSI midlayer.

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


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

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


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

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

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

 - 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

Annotation

Implementation Notes