major rework of lib/sg_pt_freebsd.c; sg_raw: fix prints of NVMe NVM command names

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@896 6180dd3e-e324-4e3e-922d-17de1ae2f315

4 files changed, 31 insertions, 16 deletions

diff --git a/doc/README b/doc/README
index 89205622..d20d510f 100644
--- a/doc/README
+++ b/doc/README
@@ -5,22 +5,22 @@ removed in version 1.24 .
 Here are the urls of the files that were previously here plus a brief
 summary:
 
-http://sg.danny.cz/sg/sg3_utils.html
+https://sg.danny.cz/sg/sg3_utils.html
     - overview and examples of this package
 
-http://sg.danny.cz/sg/sg_dd.html
+https://sg.danny.cz/sg/sg_dd.html
     - discussion and examples of the sg_dd utility which is a dd variant
       (also discusses the sgm_dd, sgp_dd and sg_read utilities)
 
-http://sg.danny.cz/sg/sg_ses.html
+https://sg.danny.cz/sg/sg_ses.html
     - discussion and examples of the sg_ses utility. SCSI Enclosure
       Services (SES) devices may contain a lot of information,
       structured in a non-trivial way.
 
-http://sg.danny.cz/sg/sg_io.html
+https://sg.danny.cz/sg/sg_io.html
     - discussion of Linux SG_IO ioctl (SCSI pass-through)
 
-http://sg.danny.cz/sg/tools.html
+https://sg.danny.cz/sg/tools.html
     - overview of around 25 storage and SCSI tools
 
 
@@ -31,4 +31,4 @@ sg_scan.8 . sg_scan is not supported for other ports.
 
 
 Douglas Gilbert
-10th February 2010
+16th April 2021
diff --git a/doc/sg3_utils.8 b/doc/sg3_utils.8
index 5f93cbd0..a4716e3e 100644
--- a/doc/sg3_utils.8
+++ b/doc/sg3_utils.8
@@ -1,4 +1,4 @@
-.TH SG3_UTILS "8" "April 2021" "sg3_utils\-1.47" SG3_UTILS
+.TH SG3_UTILS "8" "May 2021" "sg3_utils\-1.47" SG3_UTILS
 .SH NAME
 sg3_utils \- a package of utilities for sending SCSI commands
 .SH SYNOPSIS
diff --git a/doc/sg_raw.8 b/doc/sg_raw.8
index 95519848..fe157392 100644
--- a/doc/sg_raw.8
+++ b/doc/sg_raw.8
@@ -1,4 +1,4 @@
-.TH SG_RAW "8" "January 2021" "sg3_utils\-1.46" SG3_UTILS
+.TH SG_RAW "8" "April 2021" "sg3_utils\-1.47" SG3_UTILS
 .SH NAME
 sg_raw \- send arbitrary SCSI or NVMe command to a device
 .SH SYNOPSIS
@@ -58,8 +58,9 @@ the NVMe command set.
 Display usage information and exit.
 .TP
 \fB\-i\fR, \fB\-\-infile\fR=\fIIFILE\fR
-Read data from \fIIFILE\fR instead of stdin. This option is ignored if
-\fB\-\-send\fR is not specified.
+Read binary data from \fIIFILE\fR instead of stdin. This option is ignored
+if \fB\-\-send\fR is not specified. That data, if used, will become the
+the command's "data\-out" buffer.
 .TP
 \fB\-n\fR, \fB\-\-nosense\fR
 Don't display SCSI Sense information.
@@ -70,8 +71,9 @@ NVM command set (e.g. the Read and Write (user data) commands) this option
 needs to be given.
 .TP
 \fB\-o\fR, \fB\-\-outfile\fR=\fIOFILE\fR
-Write data received from the \fIDEVICE\fR to \fIOFILE\fR. The data is
-written in binary. By default, data is dumped in hex format to stdout.
+Write data received from the \fIDEVICE\fR to \fIOFILE\fR. That data is
+the command's "data\-in" buffer. The data is written in binary. By default,
+data is dumped in hex format to stdout.
 If \fIOFILE\fR is '\-' then data is dumped in binary to stdout.
 This option is ignored if \fI\-\-request\fR is not specified.
 .TP
@@ -200,7 +202,7 @@ followed by seven "ff"s. A similar arrangement is made for the length
 of that buffer (in bytes), but since that is a 32 byte quantity, the
 first 4 bytes (all "ff"s) are removed.
 .PP
-Several command file examples can be found in the examples directory of this
+Several command file examples can be found in the inhex directory of this
 package's source tarball: nvme_identify_ctl.hex, nvme_dev_self_test.hex,
 nvme_read_ctl.hex and nvme_write_ctl.hex .
 .PP
@@ -249,6 +251,9 @@ the SCSI ATA PASS\-THROUGH(12) command (see the SAT or SAT\-2 standard at
 https://www.t10.org). Notice that the STANDBY IMMEDIATE command does not
 send or receive any additional data, however if it fails sense data
 should be returned and displayed.
+.TP
+For NVME examples see the files in this package's inhex directory that
+start with 'nvme_' such as inhex/nvme_identify_ctl.hex .
 .SH EXIT STATUS
 The exit status of sg_raw is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
diff --git a/doc/sg_start.8 b/doc/sg_start.8
index c9a44491..1b251c1e 100644
--- a/doc/sg_start.8
+++ b/doc/sg_start.8
@@ -1,4 +1,4 @@
-.TH SG_START "8" "September 2020" "sg3_utils\-1.43" SG3_UTILS
+.TH SG_START "8" "April 2021" "sg3_utils\-1.47" SG3_UTILS
 .SH NAME
 sg_start \- send SCSI START STOP UNIT command: start, stop, load or eject
 medium
@@ -40,6 +40,11 @@ This utility supports two command line syntaxes, the preferred one is
 shown first in the synopsis and explained in this section. A later
 section on the old command line syntax outlines the second group of
 options.
+.PP
+Linux note: best not to use a standard block device name (e.g. /dev/sdc)
+with the \fI\-\-stop\fR option. Use a sg or bsg device node instead (see
+lsscsi(8) ). The block layer will sometimes notice the disk spinning
+down and decide: "that's not right" and spin it up again!
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 .TP
@@ -52,6 +57,8 @@ same action as \fI\-\-start\fR.
 \fB\-e\fR, \fB\-\-eject\fR
 stop the medium and eject it from the drive. Only appropriate for a
 device with removable medium. Might be ignored (prevented), see below.
+Note, this is an operation that can be done on a tape drive or CD/DVD/BD
+player, not on a hard disk or SSD!
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 print out the usage message then exit.
@@ -117,6 +124,9 @@ other options, this option defaults (i.e. set the START cdb bit).
 .TP
 \fB\-S\fR, \fB\-\-stop\fR
 stop (spin\-down) the \fIDEVICE\fR. This clears the START bit in the cdb.
+This operation is typically done on a hard disk or SSD. In the case of a
+SSD it will be placed in low power mode and may need a start operation
+later before normal IO can resume.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 increase the level of verbosity. Can be used multiple times.
@@ -264,10 +274,10 @@ Written by K. Garloff and D. Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2002\-2020 Kurt Garloff, Douglas Gilbert
+Copyright \(co 2002\-2021 Kurt Garloff, 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.
 .SH "SEE ALSO"
 .B sg_prevent(sg3_utils), sg_requests(sg3_utils), sg_turs(sg3_utils)
-.B sdparm(sdparm)
+.B sdparm(sdparm), lsscsi(lsscsi)