sa.4 revision 5884
1.Dd August 27, 1993 2.Dt ST 4 3.Os FreeBSD 4.Sh NAME 5.Nm st 6.Nd scsi tape driver 7.Sh SYNOPSIS 8.Nm device-driver st 9.Op Ar count 10.Sh DESCRIPTION 11The 12.Xr st 13driver provides support for a 14.Em scsi 15tape. It allows the tape 16to be run in upto 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 mode 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 29.Pp 30Where the 31.Xr wt 4 32device has a fairly low level interface to the system, 33.Em SCSI 34devices have a much higher level interface and talk to the system via 35a 36.Em SCSI Adapter 37and a 38.Em Scsi Adapter driver 39e.g. 40.Xr AHA1542 . 41A scsi adapter must also be separatly configured into the system 42before a scsi tape can be configured. 43.Pp 44As the scsi adapter is probed during boot, the 45.Em SCSI 46bus is scanned for devices. Any devices found which answer as 'Sequential' 47type devices will be attached to the 48.Nm 49driver. The first found will be attached as 50.Em st0 51and the next, 52.Em st1 53etc. 54.Pp 55.Sh MOUNT SESSIONS 56The 57.Nm 58driver is based around the concept of a 59.Em Mount Session 60, which is defined as the period between the time that a tape is mounted, 61and the time when it is unmounted. Any parameters set during a 62.Em Mount Session 63remain in effect for the remainder of the session or until replaced. The 64Tape can be unmounted, bringing the session to a close in several ways. 65These include: 66.Bl -tag -width ABOUT_THIS_BIG_BUT_REALLY_BIGGER 67.It Pa closing an 'unmount device' 68This is referred to as sub-mode 00 (see below). An example is /dev/rst0. 69.It Pa an MTOFFL ioctl 70Reachable throught the 'offline' command of 71.Xr st 1 72.It Pa Openning another mode. 73Openning a different mode will implicitly unmount the tape, thereby closing 74off the mode that was previously mounted. All parameters will be loaded 75freshly from the new mode. (see below for more on 'modes'). 76.El 77.Pp 78Parameters that are required to last across the unmounting of a tape, 79should be set on the control device. This is submode 3 (see below) and is 80reached through a file with a name of the form /dev/st{y}ctl.{x}, where 81{y} is the drive number and {x} is the mode number. 82.Pp 83.Sh MODES AND SUB MODES 84There are four Operation modes. These are controlled by bits 2 85and 3 of the minor number and are designed to allow people to easily 86read and write different formats of tape on devices that allow 87multiple formats. The parameters for each mode can be set individually 88by hand with the 89.Xr st 1 90variant of the 91.Xr mt 1 92command. When a device corresponding to a particular mode is first mounted, 93The operating parameters for that 94.Em Mount Session 95Are copied from that mode. Further changes to the parameters during the 96session will change those in effect for the session but not those set 97in the Operating Mode. To change the parameters for an Operating Mode, 98One must either assign the parameters to the control device, or compile 99them into the 'Rogues Gallery' table within the driver. 100.Pp 101In addition to the four Operation Modes mentionned above, 102bits 0 and 1 of the minor number are interpretted as being 'sub-modes'. 103The following sub-modes are supported 104.Bl -tag -width ABOUT_THIS_BIG 105.It Pa 00 106A close will rewind the device. If the tape has been 107written, then a Filemark will be written before the rewind is requested. 108The device is UNMOUNTED. 109.It Pa 01 110A close will leave the tape MOUNTED. 111If the tape was written to a filemark will be written. 112No other head positioning takes place. 113Any further reads or writes will occur directly after the 114last read, or the written filemark. 115.It Pa 10 116A close will rewind the device. If the tape has been 117written, then a Filemark will be written before the rewind is requested. 118On completion of the rewind an UNLOAD command will be issued. 119The device is UNMOUNTED. 120.It Pa 11 121This is a special mode. 122It is known as the 123.Em CONTROL DEVICE 124for the mode. Parameters set for the mode while in this sub 125mode will be remembered from one mount to the next. This allows the 126system administrator to set different characteristics (e.g. density, 127blocksize, (and eventually compression)) on each mode, and have the 128different modes keep those parameters independent of any parameter 129changes a user may invoke during a single mount session. At the 130completion of the user's mount session, drive parameters will revert 131to those set by the administrator. IO operations cannot be performed 132on this device/submode. General 133.Xr scsi 4 134ioctls 135.Em MUST 136be performed against the control device. 137.El 138.Sh BLOCKING MODES 139Scsi Tapes may run in either 'variable' or 'fixed block' modes. 140Most QIC type devices run in Fixed block mode, where most 'reel to reel' tapes and 141many new cartridge formats, allow variable blocksize. The difference between 142the two is as follows: 143.Bl -tag -width variable-blocksize 144.It Pa Variable Blocksize 145Each write made to the device results in a single logical record 146written to the tape. You can never read or write PART of a record 147from tape, (though you may request a larger block and read a smaller 148record). You cannot read multiple blocks either. Data from a single 149write is therefore read by a single read. The block size used may 150be any value supported by the device, the scsi adapter and the 151system. (often variable between 1 byte and 64k (sometimes more)). 152.Pp 153When reading a variable record/block from the tape, the head is 154logically considered to be immediately after the last item read, 155and before the next item after that. If the next item is a Filemark, 156but you never read it because you have all the data, then the next 157process to read will immediately read the filemark and return EOF. 158(assuming you were in non-rewind mode). 159.It Pa fixed Blocksize 160Data written by the user is passed to the tape as a succession of 161fixed size blocks. It may be contiguouse in ram and read in a single 162DMA pass, however it is considered to be a series of independent 163blocks. You may never write an amount of data that is not an exact 164multiple of the blocksize. You may read and write the same data 165as a different set of records, In other words, blocks that were 166written together may be read separatly, and visa versa. 167.Pp 168If you ask for more blocks than there are left in the file, then 169the drive will encounter the filemark. Because there is some data 170to return to you (unless there were no records before the filemark) 171the driver will return the data to you (less than you requested), 172but hide from you the discovery of the Filemark. The NEXT read 173will be returned immediately with an EOF. If you never Make the next 174read, but close the device, the next process to read will immediately 175read the filemark and return EOF. (assuming you were in non-rewind 176mode). 177.El 178.Sh FILEMARK HANDLING 179The handling of filemarks on write is pretty much automatic. If you 180have written to the tape, and not done a read since, then a filemark will 181be written to the tape when you close the device. If a rewind is requested 182after a write, then the driver assumes that you have written the last file 183on the tape and ensures that there are two filemarks written to the tape. 184It takes into account any filemarks already written (whether by close 185or by explicit ioctl). The exception to this is that there seems to be 186a standard (which we follow, but don't understand why) that certain 187types of tape do not actually write two filemarks to tape, 188but when read, report a 'phantom' filemark when the last file is read. 189These devices include the QIC family of devices. It might be that this 190set of devices is the same set as that of fixed block devices. This has not 191been detirmined yet, and they are treated as separate behaviors by the 192driver at this time. 193.Pp 194.SH KERNEL CONFIGURATION 195In configuring, if an optional 196.Ar count 197is given in 198the specification, that number of scsi tapes are configured; 199Most storage for them is allocated only when found so a large number 200of configured devices is cheap. (once the first has included the driver). 201.Pp 202Because different tape drives behave differently, there is a mechanism 203within the source to st, to quickly and conveniently recognise and deal 204with brands and models of drive that have special requirements. 205.Pp 206There is a table (called the rogues gallery) in which the indentification 207strings of known errant drives can be stored. Along with each is 208a set of flags that allows the setting of densities and blocksizes for each 209of the 4 modes, along with a set of 'QUIRK' flags that can be 210used to enable or disable sections of code within the driver if a particular 211drive is recognised. 212.Pp 213.Sh IOCTLS 214The following 215.Xr ioctl 2 216calls apply to scsi tapes. Some also apply to other tapes. They are defined 217in the header file 218.Em /sys/mtio.h. 219 220.Bl -tag -width MTIOCEEOT 221.It Pa MTIOCGET 222Get the mt control structure filled out by the driver, showing 223all the present settings. 224.It Pa MTIOCTOP 225Perform one of the following operations. These operations all have a 226single argument, which is either a boolean, or a signed integer, depending 227on the operation. 228.Bl -tag -width MTSELDNSTY 229.It Pa MTWEOF 230Write N end of file marks at the present head position. 231.It Pa MTFSF 232Skip over N Filemarks. Leave the head on the EOM side of the last skipped 233Filemark. 234.It Pa MTBSF 235Skip BACKWARDS over N Filemarks. Leave the head on the BOM (beginning of media) 236side of the last skipped Filemark. 237.It Pa MTFSR 238Skip forwards over N records. 239.It Pa MTBSR 240Skip backwards over N records. 241.It Pa MTREW 242Rewind the device to the beginning of the media. 243.It Pa MTOFFL 244Rewind the media (and if possible eject). Even if the device cannot 245eject the media it will often no longer respond to normal requests. 246.It Pa MTNOP 247No Op, set status only.. 248.It Pa MTCACHE 249Enable controller Buffering. 250.It Pa MTNOCACHE 251Disable controller Buffering. 252.It Pa MTSETBSIZ 253Set the blocksize to use for the device/mode. If the device is capable of 254variable blocksize operation, and the blocksize is set to 0, then the drive 255will be driven in variable mode. This parameter is in effect for the present 256mount session only, unless set on the control device. 257.It Pa MTSETDNSTY 258Set the Density value (see 259.Xr st 1 260) to use when running in the mode openned (minor bits 2,3). 261This parameter is in effect for the present 262mount session only, unless set on the control device. 263.El 264.It Pa MTIOCIEOT 265?Set END of TAPE processing... not yet supported. 266.It Pa MTIOCEEOT 267?Set END of TAPE processing... not yet supported. 268.El 269.Pp 270In addition, The 271.Nm 272driver will allow the use of any of the general 273.Xr scsi 4 274ioctls, as long as the control device is used. 275 276.Sh FILES 277.Bl -tag -width /dev/[n][e]rst[0-9].[0-3] -compact 278.It Pa /dev/[n][e]rst[0-9].[0-3] 279general form: 280.It Pa /dev/rst0.0 281Mode 0, rewind on close 282.It Pa /dev/nrst0.2 283Mode 2, No rewind on close 284.It Pa /dev/erst0.3 285Mode 3, Eject on close (if capable) 286.It Pa /dev/rst0 287Another name for rst0.0 288.It Pa /dev/nrst0 289Another name for nrst0.0 290.It Pa /dev/st0ctl.0 291Parameters set to this device become the default parameters for [en]rst0.0 292.It Pa /dev/st0ctl.1 293Parameters set to this device become the default parameters for [en]rst0.1 294.It Pa /dev/st0ctl.2 295Parameters set to this device become the default parameters for [en]rst0.2 296.It Pa /dev/st0ctl.3 297Parameters set to this device become the default parameters for [en]rst0.3 298.El 299.Sh DIAGNOSTICS 300None. 301.Sh SEE ALSO 302.Xr mt 1 303.Xr st 1 304.Sh HISTORY 305This 306.Nm 307driver appeared in MACH 2.5 . 308 309