diff options
Diffstat (limited to 'doc/sg_read.8')
| -rw-r--r-- | doc/sg_read.8 | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/doc/sg_read.8 b/doc/sg_read.8 new file mode 100644 index 00000000..3f370a62 --- /dev/null +++ b/doc/sg_read.8 @@ -0,0 +1,192 @@ +.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) |