193 lines
8.1 KiB
Groff
193 lines
8.1 KiB
Groff
.TH SG_READ "8" "September 2019" "sg3_utils\-1.45" SG3_UTILS
|
|
.SH NAME
|
|
sg_read \- read multiple blocks of data, optionally with SCSI READ commands
|
|
.SH SYNOPSIS
|
|
.B sg_read
|
|
[\fIblk_sgio=\fR0|1] [\fIbpt=BPT\fR] [\fIbs=BS\fR] [\fIcdbsz=\fR6|10|12|16]
|
|
\fIcount=COUNT\fR [\fIdio=\fR0|1] [\fIdpo=\fR0|1] [\fIfua=\fR0|1]
|
|
\fIif=IFILE\fR [\fImmap=\fR0|1] [\fIno_dxfer=\fR0|1] [\fIodir=\fR0|1]
|
|
[\fIskip=SKIP\fR] [\fItime=TI\fR] [\fIverbose=VERB\fR] [\fI\-\-help\fR]
|
|
[\fI\-\-version\fR]
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
.PP
|
|
Read data from a Linux SCSI generic (sg) device, a block device or
|
|
a normal file with each read command issued to the same offset or
|
|
logical block address (lba). This can be used to test (or time) disk
|
|
caching, SCSI (or some other) transport throughput, and/or SCSI
|
|
command overhead.
|
|
.PP
|
|
When the \fICOUNT\fR value is positive, then up to \fIBPT\fR blocks are
|
|
read at a time, until the \fICOUNT\fR is exhausted. Each read operation
|
|
starts at the same lba which, if \fISKIP\fR is not given, is the
|
|
beginning of the file or device.
|
|
.PP
|
|
The \fICOUNT\fR value may be negative when \fIIFILE\fR is a sg device
|
|
or is a block device with 'blk_sgio=1' set. Alternatively 'bpt=0' may
|
|
be given. In these cases |\fICOUNT\fR| "zero block" SCSI READ commands
|
|
are issued. "Zero block" means "do nothing" for SCSI READ 10, 12 and
|
|
16 byte commands (but not for the 6 byte variant). In practice "zero
|
|
block" SCSI READ commands have low latency and so are one way to measure
|
|
SCSI command overhead.
|
|
.PP
|
|
Please note: this is a very old utility that uses 32 bit integers for
|
|
disk LBAs and the count. Hence it will not be able to address beyond
|
|
2 Terabytes on a disk with logical blocks that are 512 bytes long.
|
|
Alternatives are the sg_dd and ddpt utilities.
|
|
.SH OPTIONS
|
|
.TP
|
|
\fBblk_sgio\fR=0 | 1
|
|
The default action of this utility is to use the Unix read() command when
|
|
the \fIIFILE\fR is a block device. In lk 2.6 many block devices can handle
|
|
SCSI commands issued via the SG_IO ioctl. So when this option is set
|
|
the SG_IO ioctl sends SCSI READ commands to \fIIFILE\fR if it is a block
|
|
device.
|
|
.TP
|
|
\fBbpt\fR=\fIBPT\fR
|
|
where \fIBPT\fR is the maximum number of blocks each read operation fetches.
|
|
Fewer blocks will be fetched when the remaining \fICOUNT\fR is less than
|
|
\fIBPT\fR. The default value for \fIBPT\fR is 128. Note that each read
|
|
operation starts at the same lba (as given by \fIskip=SKIP\fR or 0).
|
|
If 'bpt=0' then the \fICOUNT\fR is interpreted as the number of zero
|
|
block SCSI READ commands to issue.
|
|
.TP
|
|
\fBbs\fR=\fIBS\fR
|
|
where \fIBS\fR is the size (in bytes) of each block read. This
|
|
.B must
|
|
be the block size of the physical device (defaults to 512) if SCSI commands
|
|
are being issued to \fIIFILE\fR.
|
|
.TP
|
|
\fBcdbsz\fR=6 | 10 | 12 | 16
|
|
size of SCSI READ commands issued on sg device names, or block devices
|
|
if 'blk_sgio=1' is given. Default is 10 byte SCSI READ cdbs.
|
|
.TP
|
|
\fBcount\fR=\fICOUNT\fR
|
|
when \fICOUNT\fR is a positive number, read that number of blocks,
|
|
typically with multiple read operations. When \fICOUNT\fR is negative then
|
|
|\fICOUNT\fR| SCSI READ commands are performed requesting zero blocks
|
|
to be transferred. This option is mandatory.
|
|
.TP
|
|
\fBdio\fR=0 | 1
|
|
default is 0 which selects indirect IO. Value of 1 attempts direct
|
|
IO which, if not available, falls back to indirect IO and notes this
|
|
at completion. This option is only active if \fIIFILE\fR is an sg device.
|
|
If direct IO is selected and /sys/module/sg/parameters/allow_dio
|
|
has the value of 0 then a warning is issued (and indirect IO is performed)
|
|
.TP
|
|
\fBdpo\fR=0 | 1
|
|
when set the disable page out (DPO) bit in SCSI READ commands is set.
|
|
Otherwise the DPO bit is cleared (default).
|
|
.TP
|
|
\fBfua\fR=0 | 1
|
|
when set the force unit access (FUA) bit in SCSI READ commands is set.
|
|
Otherwise the FUA bit is cleared (default).
|
|
.TP
|
|
\fBif\fR=\fIIFILE\fR
|
|
read from this \fIIFILE\fR. This argument must be given. If the \fIIFILE\fR
|
|
is a normal file then it must be seekable (if (\fICOUNT\fR > \fIBPT\fR) or
|
|
\fIskip=SKIP\fR is given). Hence stdin is not acceptable (and giving "\-"
|
|
as the \fIIFILE\fR argument is reported as an error).
|
|
.TP
|
|
\fBmmap\fR=0 | 1
|
|
default is 0 which selects indirect IO. Value of 1 causes memory mapped
|
|
IO to be performed. Selecting both dio and mmap is an error. This option
|
|
is only active if \fIIFILE\fR is an sg device.
|
|
.TP
|
|
\fBno_dxfer\fR=0 | 1
|
|
when set then DMA transfers from the device are made into kernel buffers
|
|
but no further (i.e. there is no second copy into the user space). The
|
|
default value is 0 in which case transfers are made into the user space.
|
|
When neither mmap nor dio is set then data transfer are copied via
|
|
kernel buffers (i.e. a double copy). Mainly for testing.
|
|
.TP
|
|
\fBodir\fR=0 | 1
|
|
when set opens an \fIIFILE\fR which is a block device with an additional
|
|
O_DIRECT flag. The default value is 0 (i.e. don't open block devices
|
|
O_DIRECT).
|
|
.TP
|
|
\fBskip\fR=\fISKIP\fR
|
|
all read operations will start offset by \fISKIP\fR bs\-sized blocks
|
|
from the start of the input file (or device).
|
|
.TP
|
|
\fBtime\fR=\fITI\fR
|
|
When \fITI\fR is 0 (default) doesn't perform timing.
|
|
When 1, times transfer and does throughput calculation, starting at the
|
|
first issued command until completion. When 2, times transfer and does
|
|
throughput calculation, starting at the second issued command until
|
|
completion. When 3 times from third command, etc. An average number of
|
|
commands (SCSI READs or Unix read()s) executed per second is also
|
|
output.
|
|
.TP
|
|
\fBverbose\fR=\fIVERB\fR
|
|
as \fIVERB\fR increases so does the amount of debug output sent to stderr.
|
|
Default value is zero which yields the minimum amount of debug output.
|
|
A value of 1 reports extra information that is not repetitive.
|
|
.TP
|
|
\fB\-\-help\fR
|
|
Output the usage message then exit.
|
|
.TP
|
|
\fB\-\-version\fR
|
|
Output the version string then exit.
|
|
.SH NOTES
|
|
Various numeric arguments (e.g. \fISKIP\fR) may include multiplicative
|
|
suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
|
|
in the sg3_utils(8) man page.
|
|
.PP
|
|
Data usually gets to the user space in a 2 stage process: first the
|
|
SCSI adapter DMAs into kernel buffers and then the sg driver copies
|
|
this data into user memory.
|
|
This is called "indirect IO" and there is a "dio" option to select
|
|
"direct IO" which will DMA directly into user memory. Due to some
|
|
issues "direct IO" is disabled in the sg driver and needs a
|
|
configuration change to activate it. This is typically done with
|
|
"echo 1 > /sys/module/sg/parameters/allow_dio". An alternate way to avoid the
|
|
2 stage copy is to select memory mapped IO with 'mmap=1'.
|
|
.SH SIGNALS
|
|
The signal handling has been borrowed from dd: SIGINT, SIGQUIT and
|
|
SIGPIPE output the number of remaining blocks to be transferred;
|
|
then they have their default action.
|
|
SIGUSR1 causes the same information to be output yet the copy continues.
|
|
All output caused by signals is sent to stderr.
|
|
.SH EXAMPLES
|
|
.PP
|
|
Let us assume that /dev/sg0 is a disk and we wish to time the disk's
|
|
cache performance.
|
|
.PP
|
|
sg_read if=/dev/sg0 bs=512 count=1MB mmap=1 time=2
|
|
.PP
|
|
This command will continually read 128 512 byte blocks from block 0.
|
|
The "128" is the default value for 'bpt' while "block 0" is chosen
|
|
because the 'skip' argument was not given. This will continue until
|
|
1,000,000 blocks are read. The idea behind using 'time=2' is that the
|
|
first 64 KiB read operation will involve reading the magnetic media
|
|
while the remaining read operations will "hit" the disk's cache. The
|
|
output of third command will look like this:
|
|
.PP
|
|
time from second command to end was 4.50 secs, 113.70 MB/sec
|
|
.br
|
|
Average number of READ commands per second was 1735.27
|
|
.br
|
|
1000000+0 records in, SCSI commands issued: 7813
|
|
.SH EXIT STATUS
|
|
The exit status of sg_read is 0 when it is successful. Otherwise see
|
|
the sg3_utils(8) man page.
|
|
.SH AUTHORS
|
|
Written by Douglas Gilbert.
|
|
.SH "REPORTING BUGS"
|
|
Report bugs to <dgilbert at interlog dot com>.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2000\-2019 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"
|
|
To time streaming media read or write time see
|
|
.B sg_dd
|
|
is in the sg3_utils package and
|
|
.B ddpt
|
|
in a package of the same name.
|
|
The lmbench package contains
|
|
.B lmdd
|
|
which is also interesting.
|
|
.B raw(8), dd(1)
|