Merge commit '9276b3991ba20d5a5660887ba81b0bc7bed25a0c'

[unleashed.git] / share / man / man7d / st.7d

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ST 7D "April 9, 2016"
.SH NAME
st \- driver for SCSI tape devices
.SH SYNOPSIS
.LP
.nf
\fBst@\fR\fItarget\fR\fB,\fR\fIlun\fR\fB:\fR\fIl\fR\fB,\fR\fIm\fR\fB,\fR\fIh\fR\fB,\fR\fIc\fR\fB,\fR\fIu\fR\fIb\fR\fIn\fR
.fi

.SH DESCRIPTION
.LP
The \fBst\fR device driver provides a standard interface to various \fBSCSI\fR
tape devices. See \fBmtio\fR(7I) for details.
.sp
.LP
To determine if the \fBst\fR device driver supports your tape device, SPARC
users should enter the following on a command line:
.sp
.in +2
.nf
% strings /kernel/drv/sparcv9/st | grep -i <tape device name>
.fi
.in -2

.sp
.LP
x86 users can do the following to determine if the \fBst\fR device driver
supports a particular tape device:
.sp
.in +2
.nf
% strings /kernel/drv/st | grep -i <tape device name>
.fi
.in -2

.sp
.LP
The driver can be opened with either rewind on close or no rewind on close
options. It can also be opened with the \fBO_NDELAY\fR (see \fBopen\fR(2))
option when there is no tape inserted in the drive. A maximum of four tape
formats per device are supported (see \fBFILES\fR below). The tape format is
specified using the device name. (Tape format is also referred to as tape
density).
.sp
.LP
Following are a list of SCSI commands that can be executed while another host
reserves the tape drive. The commands are:
.sp
.in +2
.nf
SCMD_TEST_UNIT_READY
SCMD_REQUEST_SENSE
SCMD_READ_BLKLIM
SCMD_INQUIRY
SCMD_RESERVE
SCMD_RELEASE
SCMD_DOORLOCK
SCMD_REPORT_DENSITIES
SCMD_LOG_SENSE_G1
SCMD_PERSISTENT_RESERVE_IN
SCMD_PERSISTENT_RESERVE_OUT
SCMD_REPORT_LUNS
.fi
.in -2

.sp
.LP
In multi-initiator environments, the driver will not reserve  the tape drive if
above commands are issued. For other SCSI commands, the driver reserves the
tape drive and releases the drive at close if  it has been reserved. Refer to
the MTIOCRESERVE and MTIOCRELEASE ioctls  in \fBmtio\fR(7I) for information
about how to allow a tape drive to remain  reserved upon close. See the flag
options below for information about  disabling this feature.
.sp
.LP
If a SCSI-3 persistent reservation is done through the driver, the  driver
disables all existing SCSI-2 reservations.
.sp
.LP
If the tape drive is opened in O_NDELAY mode, no reservation occurs  during the
open, as per the POSIX standard (see \fBstandards\fR(5)). However, if a command
not found in the above list is used, a  reservation will occur to provide
reserve/release functionality before the command is issued.
.SS "Persistent Errors and Asynchronous Tape Operation"
.LP
The \fBst\fR driver now supports persistent errors (see \fBmtio\fR(7I) and
asynchronous tape operations (see \fBmtio\fR(7I), \fBaioread\fR(3C), and
\fBaiowrite\fR(3C)).
.SS "Read Operation"
.LP
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 detects a read failure on the first read and automatically
switches to QIC-24 to read the data.
.sp
.LP
Note that if the low density format is used, no indication is given that the
driver has overridden the format you selected. Other formats issue a warning
message to inform you of an overridden format selection. Some devices
automatically perform this function and do not require driver support (1/2"
reel tape drive, for example).
.SS "Write Operation"
.LP
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.
.SS "Tape Configuration"
.LP
The \fBst\fR driver has a built-in configuration table for most Sun-supported
tape drives. For those tape drives that are not in the table, the \fBst\fR
driver tries to read the configuration from the tape drive through optional
SCSI-3 commands. To support the addition of third party tape devices which are
not in the  built-in configuration table or not able to report their
configuration, device information can be supplied in \fBst.conf\fR as global
properties that apply to each node, or as properties that are applicable to one
node only. By supplying the information in \fBst.conf\fR, the built-in
configuration is overridden and the \fBst\fR driver will not query the
configuration from tape drives. The \fBst\fR driver looks for the property
called \fBtape-config-list\fR. The value of this property is a list of
triplets, where each triplet consists of three strings.
.sp
.LP
The formal syntax is:
.sp
.in +2
.nf
tape-config-list = <triplet> [, <triplet> *];
.fi
.in -2
.sp

.sp
.LP
where
.sp
.in +2
.nf
<triplet> := <vid+pid>, <pretty print>, <data-property-name>
.fi
.in -2
.sp

.sp
.LP
and
.sp
.in +2
.nf
<data-property-name> = <version>, <type>, <bsize>,
        <options>, <number of densities>,
        <density> [, <density>*], <default-density>;
.fi
.in -2
.sp

.sp
.LP
or
.sp
.in +2
.nf
<data-property-name> = <version 2>, <type>, <bsize>,
                <options>, <number of densities>,
                <density> [, <density>*], <default-density>,
                <non-motion time-out>, <I/O time-out>,
                <rewind time-out>, <space time-out>,
                <load time-out>, <unload time-out>,
                <erase time-out>;
.fi
.in -2
.sp

.sp
.in +2
.nf

.fi
.in -2

.sp
.LP
A semicolon (\fB;\fR) is used to terminate a prototype devinfo node
specification. Individual elements listed within the specification should not
be separated by a semicolon. (Refer to \fBdriver.conf\fR(4) for more
information.)
.sp
.LP
\fB<vid+pid>\fR is the string that is returned by the tape device on a
\fBSCSI\fR inquiry command. This string may contain any character in the range
\fB0x20-0x7e\fR. Characters such as " " " (double quote) or " ' " (single
quote), which are not permitted in property value strings, are represented by
their octal equivalent (for example, \fB\e042\fR and \fB\e047\fR). Trailing
spaces may be truncated.
.sp
.LP
\fB<pretty print>\fR is used to report the device on the console. This string
may have zero length, in which case the \fB<vid+pid>\fR will be used to report
the device.
.sp
.LP
\fB<data-property-name>\fR is the name of the property which contains all the
tape configuration values (such as \fB<type>\fR, \fB<bsize>\fR, etc.)
corresponding for the tape drive for the specified \fB<vid+pid>\fR\&.
.sp
.LP
\fB<version>\fR is a version number and should be 1 or 2. In the future, higher
version numbers may be used to allow for changes in the syntax of the
\fB<data-property-name>\fR value list.
.sp
.LP
\fB<type>\fR is a type field. Valid types are defined in
\fB/usr/include/sys/mtio.h\fR. For third party tape configuration, the
following generic types are recommended:
.sp

