diff options
Diffstat (limited to 'doc/sg_reset.8')
-rw-r--r-- | doc/sg_reset.8 | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/doc/sg_reset.8 b/doc/sg_reset.8 new file mode 100644 index 00000000..7406fa68 --- /dev/null +++ b/doc/sg_reset.8 @@ -0,0 +1,135 @@ +.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. |