SunOS man pages : st (7)
Devices st(7D)
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 tape devices include 1/4" Tandberg 2.5
Gigabyte QIC tape drive, 1/4" Archive Viper QIC-150 stream-
ing tape drive, 1/4" Emulex MT-02 tape controller, HP-88780
1/2" tape drive, Exabyte EXB-8200/8500/8505/8505XL 8mm car-
tridge tape, and the Archive Python 4 mm DAT tape subsys-
tem. st provides a standard interface to these various dev-
ices; see mtio(7I) for details.
The driver can be opened with either rewind on close or no
rewind on close options. It can also be opened with the
O_NDELAY (see open(2)) option when there is no tape inserted
in the drive. A maximum of four tape formats per device are
supported (see FILES below). The tape format is specified
using the device name. Often tape format is also referred to
as tape density.
The driver now reserves the tape drive upon open and
releases it at close for use in multi-initiator environ-
ments. Refer to the MTIOCRESERVE and MTIOCRELEASE ioctls in
mtio(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.
If the tape drive is opened in O_NDELAY mode, no reservation
will occur during the open, as per the POSIX standard (see
standards(5)). However, before the first tape operation or
I/O occurs, a reservation will occur to provide
reserve/release functionality.
Persistent Errors and Asynchronous Tape Operation
The st driver now supports persistent errors (see mtio(7I))
and asynchronous tape operations (see mtio(7I),
aioread(3AIO), and aiowrite(3AIO)).
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 that if the low density format is used, no indication
is given that the driver has overridden the user-selected
SunOS 5.8 Last change: 12 August 1999 1
Devices st(7D)
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 tape drive, 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.
Tape Configuration
The st tape driver has a built-in configuration table for
all Sun supported tape drives. In order to support the addi-
tion of third party tape devices or to override a built-in
configuration, device information can be supplied in st.conf
as global properties that apply to each node, or as proper-
ties 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>;
A semicolon (;) is used to terminate a prototype devinfo
node specification. Individual elements listed within the
specification should not be separated by a semicolon. (Refer
to driver.conf(4) for more information.)
<vid+pid> is the string that is returned by the tape device
on a SCSI inquiry command. This string may contain any char-
acter in the range 0x20-0x7e. Characters such as " " " (dou-
ble quote) or " ' " (single quote), which are not permitted
in property value strings, are represented by their octal
equivalent (for example, \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.
SunOS 5.8 Last change: 12 August 1999 2
Devices st(7D)
<data-property-name> is the name of the property which con-
tains all the tape configuration values (such as <type>,
<bsize>, etc.) corresponding for the tape drive for the
specified <vid+pid>.
<version> is a 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:
MT_ISQIC 0x32
MT_ISREEL 0x33
MT_ISDAT 0x34
MT_IS8MM 0x35
MT_ISOTHER 0x36
<bsize> is the preferred block size of the tape device. The
value should be 0 for variable block size devices.
<options> is a bit pattern representing the devices, as
defined in /usr/include/sys/scsi/targets/stdef.h. Valid
flags for tape configuration are:
ST_VARIABLE 0x0001
ST_QIC 0x0002
ST_REEL 0x0004
ST_BSF 0x0008
ST_BSR 0x0010
ST_LONG_ERASE 0x0020
ST_AUTODEN_OVERRIDE 0x0040
ST_NOBUF 0x0080
ST_KNOWS_EOD 0x0200
ST_UNLOADABLE 0x0400
ST_SOFT_ERROR_REPORTING 0x0800
ST_LONG_TIMEOUTS 0x1000
ST_BUFFERED_WRITES 0x4000
ST_NO_RECSIZE_LIMIT 0x8000
ST_MODE_SEL_COMP 0x10000
ST_NO_RESERVE_RELEASE 0x20000
ST_READ_IGNORE_ILI 0x40000
ST_READ_IGNORE_EOFS 0x80000
ST_SHORT_FILEMARKS 0x100000
ST_EJECT_TAPE_ON_CHANGER_FAILURE 0x200000
ST_RETRY_ON_RECOVERED_DEFERRED_ERROR 0x400000
ST_VARIABLE
SunOS 5.8 Last change: 12 August 1999 3
Devices st(7D)
The flag indicates the tape device supports variable
length record sizes.
ST_QIC
The flag indicates a Quarter Inch Cartridge (QIC)
tape device.
ST_REEL
The flag indicates a 1/2-inch reel tape device.
ST_BSF
If flag is set, the device supports backspace over
EOF marks (bsf - see mt(1)).
ST_BSR
If flag is set, the tape device supports the backspace
record operation (bsr - see mt(1)). If the device
does not support bsr, the st 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 mt(1)) to forward the tape to the
correct record.
ST_LONG_ERASE
The flag indicates the tape device needs a longer time
than normal to erase.
ST_AUTODEN_OVERRIDE
The auto-density override flag. The device is capable
of determining the tape density automatically without
issuing a "mode-select"/"mode-sense command".
ST_NOBUF
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.
ST_KNOWS_EOD
If flag is set, the device can determine when EOD
(End of Data) has been reached. When this flag is set,
the st driver uses fast file skipping. Otherwise,
file skipping happens one file at a time.
ST_UNLOADABLE
The flag indicates the device will not complain if
the st driver is unloaded and loaded again (see
modload(1M) and modunload(1M)). That is, the driver
will return the correct inquiry string.
SunOS 5.8 Last change: 12 August 1999 4
Devices st(7D)
ST_SOFT_ERROR_REPORTING
The flag indicates the tape device will perform a
"request sense" or "log sense" command when the device
is closed. Currently, only Exabyte and DAT drives
support this feature.
ST_LONG_TIMEOUTS
The flag indicates the tape device requires timeouts
that are 5 times longer than usual for normal opera-
tion.
ST_BUFFERED_WRITES
If the flag is set, when data is written to the tape
device, the data is buffered by the driver. The
application may receive acknowledgement of completion
of the write request before the data has been written
to tape.
ST_NO_RECSIZE_LIMIT (SPARC Only)
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 Large Record Sizes and WARNINGS.)
ST_MODE_SEL_COMP
If the ST_MODE_SEL_COMP flag is set, the driver deter-
mines which of the two mode pages the device supports
for selecting or deselecting compression. It first
tries the Data Compression mode page (0x0F); if this
fails, it tries the Device Configuration mode page
(0x10). Some devices, however, may need a specific
density code for selecting or deselecting compres-
sion. Please refer to the device specific SCSI
manual. When the flag is set, compression will be
enabled only if the "c" or "u" device is used. For
any other device densities, compression will be dis-
abled.
ST_NO_RESERVE_RELEASE
The ST_NO_RESERVE_RELEASE flag disables the use of
reserve on open and release on close. If an attempt to
use a ioctl of MTRESERVE or MTRELEASE on a drive with
this flag set, it will return an error of ENOTTY
(inappropriate ioctl for device).
ST_READ_IGNORE_ILI
The ST_READ_IGNORE_ILI flag is applicable only to
variable block devices which support the SILI bit
option. The ST_READ_IGNORE_ILI flag indicates that
SILI (supress incorrect length indicator) bit will be
SunOS 5.8 Last change: 12 August 1999 5
Devices st(7D)
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 remain-
ing 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
ENOMEM.
ST_READ_IGNORE_EOFS
The ST_READ_IGNORE_EOFS 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 indi-
cated 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.
ST_SHORT_FILEMARKS
The ST_SHORT_FILEMARKS flag is applicable only to EXA-
BYTE 8mm tape drives which supports short filemarks.
When this flag is set, short filemarks will be used
for writing filemarks. Short filemarks could lead to
tape incompatible with some otherwise compatible dev-
ice. By default long filemarks will be used for writ-
ing filemarks.
ST_EJECT_TAPE_ON_CHANGER_FAILURE
If ST_EJECT_TAPE_ON_CHANGER_FAILURE flag is set, the
tape will be ejected automatically if the tape car-
tridge is trapped in the medium due to positioning
problems of the medium changer.
The following ASC/ASCQ keys are defined to the reasons
for causing tape ejection if
ST_EJECT_TAPE_ON_CHANGER_FAILURE option is set to
0x200000:
SunOS 5.8 Last change: 12 August 1999 6
Devices st(7D)
Sense ASC/ASCQ Description
Key
4 15/01 Mechanical Failure
4 44/00 Internal Target Failure
2 53/00 Media Load or Eject Failed
4 53/00 Media Load or Eject Failed
4 53/01 Unload Tape Failure
ST_RETRY_ON_RECOVERED_DEFERRED_ERROR
If ST_RETRY_ON_RECOVERED_DEFERRED_ERROR flag is set,
the st 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.
<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 device specification manual or be
obtained from the device vendor.
<default-density> has a value between 0 and (<number of den-
sities> - 1).
Device Statistics Support
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 cumula-
tive residence-length product for each queue.
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.
IOCTLS
The behavior of SCSI tape positioning ioctls is the same
across all devices which support them. (Refer to mtio(7I).)
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 dev-
ices. It is used to restore tape tension, thus improving the
tape's soft error rate after extensive start-stop operations
or long-term storage.
SunOS 5.8 Last change: 12 August 1999 7
Devices st(7D)
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 MTIOCTOP ioctl, MTSRSZ
and MTGRSZ, 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 READ
BLOCK LIMITS 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 MTSRSZ 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 st.conf).
Note that the error status is reset by the MTIOCGET get
status ioctl call or by the next read, write, or other ioctl
operation. If no error has occurred (sense key is 0), the
current file and record position is returned.
ERRORS
EACCES
The driver is opened for write access and the tape is
write-protected or the tape unit is reserved by
another host.
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.
ENOMEM
This indicates that the record size on the tape drive
is more than the requested size during read operation.
SunOS 5.8 Last change: 12 August 1999 8
Devices st(7D)
EXAMPLES
Example 1: Global tape-config list property
The following is an example of a global tape-config-list
property:
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=6 lun=0;
Example 2: Tape-config-list property applicable to target 2
only
The following is an example of a tape-config-list property
applicable to target 2 only:
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;
Large Record Sizes
To support applications such as seismic programs that
require large record sizes, the flag ST_NO_RECSIZE_LIMIT
must be set in drive option in the configuration entry. A
SCSI tape drive that needs to transfer large records should
OR this flag with other flags in the 'options' field in
SunOS 5.8 Last change: 12 August 1999 9
Devices st(7D)
st.conf. (Refer to Tape Configuration.) By default, this
flag is set for the built-in config entries of Archive DAT
and Exabyte drives.
If this flag is set, the st driver issues a SCSI-2 READ
BLOCK LIMITS command to the device to determine the maximum
record size allowed by it. If the command fails, st contin-
ues to use the maximum record sizes mentioned in the
mtio(7I) man page.
If the command succeeds, st restricts the maximum transfer
size of a variable-length device to the minimum of that
record size and the maximum DMA size that the host adapter
can handle. Fixed-length devices are bound by the maximum
DMA 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.
(Refer to the WARNINGS section for more information.)
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 1 Mbyte to
about 20 Mbyte, depending on the tape drive.
If EOT is encountered while writing an Emulex, no error is
reported but the number of bytes transferred is 0 and no
further writing is allowed. On all other drives, the first
write that encounters EOT will return a short count or 0. If
a short count is returned, then the next write will return
0. After a zero count is returned, the next write returns a
full count or short count. A following write returns 0
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 one reads past
the two file marks which mark the end of recorded media.
Write Data Buffering
Tape drives with data compression require a much higher
data rate in order to stream the tape. Write data buffer-
ing in the driver improves streaming to the drive without
changing the application and augments the buffering in the
tape drive itself. If write data buffering is enabled, data
is buffered in the driver and the request is immediately
acknowledged by the driver before it has been written to the
SunOS 5.8 Last change: 12 August 1999 10
Devices st(7D)
tape drive. This enables the driver to submit the next
request as soon as the previous request completes and the
application to prepare the next request while the current
request is in progress.
A SCSI tape drive that allows buffering requires ORing the
flag ST_BUFFERED_WRITES with other flags in the 'options'
field in st.conf. (Refer to Tape Configuration.) By default,
this option is set for the built-in config entries of the
Archive DAT and Exabyte drives.
In order for write buffering to work properly, sufficient
space after LEOT must be available to empty the write
buffers. Older tape devices usually do not have sufficient
space after LEOT.
To turn on tape buffering, a property in st.conf called
"tape-driver-buffering" should be added. The value assigned
to this property is the maximum number of buffered write
requests allowed. For example, 0 indicates no write request
buffering allowed, while 2 indicates buffer up to 2 write
requests. If this property is not specified in st.conf, the
driver defaults to a value of 0. The maximum size of write
request that can be buffered is specified through a property
in st.conf called "tape-driver-buf-max-size". If this pro-
perty is not specified in st.conf, the driver defaults the
buffer size to a value of 1 Mbyte.
An example of st.conf, where the maximum number of write
requests buffered is 4 and maximum size of write request
buffered is 2 Mbyte, is given below. This applies to all
nodes in this conf file.
tape-driver-buffering = 4; tape-driver-buf-max-size = 0x200000;
name="st" class="scsi"
target=0 lun=0;
name="st" class="scsi"
target=1 lun=0;
name="st" class="scsi"
target=2 lun=0;
....
In the case of a SCSI bus reset, a medium error, or any
other fatal transport error on a buffered request, the
driver returns an error on subsequent write requests and
allows no more writes. If no further write requests occur,
an error is returned on close.
SunOS 5.8 Last change: 12 August 1999 11
Devices st(7D)
Since some applications may perceive write buffering as a
potential data integrity problem, this feature is disabled
by default and needs to be explicitly enabled in the config
entry and turned on by means of the property in st.conf.
Furthermore, some fault tolerant backup servers make assump-
tions about the data buffering in the tape drive itself.
These assumptions may not be valid if write buffering has
been enabled.
Write buffering may be superseded by other performance
enhancements in a future release.
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(7I)), 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:
l 800 BPI density
m 1600 BPI density
h 6250 BPI density
c data compression
(not supported on all modules)
For 8mm tape devices (Exabyte 8200/8500/8505):
l Standard 2 Gbyte format
m 5 Gbyte format (8500, 8505 only)
h,c 5 Gbyte compressed format (8505
only)
For 4mm DAT tape devices (Archive Python):
l Standard format
m,h,c data compression
SunOS 5.8 Last change: 12 August 1999 12
Devices st(7D)
For all QIC (other than QIC-24) tape devices:
l,m,h,c density of the tape cartridge type
(not all devices can read and
write all formats)
For QIC-24 tape devices (Emulex MT-02):
l QIC-11 Format
m,h,c QIC-24 Format
SEE ALSO
mt(1), modload(1M), modunload(1M), open(2), read(2),
write(2), aioread(3AIO), aiowrite(3AIO), kstat(3KSTAT),
driver.conf(4), scsi(4), standards(5), esp(7D), isp(7D),
mtio(7I), 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, ASCQ and FRU 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 speci-
fied by the vendor.
SCSI transport failed: reason 'xxxx': {retrying|giving up}
The host adapter has failed to transport a command to
SunOS 5.8 Last change: 12 August 1999 13
Devices st(7D)
the target for the reason stated. The driver will
either retry the command or, ultimately, give up.
WARNINGS
In Solaris 2.4, the ST_NO_RECSIZE_LIMIT flag is set for the
built-in config entries of the Archive DAT and Exabyte
drivers by default. (Refer to Large Record Sizes.) 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).
The ST_NO_RECSIZE_LIMIT flag can be disabled in the config
entry for the device as a work-around. (Refer to Tape Confi-
guration.) 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.
(Refer to mtio(7I) for a description of maximum record
sizes.)
BUGS
Tape devices that do not return a BUSY status during tape
loading prevent user commands from being held until the dev-
ice is ready. The user must delay issuing any tape opera-
tions until the tape device is ready. This is not a problem
for tape devices supplied by Sun Microsystems.
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.
SunOS 5.8 Last change: 12 August 1999 14
|
 |
|
|
