dt-usersguide.t

Linux磁盘测试的源代码,测试磁盘的读写性能

.so ../trf_files/INIT.doc
.\" <<<<<<<<<<<<< String Definitions >>>>>>>>>>>>>>>>>>>>>
.ds DY February 2nd, 2001
.ds F~ dt-UsersGuide.t
.ds V~ Version 14.1
.ds T~ \fIdt\fP - Data Test Program
.so _Cover.dt-UsersGuide
.\" <<<<<<<<<<<< Start Text Here >>>>>>>>>>>>>>>>>>>>>>
.nh 1 Overview.
\fIdt\fP is a generic data test program used to verify the proper operation
of peripherals & I/O sub-systems, and for obtaining performance information.
Since verification of data is performed, \fIdt\fP can be thought of as a
generic diagnostic tool.
.PP
Although the original design goals of being a generic test tool were
accomplished, it quickly become evident that device specific tests, such
as terminals, and different programming interfaces such as memory mapped
files and POSIX asynchronous I/O API's were necessary.  Therefore, special
options were added to enable these test modes and to specify necessary test
parameters.
.PP
\fIdt\fP command lines are similar to the \fIdd\fP program, which is popular
on most UNIX systems.  \fIdt\fP contains numerous options to provide user
control of most test parameters so customized tests can be written easily
and quickly by specifying simple command line options.  Since the exit
status of the program always reflects the completion status of a test,
scripts can easily detect failures to perform automatic regression tests.
.PP
\fIdt\fP has been used to successfully test disks, tapes, serial lines,
parallel lines, pipes & FIFO's, memory mapped files, and POSIX Asynchronous
I/O.  In fact, \fIdt\fP can be used with any device that supports the standard
open, read, write, and close system calls.  Special support is necessary
for some devices, such as serial lines, for setting up the speed, parity,
data bits, etc, but \fIdt\fP's design provides easy addition of this setup.
.PP
Most tests can be initiated by a simple \fIdt\fP command line, and lots of
I/O can be initiated quickly using multiple processes and/or POSIX AIO, for
those operating systems supporing AIO.  More complex tests are normally
initiated by writing shell scripts and using \fIdt\fP in conjunction with
other tools, such as \fIscu\fP (SCSI Command Utility).
Several shell scripts for testing disks, tapes, and serial lines are also
supplied with this kit which can used as templates for developing other
specialized test scripts.
.PP
Specific system features are now being added to \fIdt\fP so more extensive
testing can be accomplished.  The program has been restructured to allow
easy inclusion of new device specific tests by dispatching to test functions
through a function lookup table.  This table gets setup automatically by
the program, based on options enabled, or via the device type "\fIdtype=\fP"
option.
.B1
WARNING: \fIdt\fP does NOT perform any sanity checking of the output device
specified.  This means if you are running as 'root' and you specify a raw
disk device, \fIdt\fP will overwrite existing file systems, so please be
careful.
.HS
NOTE: Tru64 (Digital) UNIX prevents overwriting the disk label block (block 0),
to prevent you from destroying this valuable information.  Overwriting other
files systems, not starting at block zero, is still possible however.
.B2
.nh 1 Operating Systems Supported.
.PP
\fIdt\fP is conditionalized to run on SUN, ULTRIX, OSF, QNX, Windows/NT, and
Linux operating systems.  This conditionalization tends to make the source look
rather ugly, but I've purposely left this in for code maintainability (common
code base) and for other people to see porting differences between these systems.
UNIX is NOT as portable as some people think, but the POSIX standard is finally
changing this.  Eventually this will be cleaned up, but this conditionization
is currently necessary so \fIdt\fP will compile and run with non-ANSI compliant
compilers and non-POSIX compliant operating systems.
.nh 2 POSIX Compliant Systems.
People who may wish to port \fIdt\fP to other POSIX compliant operating
systems, should review the Tru64 UNIX, Linux, and QNX conditionalized code.
These operating systems also support an ANSI compliant compiler.
.HS
.nh 1 Test Uses.
Those poeple with an imagination will find many uses for \fIdt\fP, but I'll
list a few I've used it for, just to whet your appetite:
.bu
Testing of tape devices using different block sizes to determine
the best blocking factor for optimum performance and capacity.
This is very important for streaming tapes devices.
.bu
Write tapes to end of tape, to determine the total tape capacity.
This gives the total data capacity of tapes, after inter-record
gaps, preamble/postambles, or pad blocks are written on the tape.
.bu
Read existing tapes with data comparison disabled, to determine
the amount of data on the tape.  This is useful to determine how
much disk space is required to read in a tape, or to simply verify
the tape can be read without errors.
.bu
Reading/writing an entire tape to ensure device drivers properly
sense and handle end of tape error conditions.
.bu
Write a tape and ensure it can be read on another tape drive to
test drive compatibility (also referred to as transportability).
.bu
Read multiple tape files to ensure file marks and end of tape are
reported and handled properly by tape drivers.
.bu
I/O to disks using the raw device interface, to determine the
optimum performance of the controller.  This usually gives a
good indication of how well the controller cache or read-ahead
improves I/O performance for sequential or random file access.
.bu
I/O to disk files through the file system, to determine the affect
the buffer cache has on write and read performance.  You must know
the characteristics of your O/S's buffer cache to select file sizes
to either get optimum performance from the cache, or to defeat the
affect of the buffer cache.
.bu
Reading/writing of entire disks, to ensure the media capacity and
end of media error handling is properly reported by device drivers.
.bu
Test memory mapped files to compare I/O performance against raw
and file system I/O.  Typically, memory mapped I/O approaches the
raw device performance.
.bu
Testing I/O to files on NFS mounted file systems.  This will give
you a good indication of your ethernet performance to remote files.
.bu
Writing/reading pipes & FIFO's to verify pipe operation and performance.
.bu
Initiating multiple processes to test optimizations of buffer cache,
device drivers, and/or intelligent controllers.  This is also useful
to test multiple device access and for loading the I/O sub-system.
.bu
Force I/O at different memory boundaries to test low level driver
handling.  Using the align option, you can set memory alignment for
testing specialized device driver DMA code.  This is very useful
when developing new I/O sub-systems.
.bu
Do loopback testing of parallel or serial lines on either the same
system of different systems.  This is a useful compatibility test
when running different machines running different operating systems.
.bu
Enable POSIX Asynchronous I/O to verify proper operation of this API
and to determine performance gains (over standard synchronous I/O).
This is also useful for queuing multiple I/O requests to drivers and
for testing SCSI tag queuing and RAID configurations.
.bu
Specify variable record options for testing variable tape devices.
.bu
On Tru64 cluster systems, distributed lock manager (DLM) options can
be used to control access to shared devices or files.
.bu
Also available on Tru64 UNIX is the ability to use Extended Error
Information (EEI) to detect and recover from SCSI bus/device resets
(tape is repositioned for continuing the test).
.LP
.HS
.nh 1 Program Options.
This section describes program options and and special notes related
to each.  The \fIdt\fP help file provides a summary of the options,
and the default value of most options.  The \fIdt\fP help summary
for Tru64 UNIX is shown in Appendix A.
.nh 2 Input File \&"\fIif=\fP\&" Option.
This option specifies the input file to open for reads.  The device is opened
read-only so devices which only permit or support read access, e.g., parallel
input devices, can be opened successfully.
.HS
Special Notes:
.bu
Data read is automatically verified with the default data pattern, unless
you disable this action via the "\fIdisable=compare\fP" option.
.bu
Extra pad bytes of sizeof(int), are allocated at the end of data buffers,
initialized with the inverted data pattern, and then verified after each
read request to ensure the end of data buffers didn't get overwritten by
file system and/or device drivers.  This extra check has found problems
with flushing DMA FIFO's on several machines.
.LP
.EX
    Syntax:
        if=filename      The input file to read.
