NAME

st − Driver for SCSI Tape Controllers

CONFIG — SOLBOURNE SERIES 4, 5, 5E

controller si0 at kbio ? csr ? priority 2
tape st0 at si0 drive 0x04
tape st1 at si0 drive 0x05

CONFIG — SOLBOURNE S4000

controller si0 at obio ? csr 0x20 priority 4
tape st0 at si0 drive 0x04
tape st1 at si0 drive 0x05

All SCSI devices in a Solbourne system use a three layer device driver scheme. The top layer supports a specific type of device (for example disk sd(4s), or tape st(4s)), the middle layer contains common code (scsi(4)), and the lower layer supports specific host adaptor hardware (for example SCSI IOASIC si(4), or SCSI Rimfire sr(4s)).  This man page describes the top layer operations for SCSI tapes.  It provides a standard tape interface ( see mtio(4)) to tape devices on the SCSI bus. 

The first two controller lines above specify SCSI host adapters on a Solbourne system (see si(4S), and sr(4S).  The two tape lines specify the first tape drive on each controller. 

The drive value is calculated using the formula:

16∗lun+target

where target is the SCSI target, and lun is the SCSI logical unit. 

Bit 0 of flags may be SET to specify that the device does NOT support disconnect/reconnect on the SCSI bus.  Bit 1 of flags may be SET to specify that the driver should negotiate with the device for synchronous SCSI transfers.  Bit 2 of flags may be SET to specify that the device does NOT support parity on the SCSI bus.  Bit 3 of flags may be set to specify that standard commands that are going to transfer a small amount of data can, if nothing else is active, avoid doing a disconnect.  Bit 4 of flags may be set to specify the device supports multiple luns active simultaneously.  Bit 5 of flags may be set to specify the device supports only simple (COMMAND_COMPLETE) SCSI messages.  Bit 6 of flags may be set to specify that command combining optimizations can be performed. 

The file /sys/dev/stconf.c contains a description of tape devices supported by the driver.  Support for new tape devices can be added by describing drive operation in this file. 

DESCRIPTION

The driver can be opened with either rewind on close (/dev/rst∗) or no rewind on close (/dev/nrst∗) options.  A maximum of four tape formats per device are supported (see FILES below).  The tape format is specified using the device name.  The four rewind on close formats for st0, for example, are /dev/rst0, /dev/rst8, /dev/rst16, and /dev/rst24. 

Bits 0 and 1 of the minor device number select the drive. Bit 2 of the minor device number selects the rewind (CLEAR) or no-rewind (SET) device.  Bits 3 and 4 of the minor device number select the tape format.  Bit 5 of the minor device number determines speed; CLEAR for low SET for high.  Bit 6 of the minor device number determines if the drive is buffered (CLEAR) or unbuffered (SET). 

Read Operation

Fixed-length I/O tape devices require the number of bytes read or written to be a multiple of the physical record size.  For example, 1/4−inch cartridge tape devices only read or write multiples of 512 bytes. 

Fixed-length tape devices read or write multiple records if the blocking factor is greater than 64512 bytes (minphys limit).  These multiple writes are limited to 64512 bytes.  For example, if a write request is issued for 65536 bytes using a 1/4−inch cartridge tape, two writes are issued; the first for 64512 bytes and the second for 1024 bytes. 

Tape devices, which support variable-length I/O operations, such as 1/2−inch reel tape, may read or write a range of 1 to 65535 bytes.  If the record size exceeds 65535 bytes, the driver reads or writes multiple records to satisfy the request.  These multiple records are limited to 65534 bytes.  As an example, if a write request for 65540 bytes is issued using 1/2−inch reel tape, two records are written; one for 65534 bytes followed by one for 6 bytes. 

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−inch cartridge tape is written in QIC-24 format and opened for reading in QIC−11, the driver will detect a read failure on the first read and automatically switch to QIC−24 to recover the data. 

Note: If the /dev/∗st[0−3] 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−inch reel and QIC−150 tape drives for example). 

