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