Man page for the wst driver. I had planned on committing this earlier,

but forgot.

1 files changed, 231 insertions, 0 deletions

diff --git a/share/man/man4/wst.4 b/share/man/man4/wst.4
new file mode 100644
index 0000000..7bd493b
--- /dev/null
+++ b/share/man/man4/wst.4
@@ -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 .