Fish 'n' More 2/fishmore-publicdomainlibraryvol.ii1991xetec.iso/fish/devs&handlers/btntape/tape.doc

Text File | 1990-10-27 | 22KB | 450 lines

****    BTNtape:  a SCSI-Direct Tape Handler for AmigaDOS
****       Version 1.0   09/10/90
****       Freeware by Bob Rethemeyer   ([e-mail])
****
****    (c) Copyright 1990 Robert Rethemeyer.
****      This software may be freely distributed and redistributed,
****      for non-commercial purposes, provided this notice is included.
****      All original files must included in the distribution.

BTNtape is a "Better Than Nothing" SCSI tape device handler.  It provides
flat-file access to a SCSI tape drive from application programs using
simple DOS calls to Read() and Write().  It can also be used with the Amiga
TAR utility for disk backups.  Files may span multiple tape volumes
and may start at any tape block.  This handler requires a "SCSI-direct"
compatible hard disk driver.  It is known to work with a 3-M MCD-40 tape
drive on the CBM 2091 controller, the CBM 2090A with an ST506 hard drive,
and the Supra 4x4, and may also work with others (refer to the docs).
Included is a monitoring program which prints useful information
about handler activities, including error sense data.

This handler is probably not the all-purpose tape driver you have been waiting
for.  It won't work with any backup program which requires Exec devices.
I claim only that it works with the Amiga TAR program ported by Jonathan Hue.
But until we see good commercial or shareware tape software, you might
find this handler to be "better than nothing".

=================== ******> R E A D   T H I S <****** ======================

DISCLAIMER:
 "This software is provided 'as-is', without warranty of any kind,
either expressed or implied.  In no event will I, Robert Rethemeyer,
be liable for direct, indirect, incidental or consequential damages or
data loss resulting from the use or application of this software.  The entire
risk as to the results and performance of this software is assumed by you."

I cannot guarantee that this software will work for any combinations
of drives or controllers other than those I have specifically tested.

If you do not agree with this disclaimer,  I recommend you not use this
software;  wait for good commercial tape drivers.

============================================================================

I cannot at this time commit to adding further enhancements
or special features requested by users.  This is not to say that I won't
do these things, it's just that I can't guarantee I'll have the time
or resources.

Although this documentation refers to alleged problems with some
manufacturers' driver software, that should not be construed as a statement
about the quality of their products.  In fact, there is still a possibility
that the problems may be in my handler software or the equipment I used.

==============================================================================

DISTRIBUTION:

  The distribution should contain the following files:
        tape-handler          handler binary
        tape.c                source for main handler program
        tapeio.c              source for interface to SCSI-direct
        pktstuff.c            source for packet handling, by Phillip Lindsay
        tape.h                local include file
        tplink.h              local include file for handler/monitor structure
        tapemon               directory
           tapemon               monitor program binary
           tapemon.c             monitor source
           tapemon.doc           documentation for the monitor program
           tapemon.lmk           Lattice make file for tapemon
        mountlist             example mountlist entry
        formattape            raw command file for formatting tapes
        lmkfile               Lattice make file for handler
        makefile              Manx make file for handler
        sense.codes           describes sense codes for 3-M MCD-40 drive
        tape.doc              you're reading it


COMPATIBILITY:

  You must have hard disk driver software which honors the SCSI-direct protocol
  as defined in the "devices/scsidisk.h" include file.  Currently I know that
  the CBM 2090A, 2091, and Supra Series-II v1.10 software support this protocol.
  There are probably others which will support it also; check with your vendor.

  This handler is has been tested on the following equipment:

    Tape drives:  * 3-M Model MCD-40  40MB cartridge tape drive

    Controllers:  * Commodore 2091- works with no known problems.
                  * Commodore 2090A- works *if* the hard drive is ST506.
                  * Supra 4x4 (Amiga 1000)- works, but see Supra user notes.

  It may possibly work with other controllers:

    2090A with SCSI hard drive:  if the hard drive is on the same SCSI bus
    with the tape drive, the 2090A driver seems to go into some kind of loop
    when restoring files from tape to disk.  I believe this to be a problem
    with the 2090A driver.  You can still restore the files to RAM or floppy.

    A3000:  It is my understanding that the Amiga 3000 built-in SCSI
    controller is based on the 2091, so the handler should work with a 3000,
    but I have not tested it on one.  Ditto for the A590.

    Other SUPRA controllers:  I believe that the same Supra driver software
    is used on all their controllers.  I have only tried the handler on
    the Supra 4x4 for the A1000, but it might work with their A2000 boards.

  Other tape drives:  the handler *might* work with another SCSI tape drive
  if it supports the SCSI commands REZERO, REQUEST_SENSE, READ, and WRITE.
  The drive must also support READ_CAPACITY for end-of-tape detection to work.
  (If it does work for some other drive model, I would like to hear about it.)


