sa.4 revision 13744
1.Dd January 17, 1996 2.Dt ST 4 3.Os FreeBSD 4.Sh NAME 5.Nm st 6.Nd SCSI tape driver 7.Sh SYNOPSIS 8.Cd tape st 9.Cd device st1 at scbus0 target 4 lun 0 10.Sh DESCRIPTION 11The 12.Nm 13driver provides support for a 14.Tn SCSI 15tape. It allows the tape 16to be run in up to four different modes depending on minor numbers 17and supports several different `sub-modes'. 18The device can have both a 19.Em raw 20interface 21and a 22.Em block 23interface; however, only the raw interface is usually used (or recommended). 24In general the interfaces are similar to those described by 25.Xr wt 4 26or 27.Xr mt 4 . 28.Pp 29Where the 30.Xr wt 4 31device has a fairly low level interface to the system, 32.Tn SCSI 33devices have a much higher level interface and talk to the system via 34a 35.Tn SCSI 36adapter and a 37.Tn SCSI 38adapter driver 39(e.g., 40.Xr ahc 4 ) . 41A 42.Tn SCSI 43adapter must also be separately configured into the system 44before a 45.Tn SCSI 46tape can be configured. 47.Pp 48As the 49.Tn SCSI 50adapter is probed during boot, the 51.Tn SCSI 52bus is scanned for devices. Any devices found which answer as 53.Sq Em Sequential 54type devices will be attached to the 55.Nm 56driver. 57In 58.Tn FreeBSD 59releases prior to 2.1, the first found is attached as 60.Em st0 61and the next, 62.Em st1 , 63etc. 64Beginning in release 2.1 it is possible to specify what 65.Nm 66unit a device should 67come on line as; refer to 68.Xr scsi 4 69for details on kernel configuration. 70.Sh MOUNT SESSIONS 71The 72.Nm 73driver is based around the concept of a 74.Dq Em mount session , 75which is defined as the period between the time that a tape is 76mounted, and the time when it is unmounted. Any parameters set during 77a mount session remain in effect for the remainder of the session or 78until replaced. The tape can be unmounted, bringing the session to a 79close in several ways. These include: 80.Bl -enum 81.It 82Closing an `unmount device', 83referred to as sub-mode 00 below. An example is 84.Pa /dev/rst0 . 85.It 86Using the MTOFFL 87.Xr ioctl 2 88command, reachable through the 89.Sq Cm offline 90command of 91.Xr st 1 . 92.It 93Opening a different mode will implicitly unmount the tape, thereby closing 94off the mode that was previously mounted. All parameters will be loaded 95freshly from the new mode. (See below for more on modes.) 96.El 97.Pp 98Parameters that are required to last across the unmounting of a tape 99should be set on the control device. This is sub-mode 3 (see below) and is 100reached through a file with a name of the form 101.Sm off 102.No Xo 103.Pa /dev/st 104.Ar Y 105.Pa ctl. 106.Ar X 107.Xc , 108.Sm on 109where 110.Ar Y 111is the drive number and 112.Ar X 113is the mode number. 114.Sh MODES AND SUB-MODES 115There are four 116.Sq operation 117modes. These are controlled by bits 2 and 3 of the minor number and 118are designed to allow users to easily read and write different formats 119of tape on devices that allow multiple formats. The parameters for 120each mode can be set individually by hand with the 121.Xr mt 1 122command. When a device corresponding to a particular mode is first 123mounted, The operating parameters for that 124mount session 125are copied from that mode. Further changes to the parameters during the 126session will change those in effect for the session but not those set 127in the operation mode. To change the parameters for an operation mode, 128one must either assign the parameters to the control device, or compile 129them into the 130.Dq Em Rogues Gallery 131table in the driver's source code. 132.Pp 133In addition to the four operating modes mentioned above, 134bits 0 and 1 of the minor number are interpreted as 135.Sq sub-modes . 136The sub-modes differ in the action taken when the device is closed: 137.Bl -tag -width XXXX 138.It 00 139A close will rewind the device; if the tape has been 140written, then a file mark will be written before the rewind is requested. 141The device is unmounted. 142.It 01 143A close will leave the tape mounted. 144If the tape was written to, a file mark will be written. 145No other head positioning takes place. 146Any further reads or writes will occur directly after the 147last read, or the written file mark. 148.It 10 149A close will rewind the device. If the tape has been 150written, then a file mark will be written before the rewind is requested. 151On completion of the rewind an unload command will be issued. 152The device is unmounted. 153.It 11 154This is a special mode, known as the 155.Dq control device 156for the mode. Parameters set for the mode while in this sub-mode will 157be remembered from one mount to the next. This allows the system 158administrator to set different characteristics (e.g., density, 159blocksize) 160.\" (and eventually compression) 161on each mode, and have the different modes keep those parameters 162independent of any parameter changes a user may invoke during a single 163mount session. At the completion of the user's mount session, drive 164parameters will revert to those set by the administrator. I/O 165operations cannot be performed on this device/sub-mode. General 166.Xr scsi 4 167ioctls can 168.Em only 169be performed against the control device. 170.El 171.Sh BLOCKING MODES 172.Tn SCSI 173tapes may run in either 174.Sq Em variable 175or 176.Sq Em fixed 177block-size modes. Most 178.Tn QIC Ns -type 179devices run in fixed block-size mode, where most nine-track tapes and 180many new cartridge formats allow variable block-size. The difference 181between the two is as follows: 182.Bl -inset 183.It Variable block-size: 184Each write made to the device results in a single logical record 185written to the tape. One can never read or write 186.Em part 187of a record from tape (though you may request a larger block and read 188a smaller record); nor can one read multiple blocks. Data from a 189single write is therefore read by a single read. The block size used 190may be any value supported by the device, the 191.Tn SCSI 192adapter and the system (usually between 1 byte and 64 Kbytes, 193sometimes more). 194.Pp 195When reading a variable record/block from the tape, the head is 196logically considered to be immediately after the last item read, 197and before the next item after that. If the next item is a file mark, 198but it was never read, then the next 199process to read will immediately hit the file mark and receive an end-of-file notification. 200.It Fixed block-size 201Data written by the user is passed to the tape as a succession of 202fixed size blocks. It may be contiguous in memory, but it is 203considered to be a series of independent blocks. One may never write 204an amount of data that is not an exact multiple of the blocksize. One 205may read and write the same data as a different set of records, In 206other words, blocks that were written together may be read separately, 207and vice-versa. 208.Pp 209If one requests more blocks than remain in the file, the drive will 210encounter the file mark. Because there is some data to return (unless 211there were no records before the file mark), the read will succeed, 212returning that data, The next read will return immediately with an 213EOF. (As above, if the file mark is never read, it remains for the next process to read if in no-rewind mode.) 214.El 215.Sh FILE MARK HANDLING 216The handling of file marks on write is automatic. If the user has 217written to the tape, and has not done a read since the last write, 218then a file mark will be written to the tape when the device is 219closed. If a rewind is requested after a write, then the driver 220assumes that the last file on the tape has been written, and ensures 221that there are two file marks written to the tape. The exception to 222this is that there seems to be a standard (which we follow, but don't 223understand why) that certain types of tape do not actually write two 224file marks to tape, but when read, report a `phantom' file mark when the 225last file is read. These devices include the QIC family of devices. 226(It might be that this set of devices is the same set as that of fixed 227block devices. This has not been determined yet, and they are treated 228as separate behaviors by the driver at this time.) 229.Sh KERNEL CONFIGURATION 230Because different tape drives behave differently, there is a mechanism 231within the source to 232.Nm 233to quickly and conveniently recognize and deal 234with brands and models of drive that have special requirements. 235.Pp 236There is a table (called the 237.Dq Em Rogues Gallery ) 238in which the identification 239strings of known errant drives can be stored. Alongside each is 240a set of flags that allows the setting of densities and blocksizes for each 241of the four modes, along with a set of `QUIRK' flags that can be 242used to enable or disable sections of code within the driver if a particular 243drive is recognized. 244.Sh IOCTLS 245The following 246.Xr ioctl 2 247calls apply to 248.Tn SCSI 249tapes. Some also apply to other tapes. They are defined 250in the header file 251.Aq Pa /sys/mtio.h . 252.\" 253.\" Almost all of this discussion belongs in a separate mt(4) 254.\" manual page, since it is common to all magnetic tapes. 255.\" 256.Pp 257.Bl -tag -width MTIOCEEOT 258.It Dv MTIOCGET 259.Pq Li "struct mtget" 260Retrieve the status and parameters of the tape. 261.It Dv MTIOCTOP 262.Pq Li "struct mtop" 263Perform a multiplexed operation. The argument structure is as follows: 264.Bd -literal -offset indent 265struct mtop { 266 short mt_op; 267 daddr_t mt_count; 268}; 269.Ed 270.Pp 271The following operation values are defined for 272.Va mt_op : 273.Bl -tag -width MTSELDNSTY 274.It Dv MTWEOF 275Write 276.Va mt_count 277end of file marks at the present head position. 278.It Dv MTFSF 279Skip over 280.Va mt_count 281file marks. Leave the head on the EOM side of the last skipped 282file mark. 283.It Dv MTBSF 284Skip 285.Em backwards 286over 287.Va mt_count 288file marks. Leave the head on the BOM (beginning of media) 289side of the last skipped file mark. 290.It Dv MTFSR 291Skip forwards over 292.Va mt_count 293records. 294.It Dv MTBSR 295Skip backwards over 296.Va mt_count 297records. 298.It Dv MTREW 299Rewind the device to the beginning of the media. 300.It Dv MTOFFL 301Rewind the media (and, if possible, eject). Even if the device cannot 302eject the media it will often no longer respond to normal requests. 303.It Dv MTNOP 304No-op; set status only. 305.It Dv MTCACHE 306Enable controller buffering. 307.It Dv MTNOCACHE 308Disable controller buffering. 309.It Dv MTSETBSIZ 310Set the blocksize to use for the device/mode. If the device is capable of 311variable blocksize operation, and the blocksize is set to 0, then the drive 312will be driven in variable mode. This parameter is in effect for the present 313mount session only, unless set on the control device. 314.It Dv MTSETDNSTY 315Set the density value (see 316.Xr mt 1 ) 317to use when running in the mode opened (minor bits 2 and 3). 318This parameter is in effect for the present 319mount session only, unless set on the control device. 320.El 321.It Dv MTIOCIEOT 322Set end-of-tape processing (not presently supported for 323.Nm 324devices). 325.It Dv MTIOCEEOT 326Set end-of-tape processing (not presently supported for 327.Nm 328devices). 329.El 330.Pp 331In addition, the 332.Nm 333driver will allow the use of any of the general 334.Xr scsi 4 335.Fn ioctl 336commands, on the control device only. 337.Sh FILES 338.Bl -tag -width /dev/[n][e]rst[0-9].[0-3] -compact 339.It Pa /dev/[n][e]rst[0-9].[0-3] 340general form: 341.It Pa /dev/rst0.0 342Mode 0, rewind on close 343.It Pa /dev/nrst0.2 344Mode 2, No rewind on close 345.It Pa /dev/erst0.3 346Mode 3, Eject on close (if capable) 347.It Pa /dev/rst0 348Another name for rst0.0 349.It Pa /dev/nrst0 350Another name for nrst0.0 351.It Pa /dev/st0ctl.0 352Parameters set to this device become the default parameters for [en]rst0.0 353.It Pa /dev/st0ctl.1 354Parameters set to this device become the default parameters for [en]rst0.1 355.It Pa /dev/st0ctl.2 356Parameters set to this device become the default parameters for [en]rst0.2 357.It Pa /dev/st0ctl.3 358Parameters set to this device become the default parameters for [en]rst0.3 359.El 360.Sh DIAGNOSTICS 361None. 362.Sh SEE ALSO 363.Xr mt 1 , 364.Xr scsi 4 365.Sh HISTORY 366This 367.Nm 368driver was originally written for 369.Tn Mach 3702.5, and was ported to 371.Tn FreeBSD 372by Julian Elischer. 373