.EE
.nh 2 Output File \&"\fIof=\fP\&" Option.
This option specifies the output file to open for writes.  After the write
portion of the test, the device is closed (to reposition to start of file
or to rewind the tape), re-opened, and then a read verification pass is
performed.  If you wish to prevent the read verify pass, you must specify
the "\fIdisable=verify\fP" option.
.HS
Special Notes:
.bu
Terminal devices are \fBnot\fP closed between passes so previously set
terminal characteristics don't get reset.  This also caused a race condition
when doing loopback testing with two processes.
.bu
When testing terminal (serial) devices, modem control is disabled (via setting
CLOCAL) to prevent tests from hanging.  If the "\fIenable=modem\fP" option is
specified, then CLOCAL is reset, hangup on close HUPCL is set, and testing
will not preceed until carrier or DSR is detected.  This code is not fully
tested, but this description accurately describes the code.
.bu
At the present time, tapes are rewound by closing the device, so you \fBmust\fP
specify the rewind device during testing if the read verify pass is being
performed.  This restriction will probably change in the next release since
magtape control commands will be supported (tape specific tests as well).
.bu
A special check is made for the /dev/ prefix, and if located, the O_CREAT open
flag is cleared to prevent accidently creating files in this directory when not
specifying the correct device name (very easy to do when running tests
as super-user 'root').
.bu
When writing to raw disks on Tru64 UNIX, if the disk was previously labeled,
you must issue the "\fIdisklabel -z\fP" command to destroy the label block
or else you cannot write to this area of this disk (block 0).  Failure to do
this results in the error "Read-only file system" (errno=EROFS) being returned
on write requests.
.LP
.EX
    Syntax:
        of=filename      The output file to write.
