diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 9924b7d32894..259e63102982 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,10 +1,10 @@ -# $NetBSD: Makefile,v 1.27 1996/08/13 03:13:30 explorer Exp $ +# $NetBSD: Makefile,v 1.28 1996/10/16 03:14:35 explorer Exp $ # @(#)Makefile 8.1 (Berkeley) 6/18/93 MAN= audio.4 ahc.4 bpf.4 ccd.4 clnp.4 cltp.4 ddb.4 drum.4 esis.4 fd.4 \ icmp.4 idp.4 imp.4 inet.4 ip.4 iso.4 lkm.4 lo.4 netintro.4 ns.4 \ nsip.4 null.4 ppp.4 pty.4 route.4 sl.4 spp.4 strip.4 tb.4 tcp.4 \ - termios.4 tty.4 tp.4 udp.4 unix.4 vnd.4 cd.4 uk.4 sd.4 + termios.4 tty.4 tp.4 udp.4 unix.4 vnd.4 cd.4 uk.4 sd.4 st.4 MLINKS+=fd.4 stderr.4 fd.4 stdin.4 fd.4 stdout.4 MLINKS+=netintro.4 networking.4 SUBDIR= man4.amiga man4.arm32 man4.atari man4.hp300 man4.i386 man4.mac68k \ diff --git a/share/man/man4/st.4 b/share/man/man4/st.4 new file mode 100644 index 000000000000..e97608a643d0 --- /dev/null +++ b/share/man/man4/st.4 @@ -0,0 +1,303 @@ +.\" $NetBSD: st.4,v 1.1 1996/10/16 03:13:11 explorer Exp $ +.\" Copyright history unknown... +.Dd August 23, 1996 +.Dt ST 4 +.Os NetBSD +.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 +`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 `unmount device', referred to as sub-mode 00 below. An +example is +.Pa /dev/rst0 . +.It +Using the 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 +Reserved. Currently unused. +.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 `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 +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. +.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 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. +.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. +.El +.It Dv MTIOCIEOT +Set end-of-tape processing (not presently supported for +.Nm +devices). +.It Dv MTIOCEEOT +Set end-of-tape processing (not presently supported for +.Nm +devices). +.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 2, No rewind on close +.It Pa /dev/erst0 +Mode 3, Eject on close (if capable) +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr mt 1 , +.Xr scsi 4 +.Sh HISTORY +This +.Nm +driver was originally written for +.Tn Mach +2.5 by Julian Elischer, and was ported to +.Tn NetBSD +by Charles Hannum. This man page was edited for +.Tn NetBSD +by Jon Buller.