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