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