doc/sg_reset.8 - platform/external/sg3_utils - Git at Google

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