436 lines
15 KiB
Groff
436 lines
15 KiB
Groff
.\" $NetBSD: st.4,v 1.15 1999/03/16 01:19:18 garbled Exp $
|
|
.\"
|
|
.\" Copyright (c) 1996
|
|
.\" Julian Elischer <julian@freebsd.org>. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd August 23, 1996
|
|
.Dt ST 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm st
|
|
.Nd SCSI tape driver
|
|
.Sh SYNOPSIS
|
|
.Cd st* at scsibus? target ? lun ?
|
|
.Cd st1 at scsibus0 target 4 lun 0
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver provides support for
|
|
.Tn SCSI
|
|
tape drives.
|
|
It allows a tape drive to be run in several different
|
|
modes depending on minor numbers and supports several different
|
|
.Sq sub-modes .
|
|
The device can have both a
|
|
.Em raw
|
|
interface and a
|
|
.Em block
|
|
interface; however, only the raw interface is usually used (or recommended).
|
|
.Pp
|
|
.Tn SCSI
|
|
devices have a relatively high level interface and talk to the system via a
|
|
.Tn SCSI
|
|
adapter and a
|
|
.Tn SCSI
|
|
adapter driver
|
|
(e.g.
|
|
.Xr ahc 4 ) .
|
|
A
|
|
.Tn SCSI
|
|
adapter must also be separately configured into the system before a
|
|
.Tn SCSI
|
|
tape can be configured.
|
|
.Pp
|
|
As the
|
|
.Tn SCSI
|
|
adapter is probed during boot, the
|
|
.Tn SCSI
|
|
bus is scanned for devices.
|
|
Any devices found which answer as
|
|
.Sq Em Sequential
|
|
type devices will be attached to the
|
|
.Nm
|
|
driver.
|
|
.Sh MOUNT SESSIONS
|
|
The
|
|
.Nm
|
|
driver is based around the concept of a
|
|
.Dq Em mount session ,
|
|
which is defined as the period between the time that a tape is
|
|
mounted, and the time when it is unmounted.
|
|
Any parameters set during a mount session remain in effect for the
|
|
remainder of the session or until replaced.
|
|
The tape can be unmounted, bringing the session to a close in
|
|
several ways.
|
|
These include:
|
|
.Bl -enum
|
|
.It
|
|
Closing an
|
|
.Sq unmount device ,
|
|
referred to as sub-mode 00 below.
|
|
An example is
|
|
.Pa /dev/rst0 .
|
|
.It
|
|
Using the
|
|
.Dv MTOFFL
|
|
.Xr ioctl 2
|
|
command, reachable through the
|
|
.Sq Cm offline
|
|
command of
|
|
.Xr mt 1 .
|
|
.It
|
|
Opening a different mode will implicitly unmount the tape, thereby
|
|
closing off the mode that was previously mounted.
|
|
All parameters will be loaded freshly from the new mode
|
|
(See below for more on modes).
|
|
.El
|
|
.Sh MODES AND SUB-MODES
|
|
There are several different
|
|
.Sq operation
|
|
modes.
|
|
These are controlled by bits 2 and 3 of the minor number
|
|
and are designed to allow users to easily read and write different
|
|
formats of tape on devices that allow multiple formats.
|
|
The parameters for each mode can be set individually by hand with the
|
|
.Xr mt 1
|
|
command.
|
|
When a device corresponding to a particular mode is first
|
|
mounted, The operating parameters for that mount session are copied
|
|
from that mode.
|
|
Further changes to the parameters during the session will change
|
|
those in effect for the session but not those set in the operation mode.
|
|
To change the parameters for an operation mode, one must compile
|
|
them into the
|
|
.Dq Em quirk
|
|
table in the driver's source code.
|
|
.Pp
|
|
In addition to the operating modes mentioned above, bits 0 and 1
|
|
of the minor number are interpreted as
|
|
.Sq sub-modes .
|
|
The sub-modes differ in the action taken when the device is closed:
|
|
.Bl -tag -width XXXX
|
|
.It 00
|
|
A close will rewind the device; if the tape has been written, then
|
|
a file mark will be written before the rewind is requested.
|
|
The device is unmounted.
|
|
.It 01
|
|
A close will leave the tape mounted.
|
|
If the tape was written to, a file mark will be written.
|
|
No other head positioning takes place.
|
|
Any further reads or writes will occur directly after the last
|
|
read, or the written file mark.
|
|
.It 10
|
|
A close will rewind the device.
|
|
If the tape has been written, then a file mark will be written
|
|
before the rewind is requested.
|
|
On completion of the rewind an unload command will be issued.
|
|
The device is unmounted.
|
|
.It 11
|
|
This is Control mode, which allows the tape driver to be opened without a tape
|
|
inserted to allow various ioctls (e.g. MTIOCGET or MTIOCTOP to set density
|
|
or blocksize) and raw SCSI command on
|
|
through. I/O can be done in this mode, if desired, with the same
|
|
rewind/eject behaviour as mode 01. This isn't really an 'action taken
|
|
on close' type of distinction, but this seems to be the place to put
|
|
this mode.
|
|
.El
|
|
.Sh BLOCKING MODES
|
|
.Tn SCSI
|
|
tapes may run in either
|
|
.Sq Em variable
|
|
or
|
|
.Sq Em fixed
|
|
block-size modes.
|
|
Most
|
|
.Tn QIC Ns -type
|
|
devices run in fixed block-size mode, where most nine-track tapes
|
|
and many new cartridge formats allow variable block-size.
|
|
The difference between the two is as follows:
|
|
.Bl -inset
|
|
.It Variable block-size:
|
|
Each write made to the device results in a single logical record
|
|
written to the tape.
|
|
One can never read or write
|
|
.Em part
|
|
of a record from tape (though you may request a larger block and
|
|
read a smaller record); nor can one read multiple blocks.
|
|
Data from a single write is therefore read by a single read.
|
|
The block size used may be any value supported by the device, the
|
|
.Tn SCSI
|
|
adapter and the system (usually between 1 byte and 64 Kbytes,
|
|
sometimes more).
|
|
.Pp
|
|
When reading a variable record/block from the tape, the head is
|
|
logically considered to be immediately after the last item read,
|
|
and before the next item after that.
|
|
If the next item is a file mark, but it was never read, then the
|
|
next process to read will immediately hit the file mark and receive
|
|
an end-of-file notification.
|
|
.It Fixed block-size
|
|
Data written by the user is passed to the tape as a succession of
|
|
fixed size blocks.
|
|
It may be contiguous in memory, but it is considered to be a series
|
|
of independent blocks.
|
|
One may never write an amount of data that is not an exact multiple
|
|
of the blocksize.
|
|
One may read and write the same data as a different set of records,
|
|
In other words, blocks that were written together may be read
|
|
separately, and vice-versa.
|
|
.Pp
|
|
If one requests more blocks than remain in the file, the drive will
|
|
encounter the file mark.
|
|
Because there is some data to return (unless there were no records
|
|
before the file mark), the read will succeed, returning that data.
|
|
The next read will return immediately with an EOF (as above, if
|
|
the file mark is never read, it remains for the next process to
|
|
read if in no-rewind mode).
|
|
.El
|
|
.Sh FILE MARK HANDLING
|
|
The handling of file marks on write is automatic.
|
|
If the user has written to the tape, and has not done a read since
|
|
the last write, then a file mark will be written to the tape when
|
|
the device is closed.
|
|
If a rewind is requested after a write, then the driver assumes
|
|
that the last file on the tape has been written, and ensures that
|
|
there are two file marks written to the tape.
|
|
The exception to this is that there seems to be a standard (which
|
|
we follow, but don't understand why) that certain types of tape do
|
|
not actually write two file marks to tape, but when read, report a
|
|
.Sq phantom
|
|
file mark when the last file is read.
|
|
These devices include the QIC family of devices
|
|
(it might be that this set of devices is
|
|
the same set as that of fixed block devices.
|
|
This has not been determined yet, and they are treated as separate
|
|
behaviors by the driver at this time).
|
|
.Sh EOM HANDLING
|
|
Attempts to write past EOM and how EOM is reported are handled slightly
|
|
differently based upon whether EARLY WARNING recognition is enabled in
|
|
the driver.
|
|
.Pp
|
|
If EARLY WARNING recognitions is \fBnot\fR enabled, then detection
|
|
of EOM (as reported in SCSI Sense Data with an EOM indicator)
|
|
causes the write operation to be flagged with I/O error (EIO).
|
|
This has the effect for the user application of not knowing actually
|
|
how many bytes were read (since the return of the
|
|
.Xr read 2
|
|
system call is set to \(mi1).
|
|
.Pp
|
|
If EARLY WARNING recognition \fBis\fR enabled, then detection of EOM
|
|
(as reported in SCSI Sense Data with an EOM indicator)
|
|
has no immediate effect except that
|
|
the driver notes that EOM has been detected. If the write completing
|
|
didn't transfer all data that was requested, then the residual count
|
|
(counting bytes \fBnot\fR written)
|
|
is returned to the user application. In any event, the next attempt
|
|
to write (if that is the next action the user application takes)
|
|
is immediately completed with no data transferred, and a residual
|
|
returned to the user application indicating that no data was transferred.
|
|
This is the traditional UNIX EOF indication. The state that EOM had
|
|
been seen is then cleared.
|
|
.Pp
|
|
In either mode of operation, the driver does not prohibit the
|
|
user application from writing more data, if it chooses to do so. This
|
|
will continue up until the physical end of media, which is usually
|
|
signalled internally to the driver as a CHECK CONDITION with
|
|
the Sense Key set to VOLUME OVERFLOW. When this or any otherwise
|
|
unhandled error occurs, an error return of EIO will be transmitted
|
|
to the user application. This does indeed mean that if EARLY WARNING
|
|
is enables and the device continues to set EOM indicators prior to
|
|
hitting physical end of media, that an indeterminate number of 'short write
|
|
returns' as described in the previous paragraph will occur. However, the
|
|
expected user application behaviour (in common with other systems) is
|
|
to close the tape and rewind and request another tape upon the receipt
|
|
of the first EOM indicator, possibly after writing one trailer record.
|
|
.Sh KERNEL CONFIGURATION
|
|
Because different tape drives behave differently, there is a
|
|
mechanism within the source to
|
|
.Nm
|
|
to quickly and conveniently recognize and deal with brands and
|
|
models of drive that have special requirements.
|
|
.Pp
|
|
There is a table (called the
|
|
.Dq Em quirk table )
|
|
in which the identification strings of known errant drives can be stored.
|
|
Alongside each is a set of flags that allows the setting
|
|
of densities and blocksizes for each of the modes, along with a
|
|
set of `QUIRK' flags that can be used to enable or disable sections
|
|
of code within the driver if a particular drive is recognized.
|
|
.Sh IOCTLS
|
|
The following
|
|
.Xr ioctl 2
|
|
calls apply to
|
|
.Tn SCSI
|
|
tapes.
|
|
Some also apply to other tapes.
|
|
They are defined in the header file
|
|
.Aq Pa sys/mtio.h .
|
|
.\"
|
|
.\" Almost all of this discussion belongs in a separate mt(4)
|
|
.\" manual page, since it is common to all magnetic tapes.
|
|
.\"
|
|
.Pp
|
|
.Bl -tag -width MTIOCEEOT
|
|
.It Dv MTIOCGET
|
|
.Pq Li "struct mtget"
|
|
Retrieve the status and parameters of the tape. Error status
|
|
and residual is unlatched and cleared by the driver when it receives
|
|
this ioctl.
|
|
.It Dv MTIOCTOP
|
|
.Pq Li "struct mtop"
|
|
Perform a multiplexed operation.
|
|
The argument structure is as follows:
|
|
.Bd -literal -offset indent
|
|
struct mtop {
|
|
short mt_op;
|
|
daddr_t mt_count;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The following operation values are defined for
|
|
.Va mt_op :
|
|
.Bl -tag -width MTSELDNSTY
|
|
.It Dv MTWEOF
|
|
Write
|
|
.Va mt_count
|
|
end of file marks at the present head position.
|
|
.It Dv MTFSF
|
|
Skip over
|
|
.Va mt_count
|
|
file marks.
|
|
Leave the head on the EOM side of the last skipped file mark.
|
|
.It Dv MTBSF
|
|
Skip
|
|
.Em backwards
|
|
over
|
|
.Va mt_count
|
|
file marks.
|
|
Leave the head on the BOM (beginning of media)
|
|
side of the last skipped file mark.
|
|
.It Dv MTFSR
|
|
Skip forwards over
|
|
.Va mt_count
|
|
records.
|
|
.It Dv MTBSR
|
|
Skip backwards over
|
|
.Va mt_count
|
|
records.
|
|
.It Dv MTREW
|
|
Rewind the device to the beginning of the media.
|
|
.It Dv MTOFFL
|
|
Rewind the media (and, if possible, eject).
|
|
Even if the device cannot eject the media it will often no longer
|
|
respond to normal requests.
|
|
.It Dv MTNOP
|
|
No-op; set status only.
|
|
.It Dv MTERASE
|
|
Erase the media from current position. If the field
|
|
.Va mt_count
|
|
is nonzero, a full erase is done (from current position to end of
|
|
media). If
|
|
.Va mt_count
|
|
is zero, only an erase gap is written. It is hard to say which
|
|
drives support only one but not the other option
|
|
.It Dv MTCACHE
|
|
Enable controller buffering.
|
|
.It Dv MTNOCACHE
|
|
Disable controller buffering.
|
|
.It Dv MTSETBSIZ
|
|
Set the blocksize to use for the device/mode.
|
|
If the device is capable of variable blocksize operation, and the
|
|
blocksize is set to 0, then the drive will be driven in variable mode.
|
|
This parameter is in effect for the present mount session only, unless
|
|
the device was opened in Control Mode (in which case this set value persists
|
|
until a reboot).
|
|
.It Dv MTSETDNSTY
|
|
Set the density value (see
|
|
.Xr mt 1 )
|
|
to use when running in the mode opened (minor bits 2 and 3).
|
|
This parameter is in effect for the present
|
|
mount session only, unless the device was opened in Control Mode (in which
|
|
case this set value persists until a reboot).
|
|
Any byte sized value may be specified. Note that
|
|
only a very small number of them will actually usefully work. The
|
|
rest will cause the tape drive to spit up.
|
|
.It Dv MTCMPRESS
|
|
Enable or disable tape drive data compression.
|
|
Typically tape drives will quite contentedly ignore settings on
|
|
reads, and will probably keep you from changing density for writing
|
|
anywhere but BOT.
|
|
.It Dv MTEWARN
|
|
Enable or disable EARLY WARNING at EOM behaviour (using the count
|
|
as a boolean value).
|
|
.El
|
|
.It Dv MTIOCRDSPOS
|
|
.Pq Li "u_int32_t"
|
|
Read device logical block position.
|
|
Not all drives support this option.
|
|
.It Dv MTIOCRDHPOS
|
|
.Pq Li "u_int32_t"
|
|
Read device hardware block position.
|
|
Not all drives support this option.
|
|
.It Dv MTIOCSLOCATE
|
|
.Pq Li "u_int32_t"
|
|
Position the tape to the specified device logical block position.
|
|
.It Dv MTIOCHLOCATE
|
|
.Pq Li "u_int32_t"
|
|
Position the tape to the specified hardware block position.
|
|
Not all drives support this option.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/[n][e]rst[0-9] -compact
|
|
.It Pa /dev/[n][e]rst[0-9]
|
|
general form:
|
|
.It Pa /dev/rst0
|
|
Mode 0, Rewind on close
|
|
.It Pa /dev/nrst0
|
|
Mode 1, No rewind on close
|
|
.It Pa /dev/erst0
|
|
Mode 2, Eject on close (if capable)
|
|
.It Pa /dev/enst0
|
|
Mode 3, Control Mode (elsewise like mode 0)
|
|
.El
|
|
.Sh BUGS
|
|
The selection of compression could possibly also be usefully done
|
|
as with a minor device bit.
|
|
.Sh DIAGNOSTICS
|
|
A variety, far too many to list.
|
|
.Sh SEE ALSO
|
|
.Xr mt 1 ,
|
|
.Xr intro 4 ,
|
|
.Xr mtio 4 ,
|
|
.Xr scsi 4
|
|
.Sh HISTORY
|
|
This
|
|
.Nm
|
|
driver was originally written for
|
|
.Tn Mach
|
|
2.5 by Julian Elischer, and was ported to
|
|
.Nx
|
|
by Charles Hannum.
|
|
This man page was edited for
|
|
.Nx
|
|
by Jon Buller.
|