diff options
author | imp <imp@FreeBSD.org> | 1998-10-15 20:43:25 +0000 |
---|---|---|
committer | imp <imp@FreeBSD.org> | 1998-10-15 20:43:25 +0000 |
commit | 31aef622efcee90bacec09b23aae21adb37935af (patch) | |
tree | 1094ec2ee0bb7d52ff1a33277cc1cfc8b219f39b /share/man/man4/wst.4 | |
parent | e5d2797cb58e393a470e35b79ae0131dfd4d6778 (diff) | |
download | FreeBSD-src-31aef622efcee90bacec09b23aae21adb37935af.zip FreeBSD-src-31aef622efcee90bacec09b23aae21adb37935af.tar.gz |
Man page for the wst driver. I had planned on committing this earlier,
but forgot.
Diffstat (limited to 'share/man/man4/wst.4')
-rw-r--r-- | share/man/man4/wst.4 | 231 |
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 . |