1 files changed, 86 insertions, 0 deletions
diff --git a/doc/sg_test_rwbuf.8 b/doc/sg_test_rwbuf.8
new file mode 100644
index 00000000..d610531e
--- /dev/null
+++ b/doc/sg_test_rwbuf.8
@@ -0,0 +1,86 @@
+.TH SG_TEST_RWBUF "8" "January 2018" "sg3_utils\-1.43" SG3_UTILS
+.SH NAME
+sg_test_rwbuf \- test a SCSI host adapter by issuing dummy writes
+and reads
+.SH SYNOPSIS
+.B sg_test_rwbuf
+[\fI\-\-addrd=AR\fR] [\fI\-\-addwr=AW\fR] [\fI\-\-help\fR]
+[\fI\-\-quick\fR] \fI\-\-size=SZ\fR [\fI\-\-times=NUM\fR] [\fI\-\-verbose\fR]
+[\fI\-\-version\fR] \fIDEVICE\fR
+.PP
+or an older deprecated format
+.B sg_test_rwbuf
+\fIDEVICE\fR \fISZ\fR [\fIAW\fR] [\fIAR\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+sg_test_rwbuf writes and reads back \fISZ\fR bytes to the internal buffer of
+\fIDEVICE\fR (e.g. /dev/sda or /dev/sg0). A pseudo random pattern is
+written to the data buffer on the device then read back. If the same pattern
+is found 'Success' is reported. If they do not match (checksums unequal) then
+this is reported and up to 24 bytes from the first point of mismatch are
+reported; the first line shows what was written and the second line shows
+what was received. For testing purposes, you can ask it to write \fIAW\fR or
+read \fIAR\fR additional bytes.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-r\fR, \fB\-\-addrd\fR=\fIAR\fR
+Read an additional \fIAR\fR bytes (more than indicated by \fISZ\fR) from the
+data buffer. Checksum is performed over the first \fISZ\fR bytes.
+.TP
+\fB\-w\fR, \fB\-\-addwr\fR=\fIAW\fR
+Write an additional \fIAW\fR bytes (more than indicated by \fISZ\fR) of
+zeros into the data buffer. Checksum is generated over the first \fISZ\fR
+bytes.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print out a usage message the exit.
+.TP
+\fB\-q\fR, \fB\-\-quick\fR
+Perform a READ BUFFER descriptor command to find out the available data
+buffer length and offset, print them out then exit (without testing
+with write/read sequences).
+.TP
+\fB\-s\fR, \fB\-\-size\fR=\fISZ\fR
+where \fISZ\fR is the size of buffer in bytes to be written then read and
+checked. This number needs to be less than or equal to the size of the
+device's data buffer which can be seen from the \fI\-\-quick\fR option.
+Either this option or the \fI\-\-quick\fR option should be given.
+.TP
+\fB\-t\fR, \fB\-\-times\fR=\fINUM\fR
+where \fINUM\fR is the number of times to repeat the write/read to buffer
+test. Default value is 1 .
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase verbosity of output.
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print version number (and data of last change) then exit.
+.SH NOTES
+The microcode in a SCSI device is _not_ modified by doing a WRITE BUFFER
+command with its mode set to "data" (0x2) as done by this utility. Therefore
+this utility is safe in that respect. [Mode values 0x4, 0x5, 0x6 and 0x7
+are the dangerous ones :\-)]
+.PP
+\fBWARNING\fR: If you access the device at the same time (e.g. because it's
+a hard disk with a mounted file system on it) the device's buffer may be
+used by the device itself for other data at the same time, and overwriting
+it may or may not cause data corruption! \fBHOWEVER\fR the SPC\-3 draft
+standard does state in its WRITE BUFFER command: "This command shall not
+alter any medium of the logical unit when data mode ... is specified". This
+implies that it _is_ safe to use this utility with devices that have mounted
+file systems on them.
+Following this theme further, a disk with active mounted file systems may
+cause the data read back to be different (due to caching activity) to what
+was written and hence a checksum error.
+.SH EXIT STATUS
+The exit status of sg_test_rwbuf is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH AUTHORS
+Written by D. Gilbert and K. Garloff
+.SH COPYRIGHT
+Copyright \(co 2000\-2018 Douglas Gilbert, Kurt Garloff
+.br
+This software is distributed under the GPL version 2. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.