If a file mark is encountered during reading, no error is reported but the number of bytes transferred is zero.  The next read operation reads into the next file. 

End of media is indicated by two successive zero transfer counts.  No further reading should be performed past the end of recorded media. 

If the read request size is 2048 bytes, the tape driver behaves as a disk device and honors seek positioning requests (see lseek(2)).  If a file mark is crossed during a read operation, this function is disabled. 

Write Operation

Writing is allowed at either the beginning of tape or after the last written file on the tape.  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. 

Care should be used when appending files onto 1/2−inch reel tape devices, since an extra file mark is appended after the last file to mark the end of recorded media.  In other words, the last file on the tape ends with two file marks instead of one.  This extra file mark must be overwritten to prevent the creation of a null file.  To facilitate write append operations, a space to the end of recorded media ioctl is provided to eliminate this problem by having the driver perform the positioning operation. 

If the end of tape is encountered during writing, no error is reported but the number of bytes transferred is zero and no further writing is allowed.  Trailer records may be written by first writing a file mark followed by the trailer records.  It is important that these trailer records be kept as short as possible to prevent data loss. 

Close Operation

If data was written, a file mark is automatically written by the driver upon close.  If the rewinding device name is used, the tape will be rewound after the file mark is written.  If the user wrote a file mark prior to closing, then no file mark is written upon close.  If a file positioning ioctl, like rewind, is issued after writing, a file mark is written before repositioning the tape. 

Note:  For 1/2−inch reel tape devices, two file marks are written to mark the end of recorded media before rewinding or performing a file positioning ioctl.  If the user wrote a file mark before closing a 1/2−inch reel tape device, the driver will always write a file mark before closing to insure that the end of recorded media is marked properly. 

If no data was written and the driver was opened for WRITE-ONLY access, a file mark is written thus creating a null file. 

IOCTLS

The following ioctls are supported: forwardspace record, forwardspace file, backspace record, backspace file, backspace file mark, rewind, write file mark, offline, erase, retension, space to EOM, and get status. 

The backspace file and forwardspace file tape operations are inverses. Thus, a forwardspace “−1” file is equivalent to a backspace “1” file.  A backspace “0” file is the same as forwardspace “0” file; both position the tape device to the beginning of the current file. 

Backspace file mark moves the tape backwards by file marks.  The tape position will end on the beginning of tape side of the desired file mark.  Devices which do not support this function, such as 1/4−inch cartridge tape, return an ENXIO error. 

Backspace record and forwardspace record operations perform much like space file operations, except that they move by records instead of files.  Variable-length I/O devices (1/2−inch reel, for example) space actual records; fixed-length I/O devices space physical records (blocks).  1/4−inch cartridge tape, for example, spaces 512 byte physical records.  The status ioctl residue count contains the number of files or records not skipped.  Record skipping does not go past a file mark; file skipping does not go past the end of recorded media. 

Spacing to the end of recorded media positions the tape at a location just after the last file written on the tape.  For 1/4−inch cartridge tape, this is after the last file mark on the tape.  For 1/2−inch reel tape, this is just after the first file mark but before the second (and last) file mark on the tape.  Additional files can then be appended onto the tape from that point. 

The offline ioctl rewinds and, if appropriate, takes the device offline by unloading the tape.  Tape must be inserted before the tape device can be used again. 

The erase ioctl rewinds the tape, erases it completely, and returns to the beginning of tape. 

The retension ioctl only applies to 1/4−inch cartridge tape devices.  It is used to restore tape tension improving the tape’s soft error rate after extensive start-stop operations or long-term storage.  Devices which do not support this function, such as 1/2−inch reel tape, return an ENXIO error. 

The get status ioctl call returns the drive id (mt_type), sense key error (mt_erreg), file number (mt_fileno), and record number (mt_blkno) of the last error.  The residue count (mt_resid) is set to the number of bytes not transferred or files/records not spaced. 

Note: The error status is reset by the 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 are returned. 

ERRORS

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

EBUSY The tape device is already in use. 

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. 

ENOMEM During a read of a variable block size tape the size of a block was larger than the amount of data specified by the read. 

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

