From cee35c89cc98e880c7aa52e7b900363ae74e9653 Mon Sep 17 00:00:00 2001 From: Douglas Gilbert Date: Sat, 4 Dec 2021 00:11:48 +0000 Subject: sg_z_act_query: fix usage call git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@924 6180dd3e-e324-4e3e-922d-17de1ae2f315 --- doc/sg3_utils.8 | 44 +++++++++++++++++++++++++++++++++++++++++++- doc/sg_z_act_query.8 | 8 ++++---- 2 files changed, 47 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/sg3_utils.8 b/doc/sg3_utils.8 index abe07d82..25a0d0b6 100644 --- a/doc/sg3_utils.8 +++ b/doc/sg3_utils.8 @@ -1,4 +1,4 @@ -.TH SG3_UTILS "8" "November 2021" "sg3_utils\-1.48" SG3_UTILS +.TH SG3_UTILS "8" "December 2021" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg3_utils \- a package of utilities for sending SCSI commands .SH SYNOPSIS @@ -779,6 +779,48 @@ Windows may open a file in text rather than binary mode). .PP Some utilities that the author has found useful have been placed in the 'utils' subdirectory. +.SH DEBUGGING +Each utility and most scripts have a \fI\-\-verbose\fR option (short +form: \fI\-v\fR) that can be used multiple times to increase the verbosity +of the output to aid debugging. Normal output (if any) is sent to stdout +while verbose output (and error output) is sent to stderr. This may be +important when the (normal output) of a utility is being piped to another +command (e.g. the grep command to find a particular field in the output). +.PP +The Linux SCSI subsystem has a pseudo file for getting and changing the SCSI +logging level: /proc/sys/dev/scsi/logging_level . The scsi_logging_level +script in this package can be used to manipulate the logging level in a +command line friendly way. See its manpage. +.PP +The logging level runs from 0 (no logging and the default) to 7 (lots of +logging) and applies to all storage devices that use the SCSI subsystem. +The logging output goes to "the log" which is often the /var/log/syslog +file. +.PP +The Linux SCSI generic (sg) driver is often used under the utilities in +this package. It uses a seldom (otherwise) used logging type of +SCSI_LOG_TIMEOUT. An example of its use to turn on full debugging is: +.PP + scsi_logging_level \-s \-T 7 +.PP +To reduce the amount of output to only error paths, the following is +suggested: +.PP + scsi_logging_level \-s \-T 3 +.PP +And to turn off logging in the sg driver: +.PP + scsi_logging_level \-s \-T 0 +.PP +For analyzing machine crashes associated with a SCSI command, nothing beats +a real serial port. By "real" means that it is _not_ a USB serial port. +The reason is that like SCSI, USB needs a functioning software stack within +the OS kernel, the very thing that may be crippled during a machine crash. +.PP +Modern laptops do not have real serial ports and many server machines +don't either (or it is an optional extra). In Linux the netconsole module +does a pretty good job by sending log entries to another machine (on the +same sub\-net)) using the UDP ("fire and forget") network protocol . .SH WEB SITE There is a web page discussing this package at https://sg.danny.cz/sg/sg3_utils.html . The device naming used by this diff --git a/doc/sg_z_act_query.8 b/doc/sg_z_act_query.8 index a43ad073..6b816835 100644 --- a/doc/sg_z_act_query.8 +++ b/doc/sg_z_act_query.8 @@ -1,4 +1,4 @@ -.TH SG_Z_ACT_QUERY "8" "November 2021" "sg3_utils\-1.48" SG3_UTILS +.TH SG_Z_ACT_QUERY "8" "December 2021" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_z_act_query \- send a SCSI ZONE ACTIVATE or ZONE QUERY command .SH SYNOPSIS @@ -13,7 +13,7 @@ sg_z_act_query \- send a SCSI ZONE ACTIVATE or ZONE QUERY command .PP Sends a SCSI ZONE ACTIVATE or ZONE QUERY command to the \fIDEVICE\fR. If the \fI\-\-activate\fR option is not given, then a ZONE QUERY command is sent. -These commands where added in the ZBC\-2 draft revision 4 (zbc2r04.pdf). +These commands were added in the ZBC\-2 draft revision 4 (zbc2r04.pdf). .PP Both of these commands have similar cdb_s and responses hence they are both placed in this utility. The difference is that only the ZONE ACTIVATE command @@ -45,8 +45,8 @@ response is output in ASCII hexadecimal with a leading address (starting at response is output separately in hexadecimal. When used thrice the whole response is output in hexadecimal with no leading address (on each line). .br -The output format when this option is given thrice is suitable contents -for a later invocation with the \fI\-\-inhex=FN\fR option. +The output format when this option is given thrice is suitable for a later +invocation with the \fI\-\-inhex=FN\fR option. .TP \fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR where \fIFN\fR is a file name whose contents are assumed to be ASCII -- cgit v1.2.3