INSTALLATION:

  1.  Copy the TAPE-HANDLER file to L:TAPE-HANDLER.
      Copy the TAPEMON program to C: or a directory appropriate for you.

  2.  Create an entry in DEVS:MOUNTLIST something like this:

        TAPE:  Handler = L:tape-handler
               Priority = 5         /* use 11 for Supra */
               Mount = 1            /* optional */
               Stacksize = 4000
               GlobVec = -1
               Startup = "4/1/8192/1/0/yourscsi.device"
                          | |  |   | |  |
                          | |  |   | |  +---- name of your SCSI-direct driver
                          | |  |   | +--- number of reserved tape blocks
                          | |  |   +--- number of tape blocks per buffer
                          | |  +---- tape drive block size (bytes)
                          | +---- BufMemType
                          +---- SCSI bus unit number to address tape drive

      There is nothing magic about the name TAPE:   You may use some
      other valid device name if you like.

      The Startup parameter is used by the handler to determine how
      to access your drive.  It should not have any embedded blanks
      and should be enclosed in quotes.  The parts must be separated
      by slashes. The numbers may be written as decimal, or hex in the
      "0xNN" format.   FAILURE TO ENTER PROPER INFORMATION IN STARTUP MAY
      RESULT IN PROBLEMS INCLUDING HANGS, VISITS FROM THE GURU,
      OR DATA LOSS.

      The first number is the SCSI bus unit ID of your tape drive, as it
      will be addressed by your SCSI-direct driver.  Presumably you have
      set the tape drive ID switches or jumpers to a value that is unique
      on the SCSI bus.  2090A owners- use the permuted (+3) unit number here.

      The second number is the same as BufMemType for mountlists.  Use
      0 or 1 for "any", 2 or 3 for "chip", 4 or 5 for "fast".

      The third number is the number of bytes in a SCSI logical block
      for your tape drive.

      The fourth number is the number of SCSI logical blocks to write or
      read in one I/O operation.  Some drives may be mechanically more
      efficient writing multiple blocks.  You may want to tweak this
      parameter to find out, but start with 1 to be safe (some 2090A
      owners report problems with multiple-block SCSI-direct I/O).
      This parameter also determines how much storage is needed for
      buffers.  The handler uses double buffering, so it will need
      " 2 * blocksize * numberofblocks "  bytes when you Open it.
      For example, for 8K blocks if you specify 8, then
            2*8192*8 = 128K bytes are needed.

      The fifth number is like the Reserved parameter in mountlists. It tells
      the handler how many SCSI logical blocks to skip at the beginning of
      the tape before accessing data.  You may need it if there is something
      on the front of the tape you want to preserve, like volume
      information.  In most cases you can use zero.  To read a tape, you
      must use the same reserved number with which it was written.

      The last part is the name of the device driver which provides
      the SCSI-direct command protocol.  For 2090As this is "hddisk.device";
      for Supra it is "supradirect.device".  Do not include any path
      information.  You may need to include a special character in front
      of the name to invoke bug circumventions- see the user notes below.

  3.  Install the handler in DOS using the CLI command "MOUNT TAPE:"
       Unfortunately, if the handler fails due to a mountlist or OpenDevice
       problem, there is no error indication [anyone know how I can?].
       The device will show up in ASSIGN LIST, but no handler process.
       Use ASSIGN dev REMOVE, fix the problem, and try again.


