1.\" $NetBSD: st.4,v 1.22 2002/07/20 18:22:47 jdc Exp $ 2.\" 3.\" Copyright (c) 1996 4.\" Julian Elischer <julian@freebsd.org>. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd August 23, 1996 29.Dt ST 4 30.Os 31.Sh NAME 32.Nm st 33.Nd SCSI/ATAPI tape driver 34.Sh SYNOPSIS 35.Cd st* at scsibus? target ? lun ? 36.Cd st1 at scsibus0 target 4 lun 0 37.Cd "st* at atapibus? drive ? flags 0x0000" 38.Sh DESCRIPTION 39The 40.Nm 41driver provides support for 42.Tn SCSI 43and Advanced Technology Attachment Packet Interface 44.Pq Tn ATAPI 45tape drives. 46It allows a tape drive to be run in several different 47modes depending on minor numbers and supports several different 48.Sq sub-modes . 49The device can have both a 50.Em raw 51interface and a 52.Em block 53interface; however, only the raw interface is usually used (or recommended). 54.Pp 55.Tn SCSI 56and 57.Tn ATAPI 58devices have a relatively high level interface and talk to the system via a 59.Tn SCSI 60or 61.Tn ATAPI 62adapter and a 63.Tn SCSI 64or 65.Tn ATAPI 66adapter driver 67(e.g. 68.Xr ahc 4 , 69.Xr pciide 4 ) . 70A 71.Tn SCSI 72or 73.Tn ATAPI 74adapter must also be separately configured into the system before a 75.Tn SCSI 76or 77.Tn ATAPI 78tape can be configured. 79.Pp 80As the 81.Tn SCSI 82or 83.Tn ATAPI 84adapter is probed during boot, the 85.Tn SCSI 86or 87.Tn ATAPI 88bus is scanned for devices. 89Any devices found which answer as 90.Sq Em Sequential 91type devices will be attached to the 92.Nm 93driver. 94.Sh MOUNT SESSIONS 95The 96.Nm 97driver is based around the concept of a 98.Dq Em mount session , 99which is defined as the period between the time that a tape is 100mounted, and the time when it is unmounted. 101Any parameters set during a mount session remain in effect for the 102remainder of the session or until replaced. 103The tape can be unmounted, bringing the session to a close in 104several ways. 105These include: 106.Bl -enum 107.It 108Closing an 109.Sq unmount device , 110referred to as sub-mode 00 below. 111An example is 112.Pa /dev/rst0 . 113.It 114Using the 115.Dv MTOFFL 116.Xr ioctl 2 117command, reachable through the 118.Sq Cm offline 119command of 120.Xr mt 1 . 121.It 122Opening a different mode will implicitly unmount the tape, thereby 123closing off the mode that was previously mounted. 124All parameters will be loaded freshly from the new mode 125(See below for more on modes). 126.El 127.Sh MODES AND SUB-MODES 128There are several different 129.Sq operation 130modes. 131These are controlled by bits 2 and 3 of the minor number 132and are designed to allow users to easily read and write different 133formats of tape on devices that allow multiple formats. 134The parameters for each mode can be set individually by hand with the 135.Xr mt 1 136command. 137When a device corresponding to a particular mode is first 138mounted, The operating parameters for that mount session are copied 139from that mode. 140Further changes to the parameters during the session will change 141those in effect for the session but not those set in the operation mode. 142To change the parameters for an operation mode, one must compile 143them into the 144.Dq Em quirk 145table in the driver's source code. 146.Pp 147In addition to the operating modes mentioned above, bits 0 and 1 148of the minor number are interpreted as 149.Sq sub-modes . 150The sub-modes differ in the action taken when the device is closed: 151.Bl -tag -width XXXX 152.It 00 153A close will rewind the device; if the tape has been written, then 154a file mark will be written before the rewind is requested. 155The device is unmounted. 156.It 01 157A close will leave the tape mounted. 158If the tape was written to, a file mark will be written. 159No other head positioning takes place. 160Any further reads or writes will occur directly after the last 161read, or the written file mark. 162.It 10 163A close will rewind the device. 164If the tape has been written, then a file mark will be written 165before the rewind is requested. 166On completion of the rewind an unload command will be issued. 167The device is unmounted. 168.It 11 169This is Control mode, which allows the tape driver to be opened without a tape 170inserted to allow various ioctls (e.g. MTIOCGET or MTIOCTOP to set density 171or blocksize) and raw SCSI command on 172through. I/O can be done in this mode, if desired, with the same 173rewind/eject behaviour as mode 01. This isn't really an 'action taken 174on close' type of distinction, but this seems to be the place to put 175this mode. 176.El 177.Sh BLOCKING MODES 178.Tn SCSI 179tapes may run in either 180.Sq Em variable 181or 182.Sq Em fixed 183block-size modes. 184Most 185.Tn QIC Ns -type 186devices run in fixed block-size mode, where most nine-track tapes 187and many new cartridge formats allow variable block-size. 188The difference between the two is as follows: 189.Bl -inset 190.It Variable block-size 191Each write made to the device results in a single logical record 192written to the tape. 193One can never read or write 194.Em part 195of a record from tape (though you may request a larger block and 196read a smaller record); nor can one read multiple blocks. 197Data from a single write is therefore read by a single read. 198The block size used may be any value supported by the device, the 199.Tn SCSI 200adapter and the system (usually between 1 byte and 64 Kbytes, 201sometimes more). 202.Pp 203When reading a variable record/block from the tape, the head is 204logically considered to be immediately after the last item read, 205and before the next item after that. 206If the next item is a file mark, but it was never read, then the 207next process to read will immediately hit the file mark and receive 208an end-of-file notification. 209.It Fixed block-size 210Data written by the user is passed to the tape as a succession of 211fixed size blocks. 212It may be contiguous in memory, but it is considered to be a series 213of independent blocks. 214One may never write an amount of data that is not an exact multiple 215of the blocksize. 216One may read and write the same data as a different set of records, 217In other words, blocks that were written together may be read 218separately, and vice-versa. 219.Pp 220If one requests more blocks than remain in the file, the drive will 221encounter the file mark. 222Because there is some data to return (unless there were no records 223before the file mark), the read will succeed, returning that data. 224The next read will return immediately with an EOF (as above, if 225the file mark is never read, it remains for the next process to 226read if in no-rewind mode). 227.El 228.Sh FILE MARK HANDLING 229The handling of file marks on write is automatic. 230If the user has written to the tape, and has not done a read since 231the last write, then a file mark will be written to the tape when 232the device is closed. 233If a rewind is requested after a write, then the driver assumes 234that the last file on the tape has been written, and ensures that 235there are two file marks written to the tape. 236The exception to this is that there seems to be a standard (which 237we follow, but don't understand why) that certain types of tape do 238not actually write two file marks to tape, but when read, report a 239.Sq phantom 240file mark when the last file is read. 241These devices include the QIC family of devices 242(it might be that this set of devices is 243the same set as that of fixed block devices. 244This has not been determined yet, and they are treated as separate 245behaviors by the driver at this time). 246.Sh EOM HANDLING 247Attempts to write past EOM and how EOM is reported are handled slightly 248differently based upon whether EARLY WARNING recognition is enabled in 249the driver. 250.Pp 251If EARLY WARNING recognitions is 252.Em not 253enabled, then detection 254of EOM (as reported in SCSI Sense Data with an EOM indicator) 255causes the write operation to be flagged with I/O error (EIO). 256This has the effect for the user application of not knowing actually 257how many bytes were read (since the return of the 258.Xr read 2 259system call is set to \(mi1). 260.Pp 261If EARLY WARNING recognition 262.Em is 263enabled, then detection of EOM 264(as reported in SCSI Sense Data with an EOM indicator) 265has no immediate effect except that 266the driver notes that EOM has been detected. If the write completing 267didn't transfer all data that was requested, then the residual count 268(counting bytes 269.Em not 270written) 271is returned to the user application. In any event, the next attempt 272to write (if that is the next action the user application takes) 273is immediately completed with no data transferred, and a residual 274returned to the user application indicating that no data was transferred. 275This is the traditional UNIX EOF indication. The state that EOM had 276been seen is then cleared. 277.Pp 278In either mode of operation, the driver does not prohibit the 279user application from writing more data, if it chooses to do so. This 280will continue up until the physical end of media, which is usually 281signalled internally to the driver as a CHECK CONDITION with 282the Sense Key set to VOLUME OVERFLOW. When this or any otherwise 283unhandled error occurs, an error return of EIO will be transmitted 284to the user application. This does indeed mean that if EARLY WARNING 285is enables and the device continues to set EOM indicators prior to 286hitting physical end of media, that an indeterminate number of 'short write 287returns' as described in the previous paragraph will occur. However, the 288expected user application behaviour (in common with other systems) is 289to close the tape and rewind and request another tape upon the receipt 290of the first EOM indicator, possibly after writing one trailer record. 291.Sh KERNEL CONFIGURATION 292Because different tape drives behave differently, there is a 293mechanism within the source to 294.Nm 295to quickly and conveniently recognize and deal with brands and 296models of drive that have special requirements. 297.Pp 298There is a table (called the 299.Dq Em quirk table ) 300in which the identification strings of known errant drives can be stored. 301Alongside each is a set of flags that allows the setting 302of densities and blocksizes for each of the modes, along with a 303set of `QUIRK' flags that can be used to enable or disable sections 304of code within the driver if a particular drive is recognized. 305.Sh IOCTLS 306The following 307.Xr ioctl 2 308calls apply to 309.Tn SCSI 310tapes. 311Some also apply to other tapes. 312They are defined in the header file 313.Aq Pa sys/mtio.h . 314.\" 315.\" Almost all of this discussion belongs in a separate mt(4) 316.\" manual page, since it is common to all magnetic tapes. 317.\" 318.Pp 319.Bl -tag -width MTIOCEEOT 320.It Dv MTIOCGET 321.Pq Li "struct mtget" 322Retrieve the status and parameters of the tape. Error status 323and residual is unlatched and cleared by the driver when it receives 324this ioctl. 325.It Dv MTIOCTOP 326.Pq Li "struct mtop" 327Perform a multiplexed operation. 328The argument structure is as follows: 329.Bd -literal -offset indent 330struct mtop { 331 short mt_op; 332 daddr_t mt_count; 333}; 334.Ed 335.Pp 336The following operation values are defined for 337.Va mt_op : 338.Bl -tag -width MTSELDNSTY 339.It Dv MTWEOF 340Write 341.Va mt_count 342end of file marks at the present head position. 343.It Dv MTFSF 344Skip over 345.Va mt_count 346file marks. 347Leave the head on the EOM side of the last skipped file mark. 348.It Dv MTBSF 349Skip 350.Em backwards 351over 352.Va mt_count 353file marks. 354Leave the head on the BOM (beginning of media) 355side of the last skipped file mark. 356.It Dv MTFSR 357Skip forwards over 358.Va mt_count 359records. 360.It Dv MTBSR 361Skip backwards over 362.Va mt_count 363records. 364.It Dv MTREW 365Rewind the device to the beginning of the media. 366.It Dv MTOFFL 367Rewind the media (and, if possible, eject). 368Even if the device cannot eject the media it will often no longer 369respond to normal requests. 370.It Dv MTNOP 371No-op; set status only. 372.It Dv MTERASE 373Erase the media from current position. If the field 374.Va mt_count 375is nonzero, a full erase is done (from current position to end of 376media). If 377.Va mt_count 378is zero, only an erase gap is written. It is hard to say which 379drives support only one but not the other option 380.It Dv MTCACHE 381Enable controller buffering. 382.It Dv MTNOCACHE 383Disable controller buffering. 384.It Dv MTSETBSIZ 385Set the blocksize to use for the device/mode. 386If the device is capable of variable blocksize operation, and the 387blocksize is set to 0, then the drive will be driven in variable mode. 388This parameter is in effect for the present mount session only, unless 389the device was opened in Control Mode (in which case this set value persists 390until a reboot). 391.It Dv MTSETDNSTY 392Set the density value (see 393.Xr mt 1 ) 394to use when running in the mode opened (minor bits 2 and 3). 395This parameter is in effect for the present 396mount session only, unless the device was opened in Control Mode (in which 397case this set value persists until a reboot). 398Any byte sized value may be specified. Note that 399only a very small number of them will actually usefully work. The 400rest will cause the tape drive to spit up. 401.It Dv MTCMPRESS 402Enable or disable tape drive data compression. 403Typically tape drives will quite contentedly ignore settings on 404reads, and will probably keep you from changing density for writing 405anywhere but BOT. 406.It Dv MTEWARN 407Enable or disable EARLY WARNING at EOM behaviour (using the count 408as a boolean value). 409.El 410.It Dv MTIOCRDSPOS 411.Pq Li "u_int32_t" 412Read device logical block position. 413Not all drives support this option. 414.It Dv MTIOCRDHPOS 415.Pq Li "u_int32_t" 416Read device hardware block position. 417Not all drives support this option. 418.It Dv MTIOCSLOCATE 419.Pq Li "u_int32_t" 420Position the tape to the specified device logical block position. 421.It Dv MTIOCHLOCATE 422.Pq Li "u_int32_t" 423Position the tape to the specified hardware block position. 424Not all drives support this option. 425.El 426.Sh FILES 427.Bl -tag -width /dev/[n][e]rst[0-9] -compact 428.It Pa /dev/[n][e]rst[0-9] 429general form: 430.It Pa /dev/rst0 431Mode 0, Rewind on close 432.It Pa /dev/nrst0 433Mode 1, No rewind on close 434.It Pa /dev/erst0 435Mode 2, Eject on close (if capable) 436.It Pa /dev/enrst0 437Mode 3, Control Mode (elsewise like mode 0) 438.El 439.Sh SEE ALSO 440.Xr mt 1 , 441.Xr intro 4 , 442.Xr mtio 4 , 443.Xr scsi 4 444.Sh HISTORY 445This 446.Nm 447driver was originally written for 448.Tn Mach 4492.5 by Julian Elischer, and was ported to 450.Nx 451by Charles Hannum. 452This man page was edited for 453.Nx 454by Jon Buller. 455.Sh BUGS 456The selection of compression could possibly also be usefully done 457as with a minor device bit. 458