'\" 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 "22 Oct 2008" "SunOS 5.11" "Devices" .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 .sp .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 .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 .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" .sp .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" .sp .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" .sp .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" .sp .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 = [, *]; .fi .in -2 .sp .sp .LP where .sp .in +2 .nf := , , .fi .in -2 .sp .sp .LP and .sp .in +2 .nf = , , , , , [, *], ; .fi .in -2 .sp .sp .LP or .sp .in +2 .nf = , , , , , [, *], , , , , , , , ; .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\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\042\fR and \fB\047\fR). Trailing spaces may be truncated. .sp .LP \fB\fR is used to report the device on the console. This string may have zero length, in which case the \fB\fR will be used to report the device. .sp .LP \fB\fR is the name of the property which contains all the tape configuration values (such as \fB\fR, \fB\fR, etc.) corresponding for the tape drive for the specified \fB\fR\&. .sp .LP \fB\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\fR value list. .sp .LP \fB\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 tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) . \fBMT_ISQIC\fR0x32 \fBMT_ISREEL\fR0x33 \fBMT_ISDAT\fR0x34 \fBMT_IS8MM\fR0x35 \fBMT_ISOTHER\fR0x36 \fBMT_ISTAND25G\fR0x37 \fBMT_ISDLT\fR0x38 \fBMT_ISSTK9840\fR0x39 \fBMT_ISBMDLT1\fR0x3A \fBMT_LTO\fR0x3B .TE .sp .LP \fB\fR is the preferred block size of the tape device. The value should be \fB0\fR for variable block size devices. .sp .LP \fB\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 tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) . \fBST_VARIABLE\fR0x0001 \fBST_QIC\fR0x0002 \fBST_REEL\fR0x0004 \fBST_BSF\fR0x0008 \fBST_BSR\fR0x0010 \fBST_LONG_ERASE\fR0x0020 \fBST_AUTODEN_OVERRIDE\fR0x0040 \fBST_NOBUF\fR0x0080 \fBST_KNOWS_EOD\fR0x0200 \fBST_UNLOADABLE\fR0x0400 \fBST_SOFT_ERROR_REPORTING\fR0x0800 \fBST_LONG_TIMEOUTS\fR0x1000 \fBST_NO_RECSIZE_LIMIT\fR0x8000 \fBST_MODE_SEL_COMP\fR0x10000 \fBST_NO_RESERVE_RELEASE\fR0x20000 \fBST_READ_IGNORE_ILI\fR0x40000 \fBST_READ_IGNORE_EOFS\fR0x80000 \fBST_SHORT_FILEMARKS\fR0x100000 \fBST_EJECT_TAPE_ON_CHANGER_FAILURE\fR0x200000 \fBST_RETRY_ON_RECOVERED_DEFERRED_ERROR\fR0x400000 \fBST_WORMABLE\fR0x1000000 .TE .sp .ne 2 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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(1M) and \fBmodunload\fR(1M)). That is, the driver will return the correct inquiry string. .RE .sp .ne 2 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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 (supress 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 .mk .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 .mk .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 .mk .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 .mk .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 .mk .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\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\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\fR has a value between \fB0\fR and ( - \fB1\fR). .sp .LP \fB\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\fR Time in seconds to perform data transfer I/O to or from tape including worst case error recovery. .sp .LP \fB\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\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\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\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\fR Time in seconds to preform a full (BOT to EOT) erase of longest medium with worst case error recovery. .SS "Device Statistics Support" .sp .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 .sp .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 .sp .ne 2 .mk .na \fB\fBEACCES\fR\fR .ad .RS 10n .rt 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 .mk .na \fB\fBEBUSY\fR\fR .ad .RS 10n .rt 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 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 10n .rt 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 .mk .na \fB\fBEIO\fR\fR .ad .RS 10n .rt 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 .mk .na \fB\fBENOTTY\fR\fR .ad .RS 10n .rt This indicates that the tape device does not support the requested ioctl function. .RE .sp .ne 2 .mk .na \fB\fBENXIO\fR\fR .ad .RS 10n .rt During opening, the tape device does not exist. .RE .sp .ne 2 .mk .na \fB\fBENOMEM\fR\fR .ad .RS 10n .rt 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" .sp .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" .sp .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 .sp .ne 2 .mk .na \fB\fB/kernel/drv/st.conf\fR\fR .ad .sp .6 .RS 4n driver configuration file .RE .sp .ne 2 .mk .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 .mk .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 .mk .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 tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) . \fBl\fR800 BPI density \fBm\fR1600 BPI density \fBh\fR6250 BPI density \fBc\fRdata compression \fB \fR(not supported on all modules) .TE For 8mm tape devices (Exabyte 8200/8500/8505): .sp .sp .TS tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) . \fBl\fRStandard 2 Gbyte format \fBm\fR5 Gbyte format (8500, 8505 only) \fBh,c\fR5 Gbyte compressed format (8505 only) .TE For 4mm \fBDAT\fR tape devices (Archive Python): .sp .sp .TS tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) . \fBl\fRStandard format \fBm,h,c\fRdata compression .TE For all QIC (other than QIC-24) tape devices: .sp .sp .TS tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) . \fBl,m,h,c\fRdensity 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 tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) . \fBl\fRQIC-11 Format \fBm,h,c\fRQIC-24 Format .TE .RE .SH SEE ALSO .sp .LP \fBmt\fR(1), \fBmodload\fR(1M), \fBmodunload\fR(1M), \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 .sp .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: Error Level: Requested Block: Error Block: Vendor: : Serial Number: Sense Key: ASC: 0x (scsi_asc_ascq_name()>), ASCQ: 0x, FRU: 0x .fi .in -2 .sp .LP where may be any one of the following: "All," "Unknown," "Informational," "Recovered," "Retryable," "Fatal" .sp .LP The command indicated by 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 .fi .in -2 .sp .LP where is the name of the config string. Where is the field containing invalid entries and where describes the nature of the invalid entry. .sp .in +2 .nf Write/read: not modulo 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 (%) 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 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 .sp .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 .sp .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.