2090A USERS- NOTE

     Apparently (I don't own a 2090A) there is a software bug in the
     CBM 2090A SCSI-direct driver that causes problems with tape
     writes.  Bob Mitchell figured out that the problem can be
     circumvented by asserting data address bit 24 for writes.
     This handler can optionally invoke that circumvention.
     To do so, prefix the driver name in the Startup parameter
     with a dollar sign.  example: "4/1/8192/1/0/$hddisk.device"
     The circumvention is NOT necessary for other controllers.

     A worse problem- the 2090A cannot seem to handle both the disk
     and the tape drive on the same SCSI bus.  Strict reads and writes
     to the tape work fine, but intermixed tape reads and disk writes
     (such as during a restore) will cause the 2090A to get
     stuck in a loop reading and rereading the same block.
     This does not happen if the hard drive is on the ST506 bus.
     It also does not happen if you restore the files to RAM or floppy.

     Make sure the tape is out of the drive when you boot
     AmigaDOS;  otherwise, DOS never comes up.

     When you mount TAPE:,  make sure there is no cartridge in the
     tape drive.  For some reason I do not understand, the 2090A
     causes a reset to the tape drive when OpenDevice is called.
     If a cartridge is in the drive at that time, the system
     eventually enters an unusable state.  I recommend using
     "Mount = 1" in your MountList entry for TAPE:.  When TAPE:
     is mounted, it will put up a requester because the drive is
     empty;  click on cancel, then everything will be happy.


SUPRA USERS- NOTE

     Apparently (I DO own one) there is a problem with the Supra v1.10
     SCSI-direct software that causes the host adapter to hang when a
     non-zero byte count is supplied in the command (SCSICmd.scsi_Length).
     It works fine when a data length of zero is used.  The handler can also
     circumvent this problem. Prefix the driver name in the Startup parameter
     with a plus sign.  Example:  "4/1/8192/1/0/+supradirect.device"
     I have reported this to Supra, and they are looking into it.

     You *must* run the tape handler at a higher priority than the
     Supra driver task.  You do this by changing the "Priority ="
     line in the mountlist entry.  For Supra v1.10, the task runs
     at priority 10.  Therefore, the tape handler should run at
     "Priority = 11".  If some other Supra version runs at a different
     priority, change the mountlist priority accordingly.
     Use a utility such as Xoper or TaskX to find task priorities.

     If the cartridge is in the drive at the time you boot AmigaDOS,
     SupraMount will hang the system if it touches the tape drive.
     To avoid this, use the selective mount feature of SupraMount.
     That is, SupraMount only your disk unit.  Example: "SupraMount 6".


HOW TO USE IT

     Now that the handler is installed, how do you talk to it?
     You can use TAR, or your own application program, including ARexx.
     You can write data to the tape and later read it back in a manner
     similar to other files, using DOS calls to Open, Read, Write, and Close.

     The handler makes the tape data look like a sequential AmigaDOS file.
     There is NO FILE SYSTEM on the tape, but you may place multiple files
     on a tape by positioning the tape to specific block numbers.
     Also, files may span multiple tape volumes.

     You refer to the tape with one of the following file name forms:

       TAPE:            Rewind and open the tape at the first available block
       TAPE:*           Opens the tape at the current position (no rewind)
       TAPE:n           Opens the tape at block n  (n is a SCSI block number)
       TAPE:$$RAWCMD$$  Sends a raw SCSI command to the drive (see below)

     The TAPE:n form works only if the tape drive supports direct block access.

     The handler does not support mixed reads and writes.  That is, you may
     do only Reads or only Writes, but not both.  Seeks are not supported.
     You cannot Open the tape in "append" mode.

     Be sure your cartridge is formatted.  If you try to write to an
     unformatted tape, results will be non-optimal.  You can buy
     preformatted tapes, or you can try formatting your own-
     see the section on raw commands below.

     If there is no cartridge in the drive at the time TAPE: is
     opened, DOS will put up a requester asking for volume "TAPE"
     "in any drive".  Insert the cartridge (in the tape drive, not
     a floppy drive :-)  and click on retry after tape motion stops.

     If the application reaches the end of the tape, the handler will put up
     a requester  (if drive supports the "Read Capacity" SCSI command).
     The requester asks you to insert the next tape and click "Continue",
     or click "Quit".  The continue option allows the application program
     to access a file across multiple tape volumes without interruption.
     If you click quit, an I/O error indication is returned to the application.

     To use TAR, cd to the desired directory or partition ("cd DH0:"), then...

     To make a backup archive with TAR  :   tar -cv -f tape: ""
     To add another archive file        :   tar -cv -f tape:* ""
     To restore files from archive      :   tar -xv -f tape: *
     To restore from archive at blk 840 :   tar -xv -f tape:840 *
     To list the archive on the tape    :   tar -t  -f tape:
     To make an archive log             :   tar >logfile -t -f tape:
     To look at raw tape data           :   type tape: opt h  ... cntl-C

     When restoring files, TAR is case sensitive to the file names.
     TAR can be aborted with cntl-C.
     TAR can also make backups using a list of files from another file.
     Refer to the TAR documentation for more information.

     HELPFUL HINTS:
       - Label your tape cartridges.
       - When writing multiple files to a tape, you must write down the
          block numbers where each file starts.  Use the TAPEMON
          program to obtain the block numbers.  Example:
            File A starts at 0
            File B starts at 48
            File C starts at 224 ...
       - First time, try backing up and restoring a floppy before doing the
          same with your hard drive, to make sure the process works for you.
          For the same reason, make a HD backup to floppies first.  Then
          if the tape restore fails, you have something to fall back on.


THE MONITOR PROGRAM

     Included in with the handler is the TAPEMON program.  TAPEMON is
     a program that runs under a separate CLI and prints one-line
     messages from the handler.  The messages include the current
     tape operation and block number, and error and sense codes.
     You will need to run this program to be able to place multiple
     files on a tape.  Read TAPEMON.DOC for more information.


FINE TUNING

     There are a few factors you can tweak to get good performance
     on your particular system.  Good performance means the tape tends
     to run continuously for long periods of time and does not have
     to frequently back up to get a running start at the next block.
     The tape usually has to stop while TAR gets more data from the
     hard disk, but you can minimize it.

     The handler's "number of blocks" parameter can be increased from
     one to some larger number as your memory allows.  With more handler
     blocks, a large quantity of data is available to dump to the tape
     (but creates potentially more "dead blocks" at the end of the tape).

     The TAR program also has a block parameter.  It controls how much
     DOS data TAR collects before sending it to the handler.  If you
     increase this parameter, it makes no sense to also increase the
     handler block parameter, since the data has to go through both
     buffers anyway.  You can increase the TAR blocks if your SCSI-
     direct driver does not support multi-block operations.

     Some tape drives may support an interleave factor for the tape
     that can be specified at the time the cartridge is formatted.
     Interleave is the number of physical blocks separating adjacent
     logical blocks.  The 3-M unit defaults to interleave 2, but I find
     for my Supra that 3 prevents the tape from backing up frequently.
     It doesn't seem to make much difference with the CBM controllers.


HOW IT WORKS

     Writing to TAPE:, the handler collects the data in a memory buffer
     until the buffer is full, then the buffer is written to
     the current tape block.  Reads work in a similar manner but
     in the other direction.

     Two buffers are maintained so that one buffer can be used by DOS
     while the other is exchanging data with the drive.  This is
     supposed to help keep the tape in motion, but it may not help much
     with non-DMA controllers.

     This software does not write (or expect) anything special on
     the tape for itself.  That is to say, the data written on the
     tape is your raw data, nothing else.  If I were to use parts
     of the tape for file system information, I would be
     introducing a sort of standard-- I don't think that is a good
     idea right now.  Raw data provides a lowest common denominator
     which should help compatibility with other things.  For instance,
     a TAR tape created on a non-Amiga system should be readable
     using this handler and Amiga TAR.

     The handler does not provide a tape file system, and the tape
     does not have a volume name.  The handler assumes the tape is
     endless.  That is, it just keeps writing until you run out of tape.


FORMATTING A TAPE- the raw command interface

     This handler provides a crude means of formatting cartridges,
     without a special format program.  It's done with a built-in
     raw command mode which allows you to send your own SCSI command to
     the tape controller.  Although it might be used to send any
     command, it's really designed only to make it easy to do a format.
     There is no provision for any data transfer; don't try it.
     (As you might guess, playing with raw mode can be dangerous.)

     The raw command mode is invoked by referencing the tape file as
     "TAPE:$$RAWCMD$$".  The letters RAWCMD must be upper case and be
     enclosed by the double dollar signs.  This magic word is how
     the handler knows you want to do a raw command.

     To send a raw command, you enter the CLI command:

            TYPE filename TO TAPE:$$RAWCMD$$

     Line 1 of the file contains the bytes to be sent as the raw command,
     in ASCII format.  Only the FIRST line of the file is significant;
     you can use any following lines as comments, but the total size of
     the file must be less than the size of a tape block.
     The first line must contain ONLY hex digits and spaces.
     Each byte of the raw command should be specified as a pair of hex
     digits;  separate bytes by spaces.  Up to 32 bytes may be
     specified, but only 6 or 10 are really needed.

     The supplied file "formattape" contains the raw command bytes
     to initiate a format operation on the 3M tape drive.  Other
     tape drive models may need different data; I can't help you there.
     Look at the file for an explanation of the 3M format command bytes.


BUGS

     The handler always assumes the tape device is LUN zero.

     I have not tested this software with AmigaDOS 1.2 or 2.0
     (but it should work).

     The handler does not multi-task well, but I believe that to be
     a characteristic of the SCSI-direct drivers, not the handler.
     Don't expect to do much else while a backup is in progress.

     To read a file across multiple volumes, you must make sure that the
     blocking factor specified in Startup is the same as when the tape
     was written.  This is because there may be a few "dead blocks" at
     the end of the tape which cannot be reached, and a different blocking
     factor may make some previously written blocks unaccessible.


AUTHOR:

  Email:  [e-mail]   OR   ...!sun!portal!cup.portal.com!DrBob

  USmail: Robert Rethemeyer
          979-4 Belmont Terrace
          Sunnyvale, CA  94086


MANY THANKS GO TO:

  Bob Mitchell for the SCSI-direct programs I used to get started,
    and the 2090A circumvention.
  Phillip Lindsay for the my.handler example code.
  Rene' Vega for advice and Manxification.
  Gary Walborn, Don Camp, and Clay Jones for beta testing.