Man page for the wst driver. I had planned on committing this earlier,
but forgot.
This commit is contained in:
imp
parent
e5d2797cb5
commit
31aef622ef
231
share/man/man4/wst.4
Normal file
231
share/man/man4/wst.4
Normal file
@ -0,0 +1,231 @@
|
||||
.\" $Id: ch.4,v 1.11 1997/06/02 21:01:00 max Exp $
|
||||
.\" Copyright (c) 1998
|
||||
.\" Warner Losh <imp@village.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 27, 1998
|
||||
.Dt WST 4
|
||||
.Os FreeBSD
|
||||
.Sh NAME
|
||||
.Nm wst
|
||||
.Nd ATAPI Tape drive
|
||||
.Sh SYNOPSIS
|
||||
.Cd options ATAPI
|
||||
.Cd device wst0
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Mn
|
||||
driver provides support for a
|
||||
.Tn atapi
|
||||
tape drive connected to an
|
||||
.Tn IDE
|
||||
bus. It allows the tape to be run in up to four different modes
|
||||
depending on minor numbers and supports several different `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). In general the interfaces are similar to those
|
||||
described by
|
||||
.Xr st 4
|
||||
or
|
||||
.Xr mt 4 .
|
||||
.Pp
|
||||
An IDE adapter must also be configured into the kernel before the tape
|
||||
drive can be configured. In addition, ATAPI must be enabled in the
|
||||
kernel as well.
|
||||
.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 `unmount device',
|
||||
referred to as sub-mode 00 below. An example is
|
||||
.Pa /dev/rwst0 .
|
||||
.It
|
||||
Using the MTOFFL
|
||||
.Xr ioctl 2
|
||||
command, reachable through the
|
||||
.Sq Cm offline
|
||||
command of
|
||||
.Xr wst 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
|
||||
.Pp
|
||||
Parameters that are required to last across the unmounting of a tape
|
||||
should be set on the control device. This is sub-mode 3 (see below) and is
|
||||
reached through a file with a name of the form
|
||||
.Sm off
|
||||
.No Xo
|
||||
.Pa /dev/wst
|
||||
.Ar Y
|
||||
.Pa ctl.
|
||||
.Ar X
|
||||
.Xc ,
|
||||
.Sm on
|
||||
where
|
||||
.Ar Y
|
||||
is the drive number and
|
||||
.Ar X
|
||||
is the mode number.
|
||||
.Sh MODES AND SUB-MODES
|
||||
There are four
|
||||
.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 either assign the parameters to the control device.
|
||||
.Pp
|
||||
In addition to the four 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 a special mode, known as the
|
||||
.Dq control device
|
||||
for the mode. Parameters set for the mode while in this sub-mode will
|
||||
be remembered from one mount to the next. This allows the system
|
||||
administrator to set different characteristics (e.g., density,
|
||||
blocksize and eventually compression)
|
||||
on each mode, and have the different modes keep those parameters
|
||||
independent of any parameter changes a user may invoke during a single
|
||||
mount session. At the completion of the user's mount session, drive
|
||||
parameters will revert to those set by the administrator. I/O
|
||||
operations cannot be performed on this device/sub-mode.
|
||||
.El
|
||||
.Sh BLOCKING MODES
|
||||
.Tn ATAPI
|
||||
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 IDE
|
||||
controller 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 `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 KERNEL CONFIGURATION
|
||||
In configuring, if an optional
|
||||
.Ar count
|
||||
is given in the specification, that number of tape devices are configured.
|
||||
.Pp
|
||||
.Sh NOTES
|
||||
Some motherboards and IDE controllers are out of spec when it comes to
|
||||
certain minor, but critical to tape, sections of ATAPI spec. These
|
||||
motherboards are mostly rare, with the exception of the Natoma 440FX
|
||||
chipset found on Pentium Pro motherboards.
|
||||
.Sh FILES
|
||||
.Bl -tag -width /dev/wst[0-9] -compact
|
||||
.It Pa /dev/wst[0-9]
|
||||
device entries
|
||||
.El
|
||||
.Sh DIAGNOSTICS
|
||||
None.
|
||||
.Sh SEE ALSO
|
||||
.Sh HISTORY
|
||||
Soren Schmidt <sos@sos.freebsd.dk> wrote this driver which first
|
||||
appeared in
|
||||
.Fx 3.0 .
|
||||
Loading…
Reference in New Issue
Block a user