
			Overview of 'dt' Program
			------------------------

	The 'dt' program is a generic data transfer program which was
originally written to test sequential tape drives.  It's purpose was to
provide many of the features available via the 'dd' utility except with
data verification and performance statistics.

	After the initial development was completed, it was found that
'dt' was also useful for testing disk devices using both the raw and
file system interfaces.

	Eventually, there was a need to test terminal interfaces and so
various commands were added to control this testing (flow control, speed,
parity, etc.).  The terminal support which resides in 'dt' was written for
Sun's streams based terminal driver.  This code has been conditionalized
appropriately for ULTRIX, OSF, and QNX terminal drivers.

	When memory mapped files became available, this support was also
added to 'dt' so we could compare this performance with normal file system
performance.  This code is conditionalized for SUN and OSF systems.

	When I was performing my qualification of the RRD42 on ULTRIX, I
added several more useful options which allowed testing using the RRD TEST
DISC which is shipped with the RRD40.  This disk contains various data
patterns which was very useful for debugging several data corruption
problems in the SCSI drivers.   I added the ability to read a pattern file
and to seek to various positions of the disk to verify each data pattern.

	An option was added to force use of mis-aligned data buffers to test
code paths in drivers which must do special handling of this condition.
This is accomplished by specifiying a buffer offset (align=) which offsets
the normally page aligned buffers to force unaligned data access.

	New Features:

	"procs="	To initiate multiple processes.
	"files="	To process multiple tape files.
	"step="		To force seeks after disk I/O.
	"runtime="	To control how long to run.
	"enable=aio"	To enable POSIX Asynchronous I/O.
	"aios=value"	To set POSIX AIO's to queue (default 8).
	"align=rotate"	To rotate data address through sizeof(ptr).
	"pattern=incr"	To use an incrementing data pattern.
	"min="		To set the minimum record size.
	"max="		To Set the maximum record size.
	"incr="		To set the record bytes to increment.

	The "procs" option is useful for load testing, & testing buffer
cache, driver, and controller optimizations.  The "files" option is useful
for verifying tape drivers properly report & reset file marks & end of tape
conditions.  The "step" option is useful to cause non-sequential disk access.
The "min", "max", & "incr" options are used for variable length records.  In
addition to these options, errors now have a timestamp associated with them,
and the start & end times are displayed in the total statistics.
	
	There are several useful scripts I've developed which use 'dt' for
testing.  These script reside in the ~rmiller/utils/dt directory along with
the source code and pattern files required for testing with the RRD TEST DISC.
A short overview of these scripts is described below:

	dta	For testing asynhronous terminal lines.
	dtc	Test the RRD40/42 using the RRD TEST DISC.
	dtf	For testing floppy drives.
	dtt	For testing tape devices.
	dtr	To read data patterns written by 'dtw'.
	dtw	Writes the data pattens obtained from the RRD TEST DISC.
		These pattern files are named pattern_[0-9]

	A common script could be developed to replace most of the existing
scripts, but I'm not a script expert so a simple cut & paste does the job.

	The help text below is what resides in the 'dt' program.  Please
also be aware that 'dt' will let you hurt yourself if you have write access
to raw disk devices (i.e., running as root).  'dt' does not verify whether
a disk is mounted or whether it contains file systems. The best way to learn
'dt' is to simply play with it by specifying different options.

	Good luck, and have fun...

Cheers,
Robin Miller
================================================================================