.sp
.TS
l l
l l .
\fBMT_ISQIC\fR  0x32
\fBMT_ISREEL\fR 0x33
\fBMT_ISDAT\fR  0x34
\fBMT_IS8MM\fR  0x35
\fBMT_ISOTHER\fR        0x36
\fBMT_ISTAND25G\fR      0x37
\fBMT_ISDLT\fR  0x38
\fBMT_ISSTK9840\fR      0x39
\fBMT_ISBMDLT1\fR       0x3A
\fBMT_LTO\fR    0x3B
.TE

.sp
.LP
\fB<bsize>\fR is the preferred block size of the tape device. The value should
be \fB0\fR for variable block size devices.
.sp
.LP
\fB<options>\fR is a bit pattern representing the devices, as defined in
\fB/usr/include/sys/scsi/targets/stdef.h\fR. Valid flags for tape configuration
are shown in the following table. Note that this table does not list flags that
are non-configurable in \fBst.conf\fR (including \fBST_KNOWS_MEDIA\fR which
uses the media type reported from the mode select data to select the correct
density code).
.sp

.sp
.TS
l l
l l .
\fBST_VARIABLE\fR       0x0001
\fBST_QIC\fR    0x0002
\fBST_REEL\fR   0x0004
\fBST_BSF\fR    0x0008
\fBST_BSR\fR    0x0010
\fBST_LONG_ERASE\fR     0x0020
\fBST_AUTODEN_OVERRIDE\fR       0x0040
\fBST_NOBUF\fR  0x0080
\fBST_KNOWS_EOD\fR      0x0200
\fBST_UNLOADABLE\fR     0x0400
\fBST_SOFT_ERROR_REPORTING\fR   0x0800
\fBST_LONG_TIMEOUTS\fR  0x1000
\fBST_NO_RECSIZE_LIMIT\fR       0x8000
\fBST_MODE_SEL_COMP\fR  0x10000
\fBST_NO_RESERVE_RELEASE\fR     0x20000
\fBST_READ_IGNORE_ILI\fR        0x40000
\fBST_READ_IGNORE_EOFS\fR       0x80000
\fBST_SHORT_FILEMARKS\fR        0x100000
\fBST_EJECT_TAPE_ON_CHANGER_FAILURE\fR  0x200000
\fBST_RETRY_ON_RECOVERED_DEFERRED_ERROR\fR      0x400000
\fBST_WORMABLE\fR       0x1000000
.TE

.sp
.ne 2
.na
\fB\fBST_VARIABLE\fR\fR
.ad
.sp .6
.RS 4n
The flag indicates the tape device supports variable length record sizes.
.RE

.sp
.ne 2
.na
\fB\fBST_QIC\fR\fR
.ad
.sp .6
.RS 4n
The flag indicates a Quarter Inch Cartridge (QIC) tape device.
.RE

