diff options
Diffstat (limited to 'static/netbsd/man4/st.4')
| -rw-r--r-- | static/netbsd/man4/st.4 | 457 |
1 files changed, 457 insertions, 0 deletions
diff --git a/static/netbsd/man4/st.4 b/static/netbsd/man4/st.4 new file mode 100644 index 00000000..f1841abb --- /dev/null +++ b/static/netbsd/man4/st.4 @@ -0,0 +1,457 @@ +.\" $NetBSD: st.4,v 1.25 2010/03/22 18:58:31 joerg 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/ATAPI tape driver +.Sh SYNOPSIS +.Cd "st* at scsibus? target ? lun ?" +.Cd "st1 at scsibus0 target 4 lun 0" +.Cd "st* at atapibus? drive ? flags 0x0000" +.Sh DESCRIPTION +The +.Nm +driver provides support for +.Tn SCSI +and Advanced Technology Attachment Packet Interface +.Pq Tn ATAPI +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 +and +.Tn ATAPI +devices have a relatively high level interface and talk to the system via a +.Tn SCSI +or +.Tn ATAPI +adapter and a +.Tn SCSI +or +.Tn ATAPI +adapter driver +(e.g. +.Xr ahc 4 , +.Xr pciide 4 ) . +A +.Tn SCSI +or +.Tn ATAPI +adapter must also be separately configured into the system before a +.Tn SCSI +or +.Tn ATAPI +tape can be configured. +.Pp +As the +.Tn SCSI +or +.Tn ATAPI +adapter is probed during boot, the +.Tn SCSI +or +.Tn ATAPI +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 +.Em not +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 +.Em is +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 +.Em not +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 +.In 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 "uint32_t" +Read device logical block position. +Not all drives support this option. +.It Dv MTIOCRDHPOS +.Pq Li "uint32_t" +Read device hardware block position. +Not all drives support this option. +.It Dv MTIOCSLOCATE +.Pq Li "uint32_t" +Position the tape to the specified device logical block position. +.It Dv MTIOCHLOCATE +.Pq Li "uint32_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/enrst0 +Mode 3, Control Mode (elsewise like mode 0) +.El +.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. +.Sh BUGS +The selection of compression could possibly also be usefully done +as with a minor device bit. |