% dt help
Usage: dt options...

    Where options are:
        if=filename      The input file to read.
        of=filename      The output file to write.
        pf=filename      The data pattern file to use.
        bs=value         The block size to read/write.
        log=filename     The log file name to write.
        aios=value       Set number of AIO's to queue.
        align=offset     Set offset within page aligned buffer.
    or  align=rotate     Rotate data address through sizeof(ptr).
        dispose=mode     Set file dispose to: {delete or keep}.
        dlimit=value     Set the dump data buffer limit.
        dtype=string     Set the device type being tested.
        errors=value     The number of errors to tolerate.
        files=value      Set number of tape files to process.
        flow=type        Set flow to: none, cts_rts, or xon_xoff.
        incr=value       Set number of record bytes to increment.
        iomode=mode      Set I/O mode to: {copy, test, or verify}.
        iotype=type      Set I/O type to: {random or sequential}.
        min=value        Set the minumum record size to transfer.
        max=value        Set the maximum record size to transfer.
        lba=value        Set starting block used w/lbdata option.
        lbs=value        Set logical block size for lbdata option.
        limit=value      The number of bytes to transfer.
        munsa=string     Set munsa to: cr, cw, pr, pw, ex.
        flags=flags      Set open flags:   {excl,sync,...}
        oflags=flags     Set output flags: {append,trunc,...}
        oncerr=action    Set child error action: {abort or continue}.
        parity=string    Set parity to: {even, odd, or none}.
        passes=value     The number of passes to perform.
        pattern=value    The 32 bit hex data pattern to use.
    or  pattern=iot      Use DJ's IOT test pattern.
    or  pattern=incr     Use an incrementing data pattern.
    or  pattern=string   The string to use for the data pattern.
        position=offset  Position to offset before testing.
        procs=value      The number of processes to create.
        ralign=value     The random I/O offset alignment.
        rlimit=value     The random I/O data byte limit.
        records=value    The number of records to process.
        runtime=time     The number of seconds to execute.
        skip=value       The number of records to skip past.
        seek=value       The number of records to seek past.
        step=value       The number of bytes seeked after I/O.
        speed=value      The tty speed (baud rate) to use.
        timeout=value    The tty read timeout in .10 seconds.
        ttymin=value     The tty read minimum count (sets vmin).
        enable=flag      Enable one or more of the flags below.
        disable=flag     Disable one or more of the flags below.

    Flags to enable/disable:
        aio              POSIX Asynchronous I/O.(Default: disabled)
        compare          Data comparison.       (Default: enabled)
        coredump         Core dump on errors.   (Default: disabled)
        debug            Debug output.          (Default: disabled)
        Debug            Verbose debug output.  (Default: disabled)
        dump             Dump data buffer.      (Default: enabled)
        eei              Tape EEI reporting.    (Default: enabled)
        resets           Tape reset handling.   (Default: disabled)
        flush            Flush tty I/O queues.  (Default: enabled)
        header           Log file header.       (Default: enabled)
        lbdata           Logical block data.    (Default: disabled)
        loopback         Loopback mode.         (Default: disabled)
        microdelay       Microsecond delays.    (Default: disabled)
        mmap             Memory mapped I/O.     (Default: disabled)
        modem            Test modem tty lines.  (Default: disabled)
        pstats           Per pass statistics.   (Default: enabled)
        stats            Display statistics.    (Default: enabled)
        table            Table(sysinfo) timing. (Default: disabled)
        ttyport          Flag device as a tty.  (Default: disabled)
        verbose          Verbose output.        (Default: enabled)
        verify           Verify data written.   (Default: enabled)

        Example: enable=debug disable=compare,pstats

    MUNSA Lock Options:
        cr = Concurrent Read (permits read access, cr/pr/cw by others)
        pr = Protected Read (permits cr/pr read access to all, no write)
        cw = Concurrent Write (permits write and cr access to resource by all)
        pw = Protected Write (permits write access, cr by others)
        ex = Exclusive Mode (permits read/write access, no access to others)

            For more details, please refer to the dlm(4) reference page.

    Common Open Flags:
        excl (O_EXCL)         Exclusive open. (don't share)
        ndelay (O_NDELAY)     Non-delay open. (don't block)
        nonblock (O_NONBLOCK) Non-blocking open/read/write.
        cache (O_CACHE)       Attempt to keep data in file system cache.
        rsync (O_RSYNC)       Synchronize read operations.
        sync (O_SYNC)         Sync updates for data/file attributes.

    Output Open Flags:
        append (O_APPEND)     Append data to end of existing file.
        defer (O_DEFER)       Defer updates to file during writes.
        dsync (O_DSYNC)       Sync data to disk during write operations.
        trunc (O_TRUNC)       Truncate an exisiting file before writing.

    Delays (Values are seconds, unless microdelay enabled):
        cdelay=value     Delay before closing the file.    (Def: 0)
        edelay=value     Delay between multiple passes.    (Def: 0)
        rdelay=value     Delay before reading each record. (Def: 0)
        sdelay=value     Delay before starting the test.   (Def: 0)
        tdelay=value     Delay before child terminates.    (Def: 1)
        wdelay=value     Delay before writing each record. (Def: 0)

    Numeric Input:
        For options accepting numeric input, the string may contain any
        combination of the following characters:

        Special Characters:
            w = words (4 bytes)            q = quadwords (8 bytes)
            b = blocks (512 bytes)         k = kilobytes (1024 bytes)
            m = megabytes (1048576 bytes)  p = page size (8192 bytes)
            g = gigabytes (1073741824 bytes)
            t = terabytes (1099511627776 bytes)
            inf or INF = infinity (18446744073709551615 bytes)

        Arithmetic Characters:
            + = addition                   - = subtraction
            * or x = multiplcation         / = division
            % = remainder

        Bitwise Characters:
            ~ = complement of value       >> = shift bits right
           << = shift bits left            & = bitwise 'and' operation
            | = bitwise 'or' operation     ^ = bitwise exclusive 'or'

        The default base for numeric input is decimal, but you can override
        this default by specifying 0x or 0X for hexadecimal conversions, or
        a leading zero '0' for octal conversions.  NOTE: Evaluation is from
        right to left without precedence, and parenthesis are not permitted.

    Pattern String Input:
            \\ = Backslash   \a = Alert (bell)   \b = Backspace
            \f = Formfeed    \n = Newline        \r = Carriage Return
            \t = Tab         \v = Vertical Tab   \e or \E = Escape
            \ddd = Octal Value    \xdd or \Xdd = Hexadecimal Value

    Time Input:
            d = days (86400 seconds),      h = hours (3600 seconds)
            m = minutes (60 seconds),      s = seconds (the default)

        Arithmetic characters are permitted, and implicit addition is
        performed on strings of the form '1d5h10m30s'.

    Defaults:
        errors=1, files=0, passes=1, records=0, bs=512, log=stderr
        pattern=0x39c39c39, flow=xon_xoff, parity=none, speed=9600
        timeout=3 seconds, dispose=delete, align=0 (page aligned)
        aios=8, dlimit=64, oncerr=continue, iomode=test, iotype=sequential

    --> Date: July 22nd, 1999, Version: 11.14, Author: Robin T. Miller <--
% 
