136 lines
6.2 KiB
Groff
136 lines
6.2 KiB
Groff
.TH SG_RESET "8" "March 2022" "sg3_utils\-1.48" SG3_UTILS
|
|
.SH NAME
|
|
sg_reset \- sends SCSI device, target, bus or host reset; or checks reset
|
|
state
|
|
.SH SYNOPSIS
|
|
.B sg_reset
|
|
[\fI\-\-bus\fR] [\fI\-\-device\fR] [\fI\-\-help\fR] [\fI\-\-host\fR]
|
|
[\fI\-\-no-esc\fR] [\fI\-\-target\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
|
|
\fIDEVICE\fR
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
.PP
|
|
The sg_reset utility with no options (just a \fIDEVICE\fR) reports on the
|
|
reset state (e.g. if a reset is underway) of the \fIDEVICE\fR. When given
|
|
a \fI\-\-device\fR, \fI\-\-target\fR, \fI\-\-bus\fR or \fI\-\-host\fR
|
|
option it requests a device, target, bus or host reset respectively.
|
|
.PP
|
|
A device reset is applied to the Logical Unit (LU) corresponding to
|
|
\fIDEVICE\fR. It is most likely implemented by a Low level Driver (LLD)
|
|
in Linux as a LOGICAL UNIT RESET task management function.
|
|
.PP
|
|
The ability to reset a SCSI target was added in Linux kernel 2.6.27 . A LLD
|
|
may send Low level Drivers (LLDs) the I_T NEXUS RESET task management
|
|
function. Alternatively it may use a transport mechanism to do the same
|
|
thing (e.g. a hard reset on the link containing a SAS target).
|
|
.PP
|
|
In the Linux kernel 2.6 and 3 series this utility can be called on sd,
|
|
sr (cd/dvd), st or sg device nodes; if the user has appropriate permissions.
|
|
.PP
|
|
Users of this utility can check whether a reset recovery is already underway
|
|
before trying to send a new reset with this utility. Calling this utility
|
|
with no options, just the \fIDEVICE\fR, will do such a check.
|
|
.SH OPTIONS
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-bus\fR
|
|
attempt a SCSI bus reset. A bus reset is a SCSI Parallel Interface (SPI)
|
|
concept not found in modern transports. A recent LLD may implement it as
|
|
a series of resets on targets that might be considered as siblings to the
|
|
target on the \fIDEVICE\fR path.
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-device\fR
|
|
attempt a SCSI device reset. This would typically involve sending a LOGICAL
|
|
UNIT RESET task management function to \fIDEVICE\fR.
|
|
.TP
|
|
\fB\-z\fR, \fB\-\-help\fR
|
|
print the usage message then exit.
|
|
.TP
|
|
\fB\-H\fR, \fB\-\-host\fR
|
|
attempt a host reset. The "host" in this context is often called
|
|
a Host Bus Adapter (HBA) and contains one or more SCSI initiators.
|
|
.TP
|
|
\fB\-N\fR, \fB\-\-no\-esc\fR
|
|
without this option, if a device reset (\fI\-\-device\fR) fails then it
|
|
will escalate to a target reset. And if a target reset (\fI\-\-target\fR)
|
|
fails then it will escalate to a bus reset. And if a bus
|
|
reset (\fI\-\-bus\fR) fails then it will escalate to a host reset. With this
|
|
option only the requested reset is attempted. An alternate option name of
|
|
\fI\-\-no-escalate\fR is also accepted.
|
|
.TP
|
|
\fB\-\-no\-escalate\fR
|
|
The same as \fB\-N\fR, \fB\-\-no\-esc\fR.
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-target\fR
|
|
attempt a SCSI target reset. A SCSI target contains one or more LUs. This
|
|
would typically involve sending a I_T NEXUS RESET task management function
|
|
to \fIDEVICE\fR There may be a transport action that is equivalent (e.g.
|
|
in SAS a hard reset on the link that contains the target).
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-verbose\fR
|
|
increase the degree of verbosity (debug messages).
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-version\fR
|
|
prints the version string then exits.
|
|
.SH NOTES
|
|
The error recovery code within the Linux kernel (SCSI mid\-level) when faced
|
|
with a SCSI command timing out and no response from the device (LU) does the
|
|
following. First it tries a device reset and if that is not successful tries
|
|
a target reset. If that is not successful it tries a bus reset. If that is
|
|
not successful it tries a host reset. The "device,target,bus,host" order is
|
|
the reset escalation that the \fI\-\-no-esc\fR option attempts to stop. In
|
|
large storage configurations the escalation may be (very) undesirable.
|
|
.PP
|
|
This utility calls the SG_SCSI_RESET ioctl and as of lk 3.10.7 the
|
|
\fI\-\-no-esc\fR option is not supported. Patches to implement this
|
|
functionality may be accepted in lk 3.18 or 3.19 .
|
|
.PP
|
|
SAM\-4 and 5 define a hard reset, a LOGICAL UNIT RESET and a I_T NEXUS
|
|
RESET. A hard reset is defined to be a power on condition, a microcode
|
|
change or a transport reset event. LOGICAL UNIT RESET and I_T NEXUS
|
|
RESET can be requested via task management functions (and support for
|
|
LOGICAL UNIT RESET is mandatory). In Linux the SCSI subsystem leaves it up
|
|
to the LLDs as to exactly what type (if any) of reset is performed.
|
|
The "bus reset" is SCSI Parallel Interface (SPI) concept that may not map
|
|
well to recent SCSI transports so it may be a dummy operation. A "host reset"
|
|
attempts to re\-initialize the HBA that the request passes through en route
|
|
to the \fIDEVICE\fR. Note that a "host reset" and a "bus reset" may cause
|
|
collateral damage.
|
|
.PP
|
|
This utility does not allow individual SCSI commands to be aborted. SAM\-4
|
|
defines ABORT TASK and ABORT TASK SET task management functions for that.
|
|
.PP
|
|
Prior to SAM\-3 there was a TARGET RESET task management function. And in
|
|
SAM\-4 I_T NEXUS RESET appeared which seems closely related: the "I_T"
|
|
stands for Initiator\-Target.
|
|
.PP
|
|
Transports may have their own types of resets not supported by this utility.
|
|
For example SAS has a link reset in which both ends of a physical link (e.g.
|
|
between a SAS expander and a SAS tape drive) renegotiate their connection.
|
|
.PP
|
|
Prior to version 0.57 of this utility the command line had short options
|
|
only (e.g. \fI\-d\fR but not \fI\-\-device\fR). Also \fI\-h\fR invoked a host
|
|
reset while in the current version \fI\-h\fR is equivalent to \fI\-\-help\fR
|
|
and both \fI\-H\fR and \fI\-\-host\fR invoke a host reset. For backward
|
|
compatibility define the environment variable SG3_UTILS_OLD_OPTS or
|
|
SG_RESET_OLD_OPTS . In this case \fI\-h\fR will invoke a host reset and the
|
|
output will be verbose as it was previously (equivalent to using the
|
|
\fI\-\-verbose\fR option now).
|
|
For example:
|
|
.PP
|
|
SG_RESET_OLD_OPTS=1 sg_reset \-h /dev/sg1
|
|
.br
|
|
sg_reset: starting host reset
|
|
.br
|
|
sg_reset: completed host reset
|
|
.SH ENVIRONMENT VARIABLES
|
|
Since sg3_utils version 1.23 the environment variables SG3_UTILS_OLD_OPTS
|
|
or SG_RESET_OLD_OPTS can be given. When either is present this utility will
|
|
expect the older command line options as outlined in the NOTES section.
|
|
.SH AUTHORS
|
|
Written by Douglas Gilbert.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 1999\-2022 Douglas Gilbert
|
|
.br
|
|
This software is distributed under the GPL version 2. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|