
The files in this directory are provided as examples (some better than
others) and as tests of the device objects.

Makefile

    This should be self-explanatory.

ssDevLib.cpp

    This includes all of the .Cs needed to use the SS device only.

msDevLib.cpp

    This includes all of the .Cs needed to use the MS and SS devices.

msACobj.cpp, msACobj.h

    This is an object utilized by the test(s). It contains data
    buffers and sid map information.

dlist.[ch]

    This is some doubly-linked list code used by the tests. 

TESTS:

ssDevTest.cpp

    This is not implemented yet.

msDevTest.cpp

    This is an interactive test which allows the user to exercise the
    MSDevice.

msACTest.cpp

    This is a non-interactive program which does reads and writes from
    and to an autochanger.

(...and now, REAL documentation...)

                      Using the Multisurface Device Tests
                      -----------------------------------

     There are currently two tests to help exercise the multisurface 
device code.  The first, msDevTest, is a fully interactive, menu-driven 
test designed to exercise all of the methods and functionality provided 
by the hpACDev object.  The second, msACstress, is a more-or-less
non-interactive test which performs some read/write data integrity 
checking.  It tests only a subset of the hpACDev functionality.  
The DriveDevice object (a subclass of the SSDevice) uses the native
SCSI disk driver; the hpACDev object (a subclass of the MSDevice) uses the
passthru driver and, through the DriveDevice object, the native disk
driver.

*****************************************************************************
msDevTest Usage:

./msDevTest             # Takes no command-line arguments

Once you execute the program, you will be given a prompt:

msDevTest>

Type 'help' to get a help menu:

msDevTest> help
---------------------------------------------------------------------------
register [devfile]:      Registers an autochanger device file for use with
                         the test.
map [slot side ]:        Maps a (slot,side) pair to an sid_t.
unmap [sid]:             Removes a (slot,side) to sid_t mapping.
drive [tgt lun devfile]: Maps a drive in the AC to a device file.
show:                    Shows the current surface and drive maps.
numsectors [sid]:        Displays the number of sectors for a surface.
sectorsize [sid]:        Displays the sector size of a surface.
read [sid start n]:      Reads n bytes from sector offset start.
sectorsize [sid]:        Displays the sector size of a surface.
read [sid start n]:      Reads n bytes from sector offset start.
write [sid start n buf]: Writes n bytes from sector offset start using the
                         specified data buffer.
wwoe [sid start n buf]:  Writes-without-erase n bytes from sector offset
                         start using the specified data buffer.
erase [sid start n]:     Erases n sectors from sector offset start.
verify [sid [on | off]]: Sets verify mode for specified sid.
display [page]:          Displays the specified 256-byte page from the last
                         read operation.
status:                  Displays autochanger element status information.
help:                    Displays this help menu.
quit:                    Quits the program.

You may abbreviate commands to the minimal length necessary to distinguish
them from other commands.  You must first register an autochanger and then
map surfaces.

Valid write buffer values:  [0,1,2]
----------------------------------------------------------------------------

Once in the test, you will want to perform the following steps:

1.  Register an autochanger device file with the 'register' command.  You
    must supply a passthru device file which corresponds to the autochanger's
    controller device.

2.  If you are not root, or are not running on an S700 system, you must
    use the 'drive' command to map device files to the drives in your
    autochanger.  To see a list of drives in your autochanger and their
    SCSI target and LUN values, use the 'status' command.

3.  Map surfaces for use with the test to get sid handles.  For example,
    if you want to access surfaces 1a,2a, and 4b, you would enter the
    following sequence of commands:

msDevTest> map 1a
AC:  Surface (1,0) has been mapped to sid_t 0
msDevTest> map 2a
AC:  Surface (2,0) has been mapped to sid_t 1
msDevTest> map 4b
AC:  Surface (4,1) has been mapped to sid_t 1

4.  Use the 'show' command to see a list of drive and surface mappings.

Other Usage Notes:

When you use the 'read' command, data is read from the specified surface
into an internal data buffer.  To view the data, use the 'display' command.
The display command will show the read buffer in 256-byte pages.

When you use the 'write' command, you must specify one of three data buffers
(numbered 0-2).  Buffer 0 is a repeating sequence of 'a' through 'z'; 
buffer 1 sequences from 0 to 255 in increasing order; and buffer 2 sequences
from 255 to 0 in decreasing order.

*****************************************************************************
msACstress Usage:

msACstress -d devfile -i iterations [-y] [-l logfile] surface_list

-d devfile:     Devfile is the passthru device file for the autochanger.
-i iterations:  Number of iterations for the test.
[-y]:           Optional.  If this option is given, the test will ask the
                user to provide device file mappings for drives in the
                autochanger.  Otherwise, the test will attempt to create
                device files for the drives (you must be root for this to
                succeed).
[-l logfile]:   Optional.  If specified, all test output will be appended
                to the specified file.  If not specified, all output will
                be send to stdout.
surface_list:  A list of one or more entries of the form [slot_number][A|B]

Example:

./msACstress -d ac1 -i 100 1A 1B 2A 3A

     If you are not running as root, or not on an S700, you must specify the
-y option.  When you do so, the program will query you to supply a disk
character device file for each drive in the autochanger.  As it does so it
will show you the SCSI target and LUN of each drive in sequence.  Currently,
the hpACDev object cannot generate disk device files on the S800.  Only
series 700 machines running HP-UX 9.0x are supported for automatic disk
device file generation.