.sp
.ne 2
.na
\fB\fBST_REEL\fR\fR
.ad
.sp .6
.RS 4n
The flag indicates a 1/2\(miinch reel tape device.
.RE

.sp
.ne 2
.na
\fB\fBST_BSF\fR\fR
.ad
.sp .6
.RS 4n
If flag is set, the device supports backspace over EOF marks (bsf - see
\fBmt\fR(1)).
.RE

.sp
.ne 2
.na
\fB\fBST_BSR\fR\fR
.ad
.sp .6
.RS 4n
If flag is set, the tape device supports the backspace record operation (bsr -
see \fBmt\fR(1)). If the device does not support bsr, the \fBst\fR driver
emulates the action by rewinding the tape and using the forward space record
(fsf) operation to forward the tape to the correct file. The driver then uses
forward space record (fsr - see \fBmt\fR(1)) to forward the tape to the correct
record.
.RE

.sp
.ne 2
.na
\fB\fBST_LONG_ERASE\fR\fR
.ad
.sp .6
.RS 4n
The flag indicates the tape device needs a longer time than normal to erase.
.RE

.sp
.ne 2
.na
\fB\fBST_AUTODEN_OVERRIDE\fR\fR
.ad
.sp .6
.RS 4n
The auto-density override flag. The device is capable of determining the tape
density automatically without issuing a "mode-select"/"mode-sense command."
.RE

.sp
.ne 2
.na
\fB\fBST_NOBUF\fR\fR
.ad
.sp .6
.RS 4n
The flag disables the device's ability to perform buffered writes. A buffered
write occurs when the device acknowledges the completion of a write request
after the data has been written to the device's buffer, but before all of the
data has been written to the tape.
.RE

.sp
.ne 2
.na
\fB\fBST_KNOWS_EOD\fR\fR
.ad
.sp .6
.RS 4n
If flag is set, the device can determine when EOD (End of Data) has been
reached. When this flag is set, the \fBst\fR driver uses fast file skipping.
Otherwise, file skipping happens one file at a time.
.RE

.sp
.ne 2
.na
\fB\fBST_UNLOADABLE\fR\fR
.ad
.sp .6
.RS 4n
The flag indicates the device will not complain if the \fBst\fR driver is
unloaded and loaded again (see \fBmodload\fR(8) and \fBmodunload\fR(8)). That
is, the driver will return the correct inquiry string.
.RE

.sp
.ne 2
.na
\fB\fBST_SOFT_ERROR_REPORTING\fR\fR
.ad
.sp .6
.RS 4n
The flag indicates the tape device will perform a "request sense" or "log
sense" command when the device is closed. Currently, only Exabyte and \fBDAT\fR
drives support this feature.
.RE

.sp
.ne 2
.na
\fB\fBST_LONG_TIMEOUTS\fR\fR
.ad
.sp .6
.RS 4n
The flag indicates the tape device requires timeouts that are five times longer
than usual for normal operation.
.RE

.sp
.ne 2
.na
\fB\fBST_NO_RECSIZE_LIMIT\fR \fR
.ad
.sp .6
.RS 4n
The flag applies to variable-length tape devices. If this flag is set, the
record size is not limited to a 64 Kbyte record size. The record size is only
limited by the smaller of either the record size supported by the device or the
maximum DMA transfer size of the system. (Refer to \fBLarge Record Sizes\fR and
\fBWARNINGS\fR.) The maximum block size that will not be broken into smaller
blocks can be determined from the mt_bf returned from the MTIOCGET ioctl().
This number is the lesser of the upper block limit returned by the drive from
READ BLOCK LIMITS command and the dma-max property set by the Host Bus Adapter
(HBA) to which the drive is attached.
.RE

.sp
.ne 2
.na
\fB\fBST_MODE_SEL_COMP\fR\fR
.ad
.sp .6
.RS 4n
If the \fBST_MODE_SEL_COMP\fR flag is set, the driver determines which of the
two mode pages the device supports for selecting or deselecting compression. It
first tries the Data Compression mode page (\fB0x0F\fR); if this fails, it
tries the Device Configuration mode page (\fB0x10\fR). Some devices, however,
may need a specific density code for selecting or deselecting compression.
Please refer to the device specific \fBSCSI\fR manual. When the flag is set,
compression is enabled only if the "c" or "u" device is used. Note that when
the lower 2 densities of a drive are identically configured and the upper 2
densities are identically configured, but the lower and upper differ from each
other and ST_MODE_SEL_COMP is set, the "m" node sets compression \fBon\fR for
the lower density code (for example, 0x42) and the "c" and "u" nodes set
compression \fBon\fR for the higher density (for example, 0x43). For any other
device densities, compression is disabled.
.RE

.sp
.ne 2
.na
\fB\fBST_NO_RESERVE_RELEASE\fR\fR
.ad
.sp .6
.RS 4n
The \fBST_NO_RESERVE_RELEASE\fR flag disables the use of reserve on open and
release on close. If an attempt to use a ioctl of \fBMTRESERVE\fR or
\fBMTRELEASE\fR on a drive with this flag set, it will return an error of
\fBENOTTY\fR (inappropriate ioctl for device).
.RE

.sp
.ne 2
.na
\fB\fBST_READ_IGNORE_ILI\fR\fR
.ad
.sp .6
.RS 4n
The \fBST_READ_IGNORE_ILI\fR flag is applicable only to variable block devices
which support the SILI bit option. The \fBST_READ_IGNORE_ILI\fR flag indicates
that SILI (suppress incorrect length indicator) bit will be set during reads.
When this flag is set, short reads (requested read size is less than the record
size on the tape) will be successful and the number of bytes transferred will
be equal to the record size on the tape. The tape will be positioned at the
start of the next record skipping over the extra data (the remaining data has
been has been lost). Long reads (requested read size is more than the record
size on the tape) will see a large performance gain when this flag is set, due
to overhead reduction. When this flag is not set, short reads will return an
error of \fBENOMEM\fR.
.RE

.sp
.ne 2
.na
\fB\fBST_READ_IGNORE_EOFS\fR\fR
.ad
.sp .6
.RS 4n
The \fBST_READ_IGNORE_EOFS\fR flag is applicable only to 1/2" Reel Tape drives
and when performing consecutive reads only. It should not be used for any other
tape command. Usually End-of-recorded-media (EOM) is indicated by two EOF marks
on 1/2" tape and application cannot read past EOM. When this flag is set, two
EOF marks no longer indicate EOM allowing applications to read past two EOF
marks. In this case it is the responsibility of the application to detect
end-of-recorded-media (EOM). When this flag is set, tape operations (like
MTEOM) which positions the tape at end-of-recorded-media will fail since
detection of end-of-recorded-media (EOM) is to be handled by the application.
This flag should be used when backup applications have embedded double
filemarks between files.
.RE

.sp
.ne 2
.na
\fB\fBST_SHORT_FILEMARKS\fR\fR
.ad
.sp .6
.RS 4n
The \fBST_SHORT_FILEMARKS\fR flag is applicable only to EXABYTE 8mm tape drives
which supports short filemarks. When this flag is set, short filemarks is used
for writing filemarks. Short filemarks could lead to tape incompatible with
some otherwise compatible device. By default long filemarks will be used for
writing filemarks.
.RE

.sp
.ne 2
.na
\fB\fBST_EJECT_TAPE_ON_CHANGER_FAILURE\fR\fR
.ad
.sp .6
.RS 4n
If \fBST_EJECT_TAPE_ON_CHANGER_FAILURE\fR flag is set, the tape is ejected
automatically if the tape cartridge is trapped in the medium due to positioning
problems of the medium changer.
.sp
The following ASC/ASCQ keys are defined to the reasons for causing tape
ejection if \fBST_EJECT_TAPE_ON_CHANGER_FAILURE\fR option is set to 0x200000:
.sp
Sense  ASC/ASCQ  Description
.sp
Key
.sp
4      15/01     Mechanical Failure
.sp
4      44/00     Internal Target Failure
.sp
2      53/00     Media Load or Eject Failed
.sp
4      53/00     Media Load or Eject Failed
.sp
4      53/01     Unload Tape Failure
.RE

.sp
.ne 2
.na
\fB\fBST_RETRY_ON_RECOVERED_DEFERRED_ERROR\fR\fR
.ad
.sp .6
.RS 4n
If \fBST_RETRY_ON_RECOVERED_DEFERRED_ERROR\fR flag is set, the \fBst\fR driver
will retry the last write if this cmd caused a check condition with error code
0x71 and sense code 0x01. Some tape drives, notably the IBM 3090, require this
option.
.RE

.sp
.ne 2
.na
\fB\fBST_WORMABLE\fR\fR
.ad
.sp .6
.RS 4n
When \fBST_WORMABLE\fR is set, \fBst\fR attempts to detect the presence of WORM
media in the device.
.RE

.sp
.LP
\fB<number of densities>\fR is the number of densities specified. Each tape
drive can support up to four densities. The value entered should therefore be
between \fB1\fR and \fB4\fR; if less than \fB4\fR, the remaining densities will
be assigned a value of \fB0x0\fR.
.sp
.LP
\fB<density>\fR is a single-byte hexadecimal number. It can either be found in
the device specification manual or be obtained from the device vendor.
.sp
.LP
\fB<default-density>\fR has a value between \fB0\fR and (<number of densities>
- \fB1\fR).
.sp
.LP
\fB<non-motion time-out>\fR Time in seconds that the drive should be able to
perform any SCSI command that doesn't require tape to be moved. This includes
mode sense, mode select, reserve, release, read block limits, and test unit
ready.
.sp
.LP
\fB<I/O time-out>\fR Time in seconds to perform data transfer I/O to or from
tape including worst case error recovery.
.sp
.LP
\fB<rewind time-out>\fR Time in seconds to rewind from anywhere on tape to BOT
including worst case recovery forcing buffered write data to tape.
.sp
.LP
\fB<space time-out>\fR Time in seconds to space to any file, block or end of
data on tape. Including worst case when any form of cataloging is invalid.
.sp
.LP
\fB<load time-out>\fR Time in seconds to load tape and be ready to transfer
first block. This should include worst case recovery reading tape catalog or
drive specific operations done at load.
.sp
.LP
\fB<unload time-out>\fR Time in seconds to unload tape. Should include worst
case time to write to catalog, unthread, and tape cartridge unloading. Also
should include worst case time for any drive specific operations that are
preformed at unload. Should not include rewind time as the driver rewinds tape
before issuing the unload.
.sp
.LP
\fB<erase time-out>\fR Time in seconds to preform a full (BOT to EOT) erase of
longest medium with worst case error recovery.
.SS "Device Statistics Support"
.LP
Each device maintains I/O statistics both for the device and for each partition
allocated on that device. For each device/partition, the driver accumulates
reads, writes, bytes read, and bytes written. The driver also takes
hi-resolution time stamps at queue entry and exit points, which facilitates
monitoring the residence time and cumulative residence-length product for each
queue.
.sp
.LP
Each device also has error statistics associated with it. These must include
counters for hard errors, soft errors and transport errors. Other data may be
implemented as required.
.SH IOCTLS
.LP
The behavior of \fBSCSI\fR tape positioning ioctls is the same across all
devices which support them. (Refer to \fBmtio\fR(7I).) However, not all devices
support all ioctls. The driver returns an \fBENOTTY\fR error on unsupported
ioctls.
.sp
.LP
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.
.sp
.LP
In order to increase performance of variable-length tape devices (particularly
when they are used to read/write small record sizes), two operations in the
\fBMTIOCTOP\fR ioctl, \fBMTSRSZ\fR and \fBMTGRSZ\fR, can be used to set and get
fixed record lengths. The ioctl also works with fixed-length tape drives which
allow multiple record sizes. The min/max limits of record size allowed on a
driver are found by using a SCSI-2 \fBREAD\fR \fBBLOCK\fR \fBLIMITS\fR command
to the device. If this command fails, the default min/max record sizes allowed
are 1 byte and 63k bytes. An application that needs to use a different record
size opens the device, sets the size with the \fBMTSRSZ\fR ioctl, and then
continues with I/O. The scope of the change in record size remains until the
device is closed. The next open to the device resets the record size to the
default record size (retrieved from \fBst.conf\fR).
.sp
.LP
Note that the error status is reset by the \fBMTIOCGET\fR get status ioctl call
or by the next read, write, or other ioctl operation. If no error has occurred
(sense key is \fB0\fR), the current file and record position is returned.
.SH ERRORS
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
The driver is opened for write access and the tape is write-protected or the
tape unit is reserved by another host.
.RE

.sp
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 10n
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.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The number of bytes read or written is not a multiple of the physical record
size (fixed-length tape devices only).
.RE

.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 10n
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.
.RE

.sp
.ne 2
.na
\fB\fBENOTTY\fR\fR
.ad
.RS 10n
This indicates that the tape device does not support the requested ioctl
function.
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 10n
During opening, the tape device does not exist.
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
This indicates that the record size on the tape drive is more than the
requested size during read operation.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRGlobal tape-config list property
.sp
.LP
The following is an example of a global \fBtape-config-list\fR property:

.sp
.in +2
.nf
tape-config-list =
"Magic DAT", "Magic 4mm Helical Scan", "magic-data",
"Major Appliance", "Major Appliance Tape", "major-tape";


magic-data  = 1,0x34,1024,0x1639,4,0,0x8c,0x8c,0x8c,3;
major-tape = 2,0x3c,0,0x18619,4,0x0,0x0,0x0,0x0,
             3,0,0,30,120,0,0,36000;

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=6 lun=0;
.fi
.in -2

.LP
\fBExample 2 \fRTape-config-list property applicable to target 2 only
.sp
.LP
The following is an example of a tape-config-list property applicable to target
2 only:

.sp
.in +2
.nf
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=6 lun=0;
.fi
.in -2

.SS "Large Record Sizes"
.LP
To support applications such as seismic programs that require large record
sizes, the flag \fBST_NO_RECSIZE_LIMIT\fR must be set in drive option in the
configuration entry. A SCSI tape drive that needs to transfer large records
should \fBOR\fR this flag with other flags in the 'options' field in
\fBst.conf\fR. (Refer to \fBTape Configuration\fR.) By default, this flag is
set for the built-in config entries of Archive \fBDAT\fR and Exabyte drives.
.sp
.LP
If this flag is set, the \fBst\fR driver issues a SCSI-2 \fBREAD\fR \fBBLOCK\fR
\fBLIMITS\fR command to the device to determine the maximum record size allowed
by it. If the command fails, \fBst\fR continues to use the maximum record sizes
mentioned in the \fBmtio\fR(7I) man page.
.sp
.LP
If the command succeeds, \fBst\fR restricts the maximum transfer size of a
variable-length device to the minimum of that record size and the maximum
\fBDMA\fR size that the host adapter can handle. Fixed-length devices are bound
by the maximum \fBDMA\fR size allocated by the machine. Note that tapes created
with a large record size may not be readable by earlier releases or on other
platforms.
.sp
.LP
(Refer to the \fBWARNINGS\fR section for more information.)
.SS "EOT Handling"
.LP
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
(\fBLEOT\fR) before \fBPEOT\fR to guarantee flushing the data onto the tape.
The amount of storage between \fBLEOT\fR and \fBPEOT\fR varies from less than 1
Mbyte to about 20 Mbyte, depending on the tape drive.
.sp
.LP
If \fBEOT\fR is encountered while writing an Emulex, no error is reported but
the number of bytes transferred is \fB0\fR and no further writing is allowed.
On all other drives, the first write that encounters \fBEOT\fR will return a
short count or \fB0\fR. If a short count is returned, then the next write will
return \fB0\fR. After a zero count is returned, the next write returns a full
count or short count. A following write returns \fB0\fR 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 \fBEOT\fR is not recommended.
.sp
.LP
Reading past \fBEOT\fR 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 one reads past the two file marks which mark the end of recorded media.
.SH FILES
.ne 2
.na
\fB\fB/kernel/drv/st.conf\fR\fR
.ad
.sp .6
.RS 4n
driver configuration file
.RE

.sp
.ne 2
.na
\fB\fB/usr/include/sys/mtio.h\fR\fR
.ad
.sp .6
.RS 4n
structures and definitions for mag tape io control commands
.RE

.sp
.ne 2
.na
\fB\fB/usr/include/sys/scsi/targets/stdef.h\fR\fR
.ad
.sp .6
.RS 4n
definitions for \fBSCSI\fR tape drives
.RE

.sp
.ne 2
.na
\fB\fB/dev/rmt/[0\(mi 127][l,m,h,u,c][b][n]\fR\fR
.ad
.sp .6
.RS 4n
where \fBl,m,h,u,c\fR specifies the density (low, medium, high,
ultra/compressed), \fBb\fR the optional BSD behavior (see \fBmtio\fR(7I)), and
\fBn\fR the optional no rewind behavior. For example, \fB/dev/rmt/0lbn\fR
specifies unit 0, low density, BSD behavior, and no rewind.
.sp
For 1/2" reel tape devices (HP-88780), the densities are:
.sp

.sp
.TS
l l
l l .
\fBl\fR 800 BPI density
\fBm\fR 1600 BPI density
\fBh\fR 6250 BPI density
\fBc\fR data compression
\fB \fR (not supported on all modules)
.TE

For 8mm tape devices (Exabyte 8200/8500/8505):
.sp

.sp
.TS
l l
l l .
\fBl\fR Standard 2 Gbyte format
\fBm\fR 5 Gbyte format (8500, 8505 only)
\fBh,c\fR       5 Gbyte compressed format (8505 only)
.TE

For 4mm \fBDAT\fR tape devices (Archive Python):
.sp

.sp
.TS
l l
l l .
\fBl\fR Standard format
\fBm,h,c\fR     data compression
.TE

For all QIC (other than QIC-24) tape devices:
.sp

.sp
.TS
l l
l l .
\fBl,m,h,c\fR   density of the tape cartridge type
        (not all devices can read and
        write all formats)
.TE

For QIC-24 tape devices (Emulex MT\(mi02):
.sp

.sp
.TS
l l
l l .
\fBl\fR QIC-11 Format
\fBm,h,c\fR     QIC-24 Format
.TE

.RE

.SH SEE ALSO
.LP
\fBmt\fR(1), \fBmodload\fR(8), \fBmodunload\fR(8), \fBopen\fR(2),
\fBread\fR(2), \fBwrite\fR(2), \fBaioread\fR(3C), \fBaiowrite\fR(3C),
\fBkstat\fR(3KSTAT), \fBdriver.conf\fR(4), \fBscsi\fR(4), \fBstandards\fR(5),
\fBesp\fR(7D), \fBisp\fR(7D), \fBmtio\fR(7I), \fBioctl\fR(9E)
.SH DIAGNOSTICS
.LP
The \fBst\fR driver diagnostics may be printed to the console or messages file.
.sp
.LP
Each diagnostic is dependent on the value of the system variable
\fBst_error_level\fR. \fBst_error_level\fR may be set in the \fB/etc/system\fR
file. The default setting for \fBst_error_level\fR is 4 (SCSI_ERR_RETRYABLE)
which is suitable for most configurations since only actual fault diagnostics
are printed. Settings range from values 0 (SCSI_ERR_ALL) which is most verbose,
to 6 (SCSI_ERR_NONE) which is least verbose. See \fBstdef.h\fR for the full
list of error-levels. SCSI_ERR_ALL level the amount of diagnostic information
is likely to be excessive and unnecessary.
.sp
.LP
The st driver diagnostics are described below:
.sp
.in +2
.nf
Error for Command: <scsi_cmd_name()> Error Level:<error_class>
Requested Block: <blkno>  Error Block: <err_blkno>
Vendor: <name>: Serial Number: <inq_serial>
Sense Key: <es_key> ASC: 0x<es_add_code> (scsi_asc_ascq_name()>), ASCQ:
0x<es_qual_code>, FRU: 0x<ex_fru_code>
.fi
.in -2

.sp
.LP
where <error_class> may be any one of the following: "All," "Unknown,"
"Informational," "Recovered," "Retryable," "Fatal"
.sp
.LP
The command indicated by <scsi_cmd_name> failed. Requested Block represents the
block where the transfer started. Error Block represents the block that caused
the error. Sense Key, ASC, ASCQ and FRU information is returned by the target
in response to a request sense command. See SCSI protocol documentation for
description of Sense Key, ASC, ASCQ, FRU.
.sp
.LP
The st driver attempts to validate entries in the \fBst.conf\fR file. Each
field in the entry is checked for upper and lower limits and invalid bits set.
The fields are named as follows in config string order:
.sp
.in +2
.nf
        conf version
        drive type
        block size
        options
        number of densities
        density code
        default density
        non motion timeout
        I/O timeout
        space timeout
        load timeout
        unload timeout
        erase timeout
.fi
.in -2

.sp
.LP
The \fBst.conf\fR diagnostics are described below:
.sp
.in +2
.nf
<con-name> <field-in-err> <problem-with-field>
.fi
.in -2

.sp
.LP
where <con-name> is the name of the config string. Where <field-in-err> is the
field containing invalid entries and where <problem-with-field> describes the
nature of the invalid entry.
.sp
.in +2
.nf
Write/read: not modulo <n> block size
.fi
.in -2
.sp

.sp
.LP
The request size for fixed record size devices must be a multiple of the
specified block size.
.sp
.in +2
.nf
Recovery by resets failed
.fi
.in -2
.sp

.sp
.LP
After a transport error, the driver attempted to recover by issuing a device
reset and then a bus reset if device reset failed. These recoveries failed.
.sp
.in +2
.nf
Periodic head cleaning required
.fi
.in -2
.sp

.sp
.LP
The driver reported that periodic head cleaning is now required. This
diagnostic is generated either due to a threshold number of retries, or due to
the device communicating to the driver that head cleaning is required.
.sp
.in +2
.nf
Soft error rate (<n>%) during writing/reading was too high
.fi
.in -2
.sp

.sp
.LP
The soft error rate has exceeded the threshold specified by the vendor.
.sp
.in +2
.nf
SCSI transport failed: reason 'xxxx': {retrying|giving up}
.fi
.in -2
.sp

.sp
.LP
The Host Bus Adapter (HBA) has failed to transport a command to the target for
the reason stated. The driver will either retry the command or, ultimately,
give up.
.sp
.in +2
.nf
Tape not inserted in drive
.fi
.in -2
.sp

.sp
.LP
A media access command was attempted while there was no tape inserted into the
specified drive. In this case, the drive returns sense key of DRIVE NOT READY.
.sp
.in +2
.nf
Transport rejected
.fi
.in -2
.sp

.sp
.LP
The Host Bus Adapter (HBA) driver is not accepting commands after failing to
successfully transport a scsi packet to the target. The actual status received
by the \fBst\fR driver from the underlying HBA driver was either
TRAN_FATAL_ERROR or TRAN_BADPKT.
.sp
.in +2
.nf
Retrying command
.fi
.in -2
.sp

.sp
.LP
The \fBst\fR driver failed to complete a command. However the command is
retryable and will be retried.
.sp
.in +2
.nf
Giving up
.fi
.in -2
.sp

.sp
.LP
The \fBst\fR driver has exhausted retries or otherwise is unable to retry the
command and so is giving up.
.sp
.in +2
.nf
No target struct for st%d
.fi
.in -2
.sp

.sp
.LP
The \fBst\fR driver failed to obtain state information because the requested
state structure was not allocated. The specified device was probably not
attached.
.sp
.in +2
.nf
File mark detected
.fi
.in -2
.sp

.sp
.LP
The operation detected an end of file mark. (File marks signify the end of a
file on the tape media).
.sp
.in +2
.nf
End-of-media detected
.fi
.in -2
.sp

.sp
.LP
The operation reached the end of the tape media.
.sp
.in +2
.nf
Exabyte soft error reporting failed. DAT soft error reporting failed
.fi
.in -2
.sp

.sp
.LP
The \fBst\fR driver was unable to determine if the soft error threshold had
been exceeded because it did not successfully read the data it requires or did
not obtain enough data. This data is retrieved using the log sense command.
.sp
.in +2
.nf
Log sense parameter code does not make sense
.fi
.in -2
.sp

.sp
.LP
The log sense command retrieves hardware statistics that are stored on the
drive (for example, soft error counts and retries.) If the data retrieved from
the drive is invalid, this message is printed and the data is not used.
.sp
.in +2
.nf
Restoring tape position at fileno=%x, blkno=%lx....
.fi
.in -2
.sp

.sp
.LP
The \fBst\fR driver is positioning to the specified file and block. This occurs
on an open.
.sp
.in +2
.nf
Failed to restore the last <file/block> position:
In this state, tape will be loaded at BOT during next open
.fi
.in -2
.sp

.sp
.LP
The \fBst\fR driver could not position to the specified location and will
revert to the beginning of the tape when the next open is attempted.
.sp
.in +2
.nf
Device does not support compression
.fi
.in -2
.sp

.sp
.LP
The compression facility of the device was requested. However the device does
not have a hardware compression capability.
.sp
.in +2
.nf
DAT soft error reset failed
.fi
.in -2
.sp

.sp
.LP
After DAT soft error reporting, the counters within the device that accumulate
this sense data need to be re-set. This operation failed.
.sp
.in +2
.nf
Errors after pkt alloc (b_flags=0x%x, b_error=0x%x)
.fi
.in -2
.sp

.sp
.LP
Memory allocation for a \fBscsi\fR packet failed.
.sp
.in +2
.nf
Incorrect length indicator set
.fi
.in -2
.sp

.sp
.LP
The drive reported the length of data requested in a READ operation, was
incorrect. Incorrect Length Indicator (ILI) is a very commonly used facility in
SCSI tape protocol and should not be seen as an error per-se. Applications
typically probe a new tape with a read of any length, using the returned length
to the read system call for future reads. Along with this operation, an
underlying ILI error is received. ILI errors are therefore informational only
and are masked at the default \fBst_error_level\fR.
.sp
.in +2
.nf
Data property (%s) has no value
Data property (%s) incomplete
Version # for data property (%s) greater than 1
.fi
.in -2
.sp

.sp
.LP
These diagnostics indicate problems in retrieving the values of the various
property settings. The \fBst\fR driver is in the process of setting the
property/parameter values for the tape drive using information from either the
built-in table within the driver or from uncommented entries in the
\fBst.conf\fR file. The effect on the system may be that the tape drive may be
set with default or generic driver settings which may not be appropriate for
the actual type of tape drive being used.
.sp
.in +2
.nf
st_attach-RESUME: tape failure tape position will be lost
.fi
.in -2
.sp

.sp
.LP
On a resume after a power management suspend, the previously known tape
position is no longer valid. This can occur if the tape was changed while the
system was in power management suspend. The operation will not be retried.
.sp
.in +2
.nf
Write Data Buffering has been deprecated. Your applications should
continue to work normally. However, they should be ported to use
Asynchronous I/O.
.fi
.in -2
.sp

.sp
.LP
Indicates that buffering has been removed from Solaris.
.sp
.in +2
.nf
Cannot detach: fileno=%x, blkno=%lx
.fi
.in -2
.sp

.sp
.LP
The \fBst\fR driver cannot unload because the tape is not positioned at BOT
(beginning of tape). May indicate hardware problems with the tape drive.
.sp
.in +2
.nf
Variable record length I/O
Fixed record length (%d byte blocks) I/O
.fi
.in -2
.sp

.sp
.LP
Tape-drives can use either Fixed or Variable record length. If the drive uses
Fixed length records, then the built in property table or the st.conf file will
contain a non-zero record-length property. Most DAT, Exabyte and DLT drives
support Variable record lengths. Many QIC format tape drives have historically
been of Fixed record length.
.sp
.in +2
.nf
Command will be retried
 un_ncmds: %d can't retry cmd
.fi
.in -2
.sp

.sp
.LP
These diagnostics are only seen with tape drives with the
ST_RETRY_ON_RECOVERED_DEFERRED_ERROR bit set. See \fBstdef.h\fR for explanation
of the specific usage of this setting.
.SH WARNINGS
.LP
Effective with Solaris 2.4, the \fBST_NO_RECSIZE_LIMIT\fR flag is set for the
built-in config entries of the Archive \fBDAT\fR and Exabyte drivers by
default. (Refer to \fBLarge Record Sizes\fR.) Tapes written with large block
sizes prior to Solaris 2.4 may cause some applications to fail if the number of
bytes returned by a read request is less than the requested block size (for
example, asking for 128 Kbytes and receiving less than 64 Kbytes).
.sp
.LP
The \fBST_NO_RECSIZE_LIMIT\fR flag can be disabled in the config entry for the
device as a work-around. (Refer to \fBTape Configuration\fR.) This action
disables the ability to read and write with large block sizes and allows the
reading of tapes written prior to Solaris 2.4 with large block sizes.
.sp
.LP
(Refer to \fBmtio\fR(7I) for a description of maximum record sizes.)
.SH BUGS
.LP
Tape devices that do not return a \fBBUSY\fR 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 tape devices supplied by Sun Microsystems.
.sp
.LP
Tape devices that do not report a blank check error at the end of recorded
media may cause file positioning operations to fail. Some tape drives, for
example, mistakenly report media error instead of blank check error.