1.\" $OpenBSD: st.4,v 1.6 2001/06/22 12:15:47 mpech Exp $ 2.\" $NetBSD: st.4,v 1.2 1996/10/20 23:15:24 explorer Exp $ 3.\" 4.\" Copyright (c) 1996 5.\" Julian Elischer <julian@freebsd.org>. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd August 23, 1996 30.Dt ST 4 31.Os 32.Sh NAME 33.Nm st 34.Nd SCSI tape driver 35.Sh SYNOPSIS 36.Cd st* at scsibus? target ? lun ? 37.Cd st1 at scsibus0 target 4 lun 0 38.Sh DESCRIPTION 39The 40.Nm 41driver provides support for 42.Tn SCSI 43tape drives. 44It allows a tape drive to be run in several different modes depending 45on minor numbers and supports several different 46.Dq sub-modes . 47The device can have both a 48.Em raw 49interface and a 50.Em block 51interface; however, only the raw interface is usually used (or recommended). 52.Pp 53.Tn SCSI 54devices have a relatively high level interface and talk to the system via a 55.Tn SCSI 56adapter and a 57.Tn SCSI 58adapter driver 59(e.g., 60.Xr ahc 4 ) . 61A 62.Tn SCSI 63adapter must also be separately configured into the system before a 64.Tn SCSI 65tape can be configured. 66.Pp 67As the 68.Tn SCSI 69adapter is probed during boot, the 70.Tn SCSI 71bus is scanned for devices. 72Any devices found which answer as 73.Sq Em Sequential 74type devices will be attached to the 75.Nm 76driver. 77.Sh MOUNT SESSIONS 78The 79.Nm 80driver is based around the concept of a 81.Dq Em mount session , 82which is defined as the period between the time that a tape is 83mounted, and the time when it is unmounted. 84Any parameters set during a mount session remain in effect for the remainder 85of the session or until replaced. 86The tape can be unmounted, bringing the session to a close in several ways. 87These include: 88.Bl -enum 89.It 90Closing an 91.Dq unmount device , 92referred to as sub-mode 00 below. 93An example is 94.Pa /dev/rst0 . 95.It 96Using the 97.Dv MTOFFL 98.Xr ioctl 2 99command, reachable through the 100.Sq Cm offline 101command of 102.Xr mt 1 . 103.It 104Opening a different mode will implicitly unmount the tape, thereby 105closing off the mode that was previously mounted. 106All parameters will be loaded freshly from the new mode. 107(See below for more on modes.) 108.El 109.Sh MODES AND SUB-MODES 110There are several different 111.Sq operation 112modes. 113These are controlled by bits 2 and 3 of the minor number 114and are designed to allow users to easily read and write different 115formats of tape on devices that allow multiple formats. 116The parameters for each mode can be set individually by hand with the 117.Xr mt 1 118command. 119When a device corresponding to a particular mode is first 120mounted, the operating parameters for that mount session are copied 121from that mode. 122Further changes to the parameters during the session will change those in 123effect for the session but not those set in the operation mode. 124To change the parameters for an operation mode, one must compile them into the 125.Dq Em quirk 126table in the driver's source code. 127.Pp 128In addition to the operating modes mentioned above, bits 0 and 1 129of the minor number are interpreted as 130.Sq sub-modes . 131The sub-modes differ in the action taken when the device is closed: 132.Bl -tag -width XXXX 133.It 00 134A close will rewind the device; if the tape has been written, then 135a file mark will be written before the rewind is requested. 136The device is unmounted. 137.It 01 138A close will leave the tape mounted. 139If the tape was written to, a file mark will be written. 140No other head positioning takes place. 141Any further reads or writes will occur directly after the last 142read, or the written file mark. 143.It 10 144A close will rewind the device. 145If the tape has been written, then a file mark will be written before the 146rewind is requested. 147On completion of the rewind an unload command will be issued. 148The device is unmounted. 149.It 11 150Reserved. 151Currently unused. 152.El 153.Sh BLOCKING MODES 154.Tn SCSI 155tapes may run in either 156.Sq Em variable 157or 158.Sq Em fixed 159block-size modes. 160Most 161.Tn QIC Ns -type 162devices run in fixed block-size mode, where most nine-track tapes 163and many new cartridge formats allow variable block-size. 164The difference between the two is as follows: 165.Bl -inset 166.It Variable block-size: 167Each write made to the device results in a single logical record 168written to the tape. 169One can never read or write 170.Em part 171of a record from tape (though you may request a larger block and 172read a smaller record); nor can one read multiple blocks. 173Data from a single write is therefore read by a single read. 174The block size used may be any value supported by the device, the 175.Tn SCSI 176adapter and the system (usually between 1 byte and 64 Kbytes, 177sometimes more). 178.Pp 179When reading a variable record/block from the tape, the head is 180logically considered to be immediately after the last item read, 181and before the next item after that. 182If the next item is a file mark, but it was never read, then the next 183process to read will immediately hit the file mark and receive an 184end-of-file notification. 185.It Fixed block-size 186data written by the user is passed to the tape as a succession of 187fixed size blocks. 188It may be contiguous in memory, but it is considered to be a series of 189independent blocks. 190One may never write an amount of data that is not an exact multiple of the 191blocksize. 192One may read and write the same data as a different set of records. 193In other words, blocks that were written together may be read separately, 194and vice-versa. 195.Pp 196If one requests more blocks than remain in the file, the drive will 197encounter the file mark. 198Because there is some data to return (unless there were no records before 199the file mark), the read will succeed, returning that data. 200The next read will return immediately with an 201.Dv EOF . 202(As above, if the file mark is never read, it remains for the next process 203to read if in no-rewind mode.) 204.El 205.Sh FILE MARK HANDLING 206The handling of file marks on write is automatic. 207If the user has written to the tape, and has not done a read since the last 208write, then a file mark will be written to the tape when the device is closed. 209If a rewind is requested after a write, then the driver 210assumes that the last file on the tape has been written, and ensures 211that there are two file marks written to the tape. 212The exception to this is that there seems to be a standard (which we follow, 213but don't understand why) that certain types of tape do not actually 214write two file marks to tape, but when read, report a 215.Dq phantom 216file mark when the last file is read. 217These devices include the QIC family of devices. 218(It might be that this set of devices is the same set as that of fixed 219This has not yet been determined, and they are treated as separate 220behaviors by the driver at this time.) 221.Sh KERNEL CONFIGURATION 222Because different tape drives behave differently, there is a 223mechanism within the source to 224.Nm 225to quickly and conveniently recognize and deal with brands and 226models of drive that have special requirements. 227.Pp 228There is a table (called the 229.Dq Em quirk table ) 230in which the identification strings of known errant drives can be stored. 231Alongside each is a set of flags that allows the setting 232of densities and blocksizes for each of the modes, along with a 233set of 234.Dq QUIRK 235flags that can be used to enable or disable sections 236of code within the driver if a particular drive is recognized. 237.Sh IOCTLS 238The following 239.Xr ioctl 2 240calls apply to 241.Tn SCSI 242tapes. 243Some also apply to other tapes. 244They are defined in the header file 245.Aq Pa /sys/mtio.h . 246.\" 247.\" Almost all of this discussion belongs in a separate mt(4) 248.\" manual page, since it is common to all magnetic tapes. 249.\" 250.Pp 251.Bl -tag -width MTIOCEEOT 252.It Dv MTIOCGET 253.Pq Li "struct mtget" 254Retrieve the status and parameters of the tape. 255.It Dv MTIOCTOP 256.Pq Li "struct mtop" 257Perform a multiplexed operation. 258The argument structure is as follows: 259.Bd -literal -offset indent 260struct mtop { 261 short mt_op; 262 daddr_t mt_count; 263}; 264.Ed 265.Pp 266The following operation values are defined for 267.Va mt_op : 268.Bl -tag -width MTSELDNSTY 269.It Dv MTWEOF 270Write 271.Va mt_count 272end of file marks at the present head position. 273.It Dv MTFSF 274Skip over 275.Va mt_count 276file marks. 277Leave the head on the EOM side of the last skipped file mark. 278.It Dv MTBSF 279Skip 280.Em backwards 281over 282.Va mt_count 283file marks. 284Leave the head on the BOM (beginning of media) side of the last skipped 285file mark. 286.It Dv MTFSR 287Skip forwards over 288.Va mt_count 289records. 290.It Dv MTBSR 291Skip backwards over 292.Va mt_count 293records. 294.It Dv MTREW 295Rewind the device to the beginning of the media. 296.It Dv MTOFFL 297Rewind the media (and, if possible, eject). 298Even if the device cannot eject the media it will often no longer respond 299to normal requests. 300.It Dv MTNOP 301No-op; set status only. 302.It Dv MTCACHE 303Enable controller buffering. 304.It Dv MTNOCACHE 305Disable controller buffering. 306.It Dv MTSETBSIZ 307Set the blocksize to use for the device/mode. 308If the device is capable of variable blocksize operation, and the blocksize 309is set to 0, then the drive will be driven in variable mode. 310This parameter is in effect for the present mount session only. 311.It Dv MTSETDNSTY 312Set the density value (see 313.Xr mt 1 ) 314to use when running in the mode opened (minor bits 2 and 3). 315This parameter is in effect for the present 316mount session only. 317.El 318.It Dv MTIOCIEOT 319Set end-of-tape processing (not presently supported for 320.Nm 321devices). 322.It Dv MTIOCEEOT 323Set end-of-tape processing (not presently supported for 324.Nm 325devices). 326.El 327.Sh FILES 328.Bl -tag -width /dev/[n][e]rst[0-9] -compact 329.It Pa /dev/[n][e]rst[0-9] 330general form 331.It Pa /dev/rst0 332Mode 0, rewind on close 333.It Pa /dev/nrst0 334Mode 2, No rewind on close 335.It Pa /dev/erst0 336Mode 3, Eject on close (if capable) 337.El 338.Sh SEE ALSO 339.Xr mt 1 , 340.Xr mtio 4 , 341.Xr scsi 4 342.Sh HISTORY 343This 344.Nm 345driver was originally written for 346.Tn Mach 3472.5 by Julian Elischer, and was ported to 348.Nx 349by Charles Hannum. 350This man page was edited for 351.Nx 352by Jon Buller. 353