.EE
.nh 2 Pattern File \&"\fIpf=\fP\&" Option.
This option specifies a pattern file to use for the data pattern during
testing.  This option overrides the "\fIpattern=\fP" option and allows you
to specify specialized patterns.  The only restriction to this option is
that the entire file \fImust\fP fit in memory.  A buffer is allocated to
read the entire pattern file into memory before testing starts so performance
is not affected by reading the pattern file.
.EX
    Syntax:
        pf=filename      The data pattern file to use.
.EE
.nh 2 Block Size \&"\fIbs=\fP\&" Option.
This option specifies the block size, in bytes, to use during testing.
At the present time, this option sets both the input and output block sizes.
At the time I originally wrote this program, I didn't have the need for
seperate block sizes, but this may change in a future release where I'll add
back the "\fIibs=\fP" & "\fIobs=\fP" options available with \fIdd\fP.
.HS
Special Notes:
.bu
When enabling variable length records via the "\fImin=\fP" option, this
also sets the maximum record size to be written/read.
.bu
For memory mapped files, the block size \fImust\fP be a multiple of the
system dependent page size (normally 4k or 8k bytes).
.LP
.EX
    Syntax:
        bs=value         The block size to read/write.
.EE
.nh 2 Log File \&"\fIlog=\fP\&" Option.
This option specifies the log file to redirect all program output to.
This is done by re-opening the standard error stream (stderr) to the
specifed log file.  Since all output from \fIdt\fP is directed to stderr,
library functions such as perror() also write to this log file.
.HS
Special Notes:
.bu
A seperate buffer is allocated for the stderr stream, and this stream is
set buffered so timing isn't affected by program output.
.bu
When starting multiple processes via the "\fIprocs=\fP" option, all output
is directed to the same log file.  The output from each process is identified
by the process ID (PID) as part of the message (errors & statistics).
.LP
.EX
    Syntax:
        log=filename     The log file name to write.
.EE
.nh 2 POSIX Asynchronous I/O \&"\fIaios=\fP\&" Option.
This option enables and controls the number of POSIX Asychronous I/O
requests used by the program.
.HS
Special Notes:
.bu
The default is to queue up to 8 requests.
.bu
This option is only valid for Tru64 UNIX systems are this time.
.bu
The system limit for AIO on Tru64 UNIX is dynamic, and can be queried
by using the "\fIsysconfig -q rt\fP" command.
.bu
You can use the "\fIenable=aio\fP" option to enable AIO and use the
default request limit.
.bu
AIO is only supported for character devices and is disabled for terminals.
On Tru64 UNIX, you can alter the Makefile and link against libaio.a, which
allows AIO with any device/file by mimic'ing AIO using POSIX threads.
.bu
AIO requests can \fBnot\fP be cancelled on Tru64 UNIX, so queuing many
requests to 1/2" tape devices will probably result in running off the
end of the tape reel.  This is not a problem for cartridge tapes.
.LP
.EX
    Syntax:
        aios=value       Set number of AIO's to queue.
.EE
.nh 2 Buffer Alignment \&"\fIalign=\fP\&" Option.
This option controls the alignment of the normally page aligned data
buffer allocated.  This option is often useful for testing certain DMA
boundary conditions not easily reproduced otherwise.  The rotate option
automatically adjust the data buffer pointer by (0, 1, 2, 3, ...) for
each I/O request to ensure various boundaries are fully tested.
.EX
    Syntax:
        align=offset     Set offset within page aligned buffer.
    or  align=rotate     Rotate data address through sizeof(ptr).
.EE
.nh 2 File Disposition \&"\fIdispose=\fP\&" Option.
This option controls the disposition of test files created on file