ENXIO During opening, the tape device does not exist.  On ioctl functions, this indicates that the tape device does not support the ioctl function. 

FILES

For 1/2−inch reel tape devices:
/dev/rst[0−3]   1600 BPI density
/dev/rst[8−11]  6250 BPI density
/dev/rst[16−20] 800 BPI density
/dev/rst[24−28] data compression
/dev/nrst[0−3] non-rewinding 1600 BPI density
/dev/nrst[8−11] non-rewinding 6250 BPI density
/dev/nrst[16−19] non-rewinding 800 density
/dev/nrst[24−27] non-rewinding data compression

For QIC−150 tape devices:
/dev/rst[0−3]  QIC−150 Format
/dev/rst[8−11] QIC−150 Format
/dev/rst[16−20] QIC−150 Format
/dev/rst[24−28] QIC−150 Format
/dev/nrst[0−3] non-rewinding QIC−150 Format
/dev/nrst[8−11] non-rewinding QIC−150 Format
/dev/nrst[16−19] non-rewinding QIC−150 Format
/dev/nrst[24−27] non-rewinding QIC−150 Format

For QIC−24 tape devices:
/dev/rst[0−3]  QIC−11 Format
/dev/rst[8−11] QIC−24 Format
/dev/rst[16−20] QIC−24 Format
/dev/rst[24−28] QIC−24 Format
/dev/nrst[0−3] non-rewinding QIC−11 Format
/dev/nrst[8−11] non-rewinding QIC−24 Format
/dev/nrst[16−19] non-rewinding QIC−24 Format
/dev/nrst[24−27] non-rewinding QIC−24 Format

For EXABYTE 8mm Helical tape devices:
/dev/rst[0−3]   EXABYTE Helical data format
/dev/nrst[0−3] non-rewinding EXABYTE Helical data format

Note:  The QIC−24 format is preferred over QIC−11. 

SEE ALSO

mt(1), tar(1), mtio(4), scsi(4S), si(4S), sr(4S), dump(8), restore(8). 

DIAGNOSTICS

st%d: adaptor%d target %d lun %d: lun not supported. 
The lun is not supported by the target.

st%d: adaptor%d target %d lun %d: 0x%x not a DISK. 
The target is not a tape. Check the target id jumpered on the drive.

st%d: adaptor%d target %d lun %d: online: %8s %16s %4s
The drive is now online.

st%d: drive not supported: offline
The drive is not described in the file /sys/dev/stconf.c and therefor cannot be used.

st%d: adaptor%d target %d lun %d: offline
The drive has been placed offline. CCS Tape operations. 

st%d: no tape loaded or drive offline. 

st%d: tape is write protected. 
Tape was opened for WRITE ONLY operations and the media is write protected. 

st%d: aborted after scsi bus reset. 
A SCSI bus reset occurred during tape operation and tape position was lost. This is a fatal error.

st%d: byte count must be between %d and %d. 
The number of bytes specified for a tape operation on a variable block length tape drive is outside the limits of the drives single-record capabilities.

st%d: byte count not modulo %d block size. 
The number of bytes specified for a tape operation on a fixed block size tape drive is not modulo the fixed block size.

st%d: unexpected EOT/BOT. 
End of tape was encountered.

st%d: tape not ready. 

st%d: tape changed. 
The tape was changed while the device was open.

st%d: write protected. 
Attempt to write to a write protected tape.

st%d: file mark write failed. 

st%d: rewind failed. 

st%d: warning: tape wearing out or head needs cleaning: %d retries
The number of allowable soft errors has been exceeded for this tape.  Either the tape heads need cleaning or the tape is wearing out. If the tape is wearing out, continued usage of it is not recommended.

BUGS

The driver will only write an end of file mark on close if the last operation was a write, without regard for the mode used when opening the file.  Empty files will be deleted on a raw tape copy operation. 

EOM is interpreted as an EOT, data beyond EOM cannot be accessed. 

Solbourne Computer, Inc.  —  26 December 1990