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