NAME

st − driver for SCSI tape devices

SYNOPSIS

st@target,lun:[l,m,h,c,u][b][n]

DESCRIPTION

The st device driver is an interface to various SCSI tape devices.  Supported 1/4” cartridge devices include the Archive Viper QIC−150 streaming tape drive, the Emulex MT−02 tape controller.  Supported 1/2” and 8 mm and 4 mm devices include the HP−88780 1/2” tape drive, and the Exabyte EXB-8200/8500 8mm cartridge tape, and the Archive Python 4 mm DAT tape subsystem.  st provides a standard interface to these various devices; see mtio(7) for details. 

The driver can be opened with either rewind on close or no rewind on close options.  A maximum of four tape formats per device are supported (see FILES below).  The tape format is specified using the device name. 

Read Operation

If the driver is opened for reading in a different format than the tape is written in, the driver overrides the user selected format.  For example, if a 1/4” cartridge tape is written in QIC−24 format and opened for reading in QIC−150, the driver will detect a read failure on the first read and automatically switch to QIC−24 to read the data. 

NOTE: if the low density format is used, no indication is given that the driver has overridden the user selected format.  Other formats issue a warning message to inform the user of an overridden format selection.  Some devices automatically perform this function and do not require driver support (1/2” reel and QIC−150 tape drives, for example). 

Write Operation

Writing from the beginning of tape is performed in the user-specified format.  The original tape format is used for appending onto previously written tapes.  A warning message is issued if the driver has to override the user-specified format. 

EOT Handling

The Emulex drives have only a physical end of tape (PEOT); thus it is not possible to write past EOT.  All other drives have a logical end of tape (LEOT) before PEOT to guarantee flushing the data onto the tape.  The amount of storage between LEOT and PEOT varies from less than a megabyte to about 20 megabytes depending on the tape drive.  Further writing, except for trailer records, is inhibited to prevent running off the end of the reel. 

If EOT is encountered while writing an Emulex, no error is reported but the number of bytes transferred is zero and no further writing is allowed.  On all other drives, the first write that encounters EOT will return a short count or zero.  If a short count is returned, then the next write will return zero.  After a zero count is returned, the next write returns a full count or short count. A following write will return zero again.  It is important that the number and size of trailer records be kept as small as possible to prevent data loss.  Therefore, writing after EOT is not recommended. 

Reading past EOT is transparent to the user.  Reading is stopped only by reading EOF’s.  For 1/2” reel devices, it is possible to read off the end of the reel if you read past the two file marks which mark the end of recorded media.  All other devices have safeguards to eliminate this problem.

Ioctls

The behavior of SCSI tape positioning ioctls is the same across all devices which support them. Refer to mtio(7).  However, not all devices support all ioctls.  The driver returns an ENOTTY error on unsupported ioctls. 

The retension ioctl only applies to 1/4” cartridge tape devices.  It is used to restore tape tension thus improving the tape’s soft error rate after extensive start-stop operations or long-term storage. 

Note: the error status is reset by the MTIOCGET get status ioctl call or the next read, write, or other ioctl operation.  If no error has occurred (sense key is zero), the current file and record position is returned. 

Tape Configuration

The st tape driver has a built-in configuration table for all Sun supported tape drives. In order to support the addition of third party tape devices or to override a built-in configuration, drive information can be supplied in /kernel/drv/st.conf as global properties that apply to each node, or as properties that are applicable to one node only. The st driver looks for the property called “tape-config-list”.  The value of this property is a list of triplets, where each triplet consists of three strings. 

The formal syntax is:

tape-config-list = <triplet> [, <triplet> ∗];
where
<triplet> := <vid+pid>, <pretty print>,
<data-property-name>
and
<data-property-name> = <version>, <type>, <bsize>,
<options>, <number of densities>,
<density> [, <density> ], <default-density>;

<vid+pid> is the string that is returned by the tape device on a SCSI inquiry command.  This string may contain any character in the range 0x20-0x7e.  Characters such as “ " ” (double quote) or “ ’ ” (single quote), which are not permitted in property value strings, are represented by their octal equivalent (e.g., \042 and \047).  Trailing spaces may be truncated. 

<pretty print> is used to report the device on the console.  This string may have zero length, in which case the <vid+pid> will be used to report the device. 

<data-property-name> is the name of the property which contains all the tape configuration values (such as <type>, <bsize>, etc.) corresponding for the tape drive for the specified <vid+pid>. 

<version> is the version number and should be 1.  In the future, higher version numbers may be used to allow for changes in the syntax of the <data-property-name> value list. 

<type> is a type field. Valid types are defined in /usr/include/sys/mtio.h.  For third party tape configuration, the following generic types are recommended:

<bsize> is the preferred block size of the tape device. The value should be 0 for variable block size drives. 

<options> is a bit pattern representing the drive options, as defined in /usr/include/sys/scsi/targets/stdef.h.  Valid flags for tape configuration are:

<number of densities> is the number of densities specified.  Each tape drive can support up to four densities. The value entered should therefore be between 1 and 4; if less than 4, the remaining densities will be assigned a value of 0x0. 

<density> is a single byte hexadecimal number.  It can either be found in the drive specification manual or be obtained from the drive vendor. 

<default-density> has a value between 0 and (<number of densities> - 1).  Example of a global tape-config-list property:

#
# Copyright (c) 1992, by Sun Microsystems, Inc."
#
#ident  "@(#)st.conf    1.6     93/05/03 SMI"
tape-config-list =
        "Magic   DAT", "Magic 4mm Helical Scan", "magic-data";
magic-data    = 1,0x34,1024,0x1639,4,0,0x8c,0x8c,0x8c,3;
name="st" class="scsi"
             target=0 lun=0;
name="st" class="scsi"
             target=1 lun=0;
name="st" class="scsi"
             target=2 lun=0;
             .
             .
             .
name="st" class="scsi"
             target=15 lun=0;

Example of a tape-config-list property for target 2 only:

#
# Copyright (c) 1992, by Sun Microsystems, Inc.
#
#ident  "@(#)st.conf    1.6     93/05/03 SMI"
name="st" class="scsi"
             target=0 lun=0;
name="st" class="scsi"
             target=1 lun=0;
name="st" class="scsi"
             target=2 lun=0;
             tape-config-list =
   "Magic   DAT", "Magic 4mm Helical Scan", "magic-data"
             magic-data = 1,0x34,1024,0x1639,4,0,0x8c,0x8c,0x8c,3;
name="st" class="scsi"
             target=3 lun=0;
             .
             .
             .
name="st" class="scsi"
             target=15 lun=0;

ERRORS

EACCES The driver is opened for write access and the tape is write protected.  For writing with QIC−150 tape drives, this error is also reported if the wrong tape media is used for writing. 

EBUSY The tape drive is in use by another process.  Only one process can use the tape drive at a time.  The driver will allow  a grace period for the other process to finish before reporting this error. 

EINVAL The number of bytes read or written is not a multiple of the physical record size (fixed-length tape devices only). 

EIO   During opening, the tape device is not ready because either no tape is in the drive, or the drive is not on-line.  Once open, this error is returned if the requested I/O transfer could not be completed. 

ENOTTY This indicates that the tape device does not support the requested ioctl function. 

ENXIO During opening, the tape device does not exist. 

EPERM Another system has reserved the tape drive for its use.  The tape drive cannot be used until the other system releases it. 

FILES

/kernel/drv/st.conf
driver configuration file

/usr/include/sys/mtio.h
structures and definitions for mag tape io control commands

/usr/include/sys/scsi/targets/stdef.h
definitions for SCSI tape drives

/dev/rmt/[0− 127][l,m,h,u,c][b][n]
where l,m,h,u,c specifies the density (low, medium, high, ultra/compressed), b the optional BSD behavior (see mtio(7)), and n the optional no rewind behavior. For example, /dev/rmt/0lbn specifies unit 0, low density, BSD behavior, and no rewind.  For 1/2” reel tape devices (HP-88780), the densities are:

For helical-scan tape devices (Exabyte 8200/8500):

For 4mm DAT tape devices (Archive Python):

For QIC−150 tape devices (Archive Viper):

For QIC−24 tape devices (Emulex MT−02):

SEE ALSO

read(2), write(2), driver.conf(4), mtio(7), ioctl(9E)

DIAGNOSTICS

Error for command ’<command name>’Error Level: Fatal
Requested Block <n>, Error Block: <m>
Sense Key: <sense key name>
Vendor ’<name>’: ASC = 0x<a> (<extended sense code name>),
ASCQ = 0x<b>, FRU = 0x<c>

The command indicated by <command name> failed. The Requested Block is the block where the transfer started and the Error Block is the block that caused the error. Sense Key, ASC, and ASCQ information is returned by the target in response to a request sense command. 

write/read: not modulo <n> block size

The request size for fixed record size devices must be a multiple of the specified block size. 

recovery by resets failed

After a transport error, the driver attempted to recover with device and bus reset. This recovery failed. 

Periodic head cleaning required

The driver reported that periodic head cleaning is now required. 

Soft error rate (<n>%) during writing/reading was too high

The soft error rate has exceeded the threshold specified by the vendor. 

SCSI transport failed: reason ’xxxx’: {retrying|giving up}

The host adapter has failed to transport a command to the target for the reason stated. The driver will either retry the command or, ultimately, give up. 

BUGS

Tape devices that do not return a BUSY status during tape loading prevent user commands from being held until the device is ready.  The user must delay issuing any tape operations until the tape device is ready.  This is not a problem for Sun Microsystem Computer Corporation supplied tape devices. 

Tape devices that do not report a blank check error at the end of recorded media cause file positioning operations to fail.  Some tape drives for example, mistakenly report media error instead of blank check error. 

Sun Microsystems  —  Last change: 19 Feb 1993