1This file contains brief information about the SCSI tape driver. 2The driver is currently maintained by Kai M�kisara (email 3Kai.Makisara@kolumbus.fi) 4 5Last modified: Sun Apr 6 22:44:55 2003 by makisara 6 7 8BASICS 9 10The driver is generic, i.e., it does not contain any code tailored 11to any specific tape drive. The tape parameters can be specified with 12one of the following three methods: 13 141. Each user can specify the tape parameters he/she wants to use 15directly with ioctls. This is administratively a very simple and 16flexible method and applicable to single-user workstations. However, 17in a multiuser environment the next user finds the tape parameters in 18state the previous user left them. 19 202. The system manager (root) can define default values for some tape 21parameters, like block size and density using the MTSETDRVBUFFER ioctl. 22These parameters can be programmed to come into effect either when a 23new tape is loaded into the drive or if writing begins at the 24beginning of the tape. The second method is applicable if the tape 25drive performs auto-detection of the tape format well (like some 26QIC-drives). The result is that any tape can be read, writing can be 27continued using existing format, and the default format is used if 28the tape is rewritten from the beginning (or a new tape is written 29for the first time). The first method is applicable if the drive 30does not perform auto-detection well enough and there is a single 31"sensible" mode for the device. An example is a DAT drive that is 32used only in variable block mode (I don't know if this is sensible 33or not :-). 34 35The user can override the parameters defined by the system 36manager. The changes persist until the defaults again come into 37effect. 38 393. Up to four modes can be defined and selected using the minor number 40(bits 5 and 6). Mode 0 corresponds to the defaults discussed 41above. Additional modes are dormant until they are defined by the 42system manager (root). When specification of a new mode is started, 43the configuration of mode 0 is used to provide a starting point for 44definition of the new mode. 45 46Using the modes allows the system manager to give the users choices 47over some of the buffering parameters not directly accessible to the 48users (buffered and asynchronous writes). The modes also allow choices 49between formats in multi-tape operations (the explicitly overridden 50parameters are reset when a new tape is loaded). 51 52If more than one mode is used, all modes should contain definitions 53for the same set of parameters. 54 55Many Unices contain internal tables that associate different modes to 56supported devices. The Linux SCSI tape driver does not contain such 57tables (and will not do that in future). Instead of that, a utility 58program can be made that fetches the inquiry data sent by the device, 59scans its database, and sets up the modes using the ioctls. Another 60alternative is to make a small script that uses mt to set the defaults 61tailored to the system. 62 63The driver supports fixed and variable block size (within buffer 64limits). Both the auto-rewind (minor equals device number) and 65non-rewind devices (minor is 128 + device number) are implemented. 66 67In variable block mode, the byte count in write() determines the size 68of the physical block on tape. When reading, the drive reads the next 69tape block and returns to the user the data if the read() byte count 70is at least the block size. Otherwise, error ENOMEM is returned. 71 72In fixed block mode, the data transfer between the drive and the 73driver is in multiples of the block size. The write() byte count must 74be a multiple of the block size. This is not required when reading but 75may be advisable for portability. 76 77Support is provided for changing the tape partition and partitioning 78of the tape with one or two partitions. By default support for 79partitioned tape is disabled for each driver and it can be enabled 80with the ioctl MTSETDRVBUFFER. 81 82By default the driver writes one filemark when the device is closed after 83writing and the last operation has been a write. Two filemarks can be 84optionally written. In both cases end of data is signified by 85returning zero bytes for two consecutive reads. 86 87The compile options are defined in the file linux/drivers/scsi/st_options.h. 88 89 90BSD AND SYS V SEMANTICS 91 92The user can choose between these two behaviours of the tape driver by 93defining the value of the symbol ST_SYSV. The semantics differ when a 94file being read is closed. The BSD semantics leaves the tape where it 95currently is whereas the SYS V semantics moves the tape past the next 96filemark unless the filemark has just been crossed. 97 98The default is BSD semantics. 99 100 101BUFFERING 102 103The driver uses tape buffers allocated either at system initialization 104or at run-time when needed. One buffer is used for each open tape 105device. The size of the buffers is selectable at compile and/or boot 106time. The buffers are used to store the data being transferred to/from 107the SCSI adapter. The following buffering options are selectable at 108compile time and/or at run time (via ioctl): 109 110Buffering of data across write calls in fixed block mode (define 111ST_BUFFER_WRITES). 112 113Asynchronous writing. Writing the buffer contents to the tape is 114started and the write call returns immediately. The status is checked 115at the next tape operation. Applies only to variable block mode. 116 117Buffered writes and asynchronous writes may in some rare cases cause 118problems in multivolume operations if there is not enough space on the 119tape after the early-warning mark to flush the driver buffer. 120 121Read ahead for fixed block mode (ST_READ_AHEAD). Filling the buffer is 122attempted even if the user does not want to get all of the data at 123this read command. Should be disabled for those drives that don't like 124a filemark to truncate a read request or that don't like backspacing. 125 126The buffer size is defined (in 1024 byte units) by ST_BUFFER_BLOCKS or 127at boot time. If this size is not large enough, the driver tries to 128temporarily enlarge the buffer. Buffer allocation uses chunks of 129memory having sizes 2^n * (page size). Because of this the actual 130buffer size may be larger than the buffer size specified with 131ST_BUFFER_BLOCKS. 132 133A small number of buffers are allocated at driver initialisation. The 134maximum number of these buffers is defined by ST_MAX_BUFFERS. The 135maximum can be changed with kernel or module startup options. One 136buffer is allocated for each drive detected when the driver is 137initialized up to the maximum. 138 139The driver tries to allocate new buffers at run-time if 140necessary. These buffers are freed after use. If the maximum number of 141initial buffers is set to zero, all buffer allocation is done at 142run-time. The advantage of run-time allocation is that memory is not 143wasted for buffers not being used. The disadvantage is that there may 144not be memory available at the time when a buffer is needed for the 145first time (once a buffer is allocated, it is not released). This risk 146should not be big if the tape drive is connected to a PCI adapter that 147supports scatter/gather (the allocation is not limited to "DMA memory" 148and the buffer can be composed of several fragments). 149 150Scatter/gather buffers (buffers that consist of chunks non-contiguous 151in the physical memory) are used if contiguous buffers can't be 152allocated. To support all SCSI adapters (including those not 153supporting scatter/gather), buffer allocation is using the following 154three kinds of chunks: 1551. The initial segment that is used for all SCSI adapters including 156those not supporting scatter/gather. The size of this buffer will be 157(PAGE_SIZE << ST_FIRST_ORDER) bytes if the system can give a chunk of 158this size (and it is not larger than the buffer size specified by 159ST_BUFFER_BLOCKS). If this size is not available, the driver halves 160the size and tries again until the size of one page. The default 161settings in st_options.h make the driver to try to allocate all of the 162buffer as one chunk. 1632. The scatter/gather segments to fill the specified buffer size are 164allocated so that as many segments as possible are used but the number 165of segments does not exceed ST_FIRST_SG. 1663. The remaining segments between ST_MAX_SG (or the module parameter 167max_sg_segs) and the number of segments used in phases 1 and 2 168are used to extend the buffer at run-time if this is necessary. The 169number of scatter/gather segments allowed for the SCSI adapter is not 170exceeded if it is smaller than the maximum number of scatter/gather 171segments specified. If the maximum number allowed for the SCSI adapter 172is smaller than the number of segments used in phases 1 and 2, 173extending the buffer will always fail. 174 175 176MODULE PARAMETERS 177 178The buffer size, write threshold, and the maximum number of allocated buffers 179are configurable when the driver is loaded as a module. The keywords are: 180 181buffer_kbs=xxx the buffer size in kilobytes is set to xxx 182max_buffers=xxx the maximum number of tape buffer set to xxx 183max_sg_segs=xxx the maximum number of scatter/gather 184 segments 185blocking_open=xxx block in open() if drive not ready, O_NONBLOCK 186 not used, and blocking_open non-zero 187 188Note that if the buffer size is changed but the write threshold is not 189set, the write threshold is set to the new buffer size - 2 kB. 190 191 192BOOT TIME CONFIGURATION 193 194If the driver is compiled into the kernel, the same parameters can be 195also set using, e.g., the LILO command line. The preferred syntax is 196to use the same keywords as when loading the driver as module. If 197several parameters are set, the keyword-value pairs are separated with 198a comma (no spaces allowed). A colon can be used instead of the equal 199mark. The definition is prepended by the string st=. Here is an 200example: 201 202 st=buffer_kbs:64,max_buffers:2 203 204The following syntax used by the old kernel versions is also supported: 205 206 st=aa[,bb[,cc[,dd]]] 207 208where 209 aa is the buffer size in 1024 byte units 210 bb is the write threshold in 1024 byte units (not used any more) 211 cc is the maximum number of tape buffers to allocate (the number of 212 buffers is bounded also by the number of drives detected) 213 dd is the maximum number of scatter/gather segments 214 215 216IOCTLS 217 218The tape is positioned and the drive parameters are set with ioctls 219defined in mtio.h The tape control program 'mt' uses these ioctls. Try 220to find an mt that supports all of the Linux SCSI tape ioctls and 221opens the device for writing if the tape contents will be modified 222(look for a package mt-st* from the Linux ftp sites; the GNU mt does 223not open for writing for, e.g., erase). 224 225The supported ioctls are: 226 227The following use the structure mtop: 228 229MTFSF Space forward over count filemarks. Tape positioned after filemark. 230MTFSFM As above but tape positioned before filemark. 231MTBSF Space backward over count filemarks. Tape positioned before 232 filemark. 233MTBSFM As above but ape positioned after filemark. 234MTFSR Space forward over count records. 235MTBSR Space backward over count records. 236MTFSS Space forward over count setmarks. 237MTBSS Space backward over count setmarks. 238MTWEOF Write count filemarks. 239MTWSM Write count setmarks. 240MTREW Rewind tape. 241MTOFFL Set device off line (often rewind plus eject). 242MTNOP Do nothing except flush the buffers. 243MTRETEN Re-tension tape. 244MTEOM Space to end of recorded data. 245MTERASE Erase tape. 246MTSEEK Seek to tape block count. Uses Tandberg-compatible seek (QFA) 247 for SCSI-1 drives and SCSI-2 seek for SCSI-2 drives. The file and 248 block numbers in the status are not valid after a seek. 249MTSETBLK Set the drive block size. Setting to zero sets the drive into 250 variable block mode (if applicable). 251MTSETDENSITY Sets the drive density code to arg. See drive 252 documentation for available codes. 253MTLOCK and MTUNLOCK Explicitly lock/unlock the tape drive door. 254MTLOAD and MTUNLOAD Explicitly load and unload the tape. If the 255 command argument x is between MT_ST_HPLOADER_OFFSET + 1 and 256 MT_ST_HPLOADER_OFFSET + 6, the number x is used sent to the 257 drive with the command and it selects the tape slot to use of 258 HP C1553A changer. 259MTCOMPRESSION Sets compressing or uncompressing drive mode using the 260 SCSI mode page 15. Note that some drives other methods for 261 control of compression. Some drives (like the Exabytes) use 262 density codes for compression control. Some drives use another 263 mode page but this page has not been implemented in the 264 driver. Some drives without compression capability will accept 265 any compression mode without error. 266MTSETPART Moves the tape to the partition given by the argument at the 267 next tape operation. The block at which the tape is positioned 268 is the block where the tape was previously positioned in the 269 new active partition unless the next tape operation is 270 MTSEEK. In this case the tape is moved directly to the block 271 specified by MTSEEK. MTSETPART is inactive unless 272 MT_ST_CAN_PARTITIONS set. 273MTMKPART Formats the tape with one partition (argument zero) or two 274 partitions (the argument gives in megabytes the size of 275 partition 1 that is physically the first partition of the 276 tape). The drive has to support partitions with size specified 277 by the initiator. Inactive unless MT_ST_CAN_PARTITIONS set. 278MTSETDRVBUFFER 279 Is used for several purposes. The command is obtained from count 280 with mask MT_SET_OPTIONS, the low order bits are used as argument. 281 This command is only allowed for the superuser (root). The 282 subcommands are: 283 0 284 The drive buffer option is set to the argument. Zero means 285 no buffering. 286 MT_ST_BOOLEANS 287 Sets the buffering options. The bits are the new states 288 (enabled/disabled) the following options (in the 289 parenthesis is specified whether the option is global or 290 can be specified differently for each mode): 291 MT_ST_BUFFER_WRITES write buffering (mode) 292 MT_ST_ASYNC_WRITES asynchronous writes (mode) 293 MT_ST_READ_AHEAD read ahead (mode) 294 MT_ST_TWO_FM writing of two filemarks (global) 295 MT_ST_FAST_EOM using the SCSI spacing to EOD (global) 296 MT_ST_AUTO_LOCK automatic locking of the drive door (global) 297 MT_ST_DEF_WRITES the defaults are meant only for writes (mode) 298 MT_ST_CAN_BSR backspacing over more than one records can 299 be used for repositioning the tape (global) 300 MT_ST_NO_BLKLIMS the driver does not ask the block limits 301 from the drive (block size can be changed only to 302 variable) (global) 303 MT_ST_CAN_PARTITIONS enables support for partitioned 304 tapes (global) 305 MT_ST_SCSI2LOGICAL the logical block number is used in 306 the MTSEEK and MTIOCPOS for SCSI-2 drives instead of 307 the device dependent address. It is recommended to set 308 this flag unless there are tapes using the device 309 dependent (from the old times) (global) 310 MT_ST_SYSV sets the SYSV sematics (mode) 311 MT_ST_NOWAIT enables immediate mode (i.e., don't wait for 312 the command to finish) for some commands (e.g., rewind) 313 MT_ST_DEBUGGING debugging (global; debugging must be 314 compiled into the driver) 315 MT_ST_SETBOOLEANS 316 MT_ST_CLEARBOOLEANS 317 Sets or clears the option bits. 318 MT_ST_DEF_BLKSIZE 319 Defines the default block size set automatically. Value 320 0xffffff means that the default is not used any more. 321 MT_ST_DEF_DENSITY 322 MT_ST_DEF_DRVBUFFER 323 Used to set or clear the density (8 bits), and drive buffer 324 state (3 bits). If the value is MT_ST_CLEAR_DEFAULT 325 (0xfffff) the default will not be used any more. Otherwise 326 the lowermost bits of the value contain the new value of 327 the parameter. 328 MT_ST_DEF_COMPRESSION 329 The compression default will not be used if the value of 330 the lowermost byte is 0xff. Otherwise the lowermost bit 331 contains the new default. If the bits 8-15 are set to a 332 non-zero number, and this number is not 0xff, the number is 333 used as the compression algorithm. The value 334 MT_ST_CLEAR_DEFAULT can be used to clear the compression 335 default. 336 MT_ST_SET_TIMEOUT 337 Set the normal timeout in seconds for this device. The 338 default is 900 seconds (15 minutes). The timeout should be 339 long enough for the retries done by the device while 340 reading/writing. 341 MT_ST_SET_LONG_TIMEOUT 342 Set the long timeout that is used for operations that are 343 known to take a long time. The default is 14000 seconds 344 (3.9 hours). For erase this value is further multiplied by 345 eight. 346 MT_ST_SET_CLN 347 Set the cleaning request interpretation parameters using 348 the lowest 24 bits of the argument. The driver can set the 349 generic status bit GMT_CLN if a cleaning request bit pattern 350 is found from the extended sense data. Many drives set one or 351 more bits in the extended sense data when the drive needs 352 cleaning. The bits are device-dependent. The driver is 353 given the number of the sense data byte (the lowest eight 354 bits of the argument; must be >= 18 (values 1 - 17 355 reserved) and <= the maximum requested sense data sixe), 356 a mask to select the relevant bits (the bits 9-16), and the 357 bit pattern (bits 17-23). If the bit pattern is zero, one 358 or more bits under the mask indicate cleaning request. If 359 the pattern is non-zero, the pattern must match the masked 360 sense data byte. 361 362 (The cleaning bit is set if the additional sense code and 363 qualifier 00h 17h are seen regardless of the setting of 364 MT_ST_SET_CLN.) 365 366The following ioctl uses the structure mtpos: 367MTIOCPOS Reads the current position from the drive. Uses 368 Tandberg-compatible QFA for SCSI-1 drives and the SCSI-2 369 command for the SCSI-2 drives. 370 371The following ioctl uses the structure mtget to return the status: 372MTIOCGET Returns some status information. 373 The file number and block number within file are returned. The 374 block is -1 when it can't be determined (e.g., after MTBSF). 375 The drive type is either MTISSCSI1 or MTISSCSI2. 376 The number of recovered errors since the previous status call 377 is stored in the lower word of the field mt_erreg. 378 The current block size and the density code are stored in the field 379 mt_dsreg (shifts for the subfields are MT_ST_BLKSIZE_SHIFT and 380 MT_ST_DENSITY_SHIFT). 381 The GMT_xxx status bits reflect the drive status. GMT_DR_OPEN 382 is set if there is no tape in the drive. GMT_EOD means either 383 end of recorded data or end of tape. GMT_EOT means end of tape. 384 385 386MISCELLANEOUS COMPILE OPTIONS 387 388The recovered write errors are considered fatal if ST_RECOVERED_WRITE_FATAL 389is defined. 390 391By default, open() does not block if the drive is not ready. The 392behaviour can be changed by setting ST_BLOCKING_OPEN to one. The 393behaviour can be changed also with the boot/module option 394blocking_open. The blocking open times out after ST_BLOCK_SECONDS. 395 396The maximum number of tape devices is determined by the define 397ST_MAX_TAPES. If more tapes are detected at driver initialization, the 398maximum is adjusted accordingly. 399 400Immediate return from tape positioning SCSI commands can be enabled by 401defining ST_NOWAIT. If this is defined, the user should take care that 402the next tape operation is not started before the previous one has 403finished. The drives and SCSI adapters should handle this condition 404gracefully, but some drive/adapter combinations are known to hang the 405SCSI bus in this case. 406 407The MTEOM command is by default implemented as spacing over 32767 408filemarks. With this method the file number in the status is 409correct. The user can request using direct spacing to EOD by setting 410ST_FAST_EOM 1 (or using the MT_ST_OPTIONS ioctl). In this case the file 411number will be invalid. 412 413When using read ahead or buffered writes the position within the file 414may not be correct after the file is closed (correct position may 415require backspacing over more than one record). The correct position 416within file can be obtained if ST_IN_FILE_POS is defined at compile 417time or the MT_ST_CAN_BSR bit is set for the drive with an ioctl. 418(The driver always backs over a filemark crossed by read ahead if the 419user does not request data that far.) 420 421 422DEBUGGING HINTS 423 424To enable debugging messages, edit st.c and #define DEBUG 1. As seen 425above, debugging can be switched off with an ioctl if debugging is 426compiled into the driver. The debugging output is not voluminuous. 427 428If the tape seems to hang, I would be very interested to hear where 429the driver is waiting. With the command 'ps -l' you can see the state 430of the process using the tape. If the state is D, the process is 431waiting for something. The field WCHAN tells where the driver is 432waiting. If you have the current System.map in the correct place (in 433/boot for the procps I use) or have updated /etc/psdatabase (for kmem 434ps), ps writes the function name in the WCHAN field. If not, you have 435to look up the function from System.map. 436 437Note also that the timeouts are very long compared to most other 438drivers. This means that the Linux driver may appear hung although the 439real reason is that the tape firmware has got confused. 440