1.. SPDX-License-Identifier: GPL-2.0 2 3==================== 4The SCSI Tape Driver 5==================== 6 7This file contains brief information about the SCSI tape driver. 8The driver is currently maintained by Kai Mäkisara (email 9Kai.Makisara@kolumbus.fi) 10 11Last modified: Tue Feb 9 21:54:16 2016 by kai.makisara 12 13 14Basics 15====== 16 17The driver is generic, i.e., it does not contain any code tailored 18to any specific tape drive. The tape parameters can be specified with 19one of the following three methods: 20 211. Each user can specify the tape parameters he/she wants to use 22directly with ioctls. This is administratively a very simple and 23flexible method and applicable to single-user workstations. However, 24in a multiuser environment the next user finds the tape parameters in 25state the previous user left them. 26 272. The system manager (root) can define default values for some tape 28parameters, like block size and density using the MTSETDRVBUFFER ioctl. 29These parameters can be programmed to come into effect either when a 30new tape is loaded into the drive or if writing begins at the 31beginning of the tape. The second method is applicable if the tape 32drive performs auto-detection of the tape format well (like some 33QIC-drives). The result is that any tape can be read, writing can be 34continued using existing format, and the default format is used if 35the tape is rewritten from the beginning (or a new tape is written 36for the first time). The first method is applicable if the drive 37does not perform auto-detection well enough and there is a single 38"sensible" mode for the device. An example is a DAT drive that is 39used only in variable block mode (I don't know if this is sensible 40or not :-). 41 42The user can override the parameters defined by the system 43manager. The changes persist until the defaults again come into 44effect. 45 463. By default, up to four modes can be defined and selected using the minor 47number (bits 5 and 6). The number of modes can be changed by changing 48ST_NBR_MODE_BITS in st.h. Mode 0 corresponds to the defaults discussed 49above. Additional modes are dormant until they are defined by the 50system manager (root). When specification of a new mode is started, 51the configuration of mode 0 is used to provide a starting point for 52definition of the new mode. 53 54Using the modes allows the system manager to give the users choices 55over some of the buffering parameters not directly accessible to the 56users (buffered and asynchronous writes). The modes also allow choices 57between formats in multi-tape operations (the explicitly overridden 58parameters are reset when a new tape is loaded). 59 60If more than one mode is used, all modes should contain definitions 61for the same set of parameters. 62 63Many Unices contain internal tables that associate different modes to 64supported devices. The Linux SCSI tape driver does not contain such 65tables (and will not do that in future). Instead of that, a utility 66program can be made that fetches the inquiry data sent by the device, 67scans its database, and sets up the modes using the ioctls. Another 68alternative is to make a small script that uses mt to set the defaults 69tailored to the system. 70 71The driver supports fixed and variable block size (within buffer 72limits). Both the auto-rewind (minor equals device number) and 73non-rewind devices (minor is 128 + device number) are implemented. 74 75In variable block mode, the byte count in write() determines the size 76of the physical block on tape. When reading, the drive reads the next 77tape block and returns to the user the data if the read() byte count 78is at least the block size. Otherwise, error ENOMEM is returned. 79 80In fixed block mode, the data transfer between the drive and the 81driver is in multiples of the block size. The write() byte count must 82be a multiple of the block size. This is not required when reading but 83may be advisable for portability. 84 85Support is provided for changing the tape partition and partitioning 86of the tape with one or two partitions. By default support for 87partitioned tape is disabled for each driver and it can be enabled 88with the ioctl MTSETDRVBUFFER. 89 90By default the driver writes one filemark when the device is closed after 91writing and the last operation has been a write. Two filemarks can be 92optionally written. In both cases end of data is signified by 93returning zero bytes for two consecutive reads. 94 95Writing filemarks without the immediate bit set in the SCSI command block acts 96as a synchronization point, i.e., all remaining data form the drive buffers is 97written to tape before the command returns. This makes sure that write errors 98are caught at that point, but this takes time. In some applications, several 99consecutive files must be written fast. The MTWEOFI operation can be used to 100write the filemarks without flushing the drive buffer. Writing filemark at 101close() is always flushing the drive buffers. However, if the previous 102operation is MTWEOFI, close() does not write a filemark. This can be used if 103the program wants to close/open the tape device between files and wants to 104skip waiting. 105 106If rewind, offline, bsf, or seek is done and previous tape operation was 107write, a filemark is written before moving tape. 108 109The compile options are defined in the file linux/drivers/scsi/st_options.h. 110 1114. If the open option O_NONBLOCK is used, open succeeds even if the 112drive is not ready. If O_NONBLOCK is not used, the driver waits for 113the drive to become ready. If this does not happen in ST_BLOCK_SECONDS 114seconds, open fails with the errno value EIO. With O_NONBLOCK the 115device can be opened for writing even if there is a write protected 116tape in the drive (commands trying to write something return error if 117attempted). 118 119 120Minor Numbers 121============= 122 123The tape driver currently supports up to 2^17 drives if 4 modes for 124each drive are used. 125 126The minor numbers consist of the following bit fields:: 127 128 dev_upper non-rew mode dev-lower 129 20 - 8 7 6 5 4 0 130 131The non-rewind bit is always bit 7 (the uppermost bit in the lowermost 132byte). The bits defining the mode are below the non-rewind bit. The 133remaining bits define the tape device number. This numbering is 134backward compatible with the numbering used when the minor number was 135only 8 bits wide. 136 137 138Sysfs Support 139============= 140 141The driver creates the directory /sys/class/scsi_tape and populates it with 142directories corresponding to the existing tape devices. There are autorewind 143and non-rewind entries for each mode. The names are stxy and nstxy, where x 144is the tape number and y a character corresponding to the mode (none, l, m, 145a). For example, the directories for the first tape device are (assuming four 146modes): st0 nst0 st0l nst0l st0m nst0m st0a nst0a. 147 148Each directory contains the entries: default_blksize default_compression 149default_density defined dev device driver. The file 'defined' contains 1 150if the mode is defined and zero if not defined. The files 'default_*' contain 151the defaults set by the user. The value -1 means the default is not set. The 152file 'dev' contains the device numbers corresponding to this device. The links 153'device' and 'driver' point to the SCSI device and driver entries. 154 155Each directory also contains the entry 'options' which shows the currently 156enabled driver and mode options. The value in the file is a bit mask where the 157bit definitions are the same as those used with MTSETDRVBUFFER in setting the 158options. 159 160Each directory contains the entry 'position_lost_in_reset'. If this value is 161one, reading and writing to the device is blocked after device reset. Most 162devices rewind the tape after reset and the writes/read don't access the 163tape position the user expects. 164 165A link named 'tape' is made from the SCSI device directory to the class 166directory corresponding to the mode 0 auto-rewind device (e.g., st0). 167 168 169Sysfs and Statistics for Tape Devices 170===================================== 171 172The st driver maintains statistics for tape drives inside the sysfs filesystem. 173The following method can be used to locate the statistics that are 174available (assuming that sysfs is mounted at /sys): 175 1761. Use opendir(3) on the directory /sys/class/scsi_tape 1772. Use readdir(3) to read the directory contents 1783. Use regcomp(3)/regexec(3) to match directory entries to the extended 179 regular expression "^st[0-9]+$" 1804. Access the statistics from the /sys/class/scsi_tape/<match>/stats 181 directory (where <match> is a directory entry from /sys/class/scsi_tape 182 that matched the extended regular expression) 183 184The reason for using this approach is that all the character devices 185pointing to the same tape drive use the same statistics. That means 186that st0 would have the same statistics as nst0. 187 188The directory contains the following statistics files: 189 1901. in_flight 191 - The number of I/Os currently outstanding to this device. 1922. io_ns 193 - The amount of time spent waiting (in nanoseconds) for all I/O 194 to complete (including read and write). This includes tape movement 195 commands such as seeking between file or set marks and implicit tape 196 movement such as when rewind on close tape devices are used. 1973. other_cnt 198 - The number of I/Os issued to the tape drive other than read or 199 write commands. The time taken to complete these commands uses the 200 following calculation io_ms-read_ms-write_ms. 2014. read_byte_cnt 202 - The number of bytes read from the tape drive. 2035. read_cnt 204 - The number of read requests issued to the tape drive. 2056. read_ns 206 - The amount of time (in nanoseconds) spent waiting for read 207 requests to complete. 2087. write_byte_cnt 209 - The number of bytes written to the tape drive. 2108. write_cnt 211 - The number of write requests issued to the tape drive. 2129. write_ns 213 - The amount of time (in nanoseconds) spent waiting for write 214 requests to complete. 21510. resid_cnt 216 - The number of times during a read or write we found 217 the residual amount to be non-zero. This should mean that a program 218 is issuing a read larger thean the block size on tape. For write 219 not all data made it to tape. 220 221.. Note:: 222 223 The in_flight value is incremented when an I/O starts the I/O 224 itself is not added to the statistics until it completes. 225 226The total of read_cnt, write_cnt, and other_cnt may not total to the same 227value as iodone_cnt at the device level. The tape statistics only count 228I/O issued via the st module. 229 230When read the statistics may not be temporally consistent while I/O is in 231progress. The individual values are read and written to atomically however 232when reading them back via sysfs they may be in the process of being 233updated when starting an I/O or when it is completed. 234 235The value shown in in_flight is incremented before any statstics are 236updated and decremented when an I/O completes after updating statistics. 237The value of in_flight is 0 when there are no I/Os outstanding that are 238issued by the st driver. Tape statistics do not take into account any 239I/O performed via the sg device. 240 241BSD and Sys V Semantics 242======================= 243 244The user can choose between these two behaviours of the tape driver by 245defining the value of the symbol ST_SYSV. The semantics differ when a 246file being read is closed. The BSD semantics leaves the tape where it 247currently is whereas the SYS V semantics moves the tape past the next 248filemark unless the filemark has just been crossed. 249 250The default is BSD semantics. 251 252 253Buffering 254========= 255 256The driver tries to do transfers directly to/from user space. If this 257is not possible, a driver buffer allocated at run-time is used. If 258direct i/o is not possible for the whole transfer, the driver buffer 259is used (i.e., bounce buffers for individual pages are not 260used). Direct i/o can be impossible because of several reasons, e.g.: 261 262- one or more pages are at addresses not reachable by the HBA 263- the number of pages in the transfer exceeds the number of 264 scatter/gather segments permitted by the HBA 265- one or more pages can't be locked into memory (should not happen in 266 any reasonable situation) 267 268The size of the driver buffers is always at least one tape block. In fixed 269block mode, the minimum buffer size is defined (in 1024 byte units) by 270ST_FIXED_BUFFER_BLOCKS. With small block size this allows buffering of 271several blocks and using one SCSI read or write to transfer all of the 272blocks. Buffering of data across write calls in fixed block mode is 273allowed if ST_BUFFER_WRITES is non-zero and direct i/o is not used. 274Buffer allocation uses chunks of memory having sizes 2^n * (page 275size). Because of this the actual buffer size may be larger than the 276minimum allowable buffer size. 277 278NOTE that if direct i/o is used, the small writes are not buffered. This may 279cause a surprise when moving from 2.4. There small writes (e.g., tar without 280-b option) may have had good throughput but this is not true any more with 2812.6. Direct i/o can be turned off to solve this problem but a better solution 282is to use bigger write() byte counts (e.g., tar -b 64). 283 284Asynchronous writing. Writing the buffer contents to the tape is 285started and the write call returns immediately. The status is checked 286at the next tape operation. Asynchronous writes are not done with 287direct i/o and not in fixed block mode. 288 289Buffered writes and asynchronous writes may in some rare cases cause 290problems in multivolume operations if there is not enough space on the 291tape after the early-warning mark to flush the driver buffer. 292 293Read ahead for fixed block mode (ST_READ_AHEAD). Filling the buffer is 294attempted even if the user does not want to get all of the data at 295this read command. Should be disabled for those drives that don't like 296a filemark to truncate a read request or that don't like backspacing. 297 298Scatter/gather buffers (buffers that consist of chunks non-contiguous 299in the physical memory) are used if contiguous buffers can't be 300allocated. To support all SCSI adapters (including those not 301supporting scatter/gather), buffer allocation is using the following 302three kinds of chunks: 303 3041. The initial segment that is used for all SCSI adapters including 305 those not supporting scatter/gather. The size of this buffer will be 306 (PAGE_SIZE << ST_FIRST_ORDER) bytes if the system can give a chunk of 307 this size (and it is not larger than the buffer size specified by 308 ST_BUFFER_BLOCKS). If this size is not available, the driver halves 309 the size and tries again until the size of one page. The default 310 settings in st_options.h make the driver to try to allocate all of the 311 buffer as one chunk. 3122. The scatter/gather segments to fill the specified buffer size are 313 allocated so that as many segments as possible are used but the number 314 of segments does not exceed ST_FIRST_SG. 3153. The remaining segments between ST_MAX_SG (or the module parameter 316 max_sg_segs) and the number of segments used in phases 1 and 2 317 are used to extend the buffer at run-time if this is necessary. The 318 number of scatter/gather segments allowed for the SCSI adapter is not 319 exceeded if it is smaller than the maximum number of scatter/gather 320 segments specified. If the maximum number allowed for the SCSI adapter 321 is smaller than the number of segments used in phases 1 and 2, 322 extending the buffer will always fail. 323 324 325EOM Behaviour When Writing 326========================== 327 328When the end of medium early warning is encountered, the current write 329is finished and the number of bytes is returned. The next write 330returns -1 and errno is set to ENOSPC. To enable writing a trailer, 331the next write is allowed to proceed and, if successful, the number of 332bytes is returned. After this, -1 and the number of bytes are 333alternately returned until the physical end of medium (or some other 334error) is encountered. 335 336Module Parameters 337================= 338 339The buffer size, write threshold, and the maximum number of allocated buffers 340are configurable when the driver is loaded as a module. The keywords are: 341 342========================== =========================================== 343buffer_kbs=xxx the buffer size for fixed block mode is set 344 to xxx kilobytes 345write_threshold_kbs=xxx the write threshold in kilobytes set to xxx 346max_sg_segs=xxx the maximum number of scatter/gather 347 segments 348try_direct_io=x try direct transfer between user buffer and 349 tape drive if this is non-zero 350========================== =========================================== 351 352Note that if the buffer size is changed but the write threshold is not 353set, the write threshold is set to the new buffer size - 2 kB. 354 355 356Boot Time Configuration 357======================= 358 359If the driver is compiled into the kernel, the same parameters can be 360also set using, e.g., the LILO command line. The preferred syntax is 361to use the same keyword used when loading as module but prepended 362with 'st.'. For instance, to set the maximum number of scatter/gather 363segments, the parameter 'st.max_sg_segs=xx' should be used (xx is the 364number of scatter/gather segments). 365 366For compatibility, the old syntax from early 2.5 and 2.4 kernel 367versions is supported. The same keywords can be used as when loading 368the driver as module. If several parameters are set, the keyword-value 369pairs are separated with a comma (no spaces allowed). A colon can be 370used instead of the equal mark. The definition is prepended by the 371string st=. Here is an example:: 372 373 st=buffer_kbs:64,write_threshold_kbs:60 374 375The following syntax used by the old kernel versions is also supported:: 376 377 st=aa[,bb[,dd]] 378 379where: 380 381 - aa is the buffer size for fixed block mode in 1024 byte units 382 - bb is the write threshold in 1024 byte units 383 - dd is the maximum number of scatter/gather segments 384 385 386IOCTLs 387====== 388 389The tape is positioned and the drive parameters are set with ioctls 390defined in mtio.h The tape control program 'mt' uses these ioctls. Try 391to find an mt that supports all of the Linux SCSI tape ioctls and 392opens the device for writing if the tape contents will be modified 393(look for a package mt-st* from the Linux ftp sites; the GNU mt does 394not open for writing for, e.g., erase). 395 396The supported ioctls are: 397 398The following use the structure mtop: 399 400MTFSF 401 Space forward over count filemarks. Tape positioned after filemark. 402MTFSFM 403 As above but tape positioned before filemark. 404MTBSF 405 Space backward over count filemarks. Tape positioned before 406 filemark. 407MTBSFM 408 As above but ape positioned after filemark. 409MTFSR 410 Space forward over count records. 411MTBSR 412 Space backward over count records. 413MTFSS 414 Space forward over count setmarks. 415MTBSS 416 Space backward over count setmarks. 417MTWEOF 418 Write count filemarks. 419MTWEOFI 420 Write count filemarks with immediate bit set (i.e., does not 421 wait until data is on tape) 422MTWSM 423 Write count setmarks. 424MTREW 425 Rewind tape. 426MTOFFL 427 Set device off line (often rewind plus eject). 428MTNOP 429 Do nothing except flush the buffers. 430MTRETEN 431 Re-tension tape. 432MTEOM 433 Space to end of recorded data. 434MTERASE 435 Erase tape. If the argument is zero, the short erase command 436 is used. The long erase command is used with all other values 437 of the argument. 438MTSEEK 439 Seek to tape block count. Uses Tandberg-compatible seek (QFA) 440 for SCSI-1 drives and SCSI-2 seek for SCSI-2 drives. The file and 441 block numbers in the status are not valid after a seek. 442MTSETBLK 443 Set the drive block size. Setting to zero sets the drive into 444 variable block mode (if applicable). 445MTSETDENSITY 446 Sets the drive density code to arg. See drive 447 documentation for available codes. 448MTLOCK and MTUNLOCK 449 Explicitly lock/unlock the tape drive door. 450MTLOAD and MTUNLOAD 451 Explicitly load and unload the tape. If the 452 command argument x is between MT_ST_HPLOADER_OFFSET + 1 and 453 MT_ST_HPLOADER_OFFSET + 6, the number x is used sent to the 454 drive with the command and it selects the tape slot to use of 455 HP C1553A changer. 456MTCOMPRESSION 457 Sets compressing or uncompressing drive mode using the 458 SCSI mode page 15. Note that some drives other methods for 459 control of compression. Some drives (like the Exabytes) use 460 density codes for compression control. Some drives use another 461 mode page but this page has not been implemented in the 462 driver. Some drives without compression capability will accept 463 any compression mode without error. 464MTSETPART 465 Moves the tape to the partition given by the argument at the 466 next tape operation. The block at which the tape is positioned 467 is the block where the tape was previously positioned in the 468 new active partition unless the next tape operation is 469 MTSEEK. In this case the tape is moved directly to the block 470 specified by MTSEEK. MTSETPART is inactive unless 471 MT_ST_CAN_PARTITIONS set. 472MTMKPART 473 Formats the tape with one partition (argument zero) or two 474 partitions (argument non-zero). If the argument is positive, 475 it specifies the size of partition 1 in megabytes. For DDS 476 drives and several early drives this is the physically first 477 partition of the tape. If the argument is negative, its absolute 478 value specifies the size of partition 0 in megabytes. This is 479 the physically first partition of many later drives, like the 480 LTO drives from LTO-5 upwards. The drive has to support partitions 481 with size specified by the initiator. Inactive unless 482 MT_ST_CAN_PARTITIONS set. 483MTSETDRVBUFFER 484 Is used for several purposes. The command is obtained from count 485 with mask MT_SET_OPTIONS, the low order bits are used as argument. 486 This command is only allowed for the superuser (root). The 487 subcommands are: 488 489 * 0 490 The drive buffer option is set to the argument. Zero means 491 no buffering. 492 * MT_ST_BOOLEANS 493 Sets the buffering options. The bits are the new states 494 (enabled/disabled) the following options (in the 495 parenthesis is specified whether the option is global or 496 can be specified differently for each mode): 497 498 MT_ST_BUFFER_WRITES 499 write buffering (mode) 500 MT_ST_ASYNC_WRITES 501 asynchronous writes (mode) 502 MT_ST_READ_AHEAD 503 read ahead (mode) 504 MT_ST_TWO_FM 505 writing of two filemarks (global) 506 MT_ST_FAST_EOM 507 using the SCSI spacing to EOD (global) 508 MT_ST_AUTO_LOCK 509 automatic locking of the drive door (global) 510 MT_ST_DEF_WRITES 511 the defaults are meant only for writes (mode) 512 MT_ST_CAN_BSR 513 backspacing over more than one records can 514 be used for repositioning the tape (global) 515 MT_ST_NO_BLKLIMS 516 the driver does not ask the block limits 517 from the drive (block size can be changed only to 518 variable) (global) 519 MT_ST_CAN_PARTITIONS 520 enables support for partitioned 521 tapes (global) 522 MT_ST_SCSI2LOGICAL 523 the logical block number is used in 524 the MTSEEK and MTIOCPOS for SCSI-2 drives instead of 525 the device dependent address. It is recommended to set 526 this flag unless there are tapes using the device 527 dependent (from the old times) (global) 528 MT_ST_SYSV 529 sets the SYSV semantics (mode) 530 MT_ST_NOWAIT 531 enables immediate mode (i.e., don't wait for 532 the command to finish) for some commands (e.g., rewind) 533 MT_ST_NOWAIT_EOF 534 enables immediate filemark mode (i.e. when 535 writing a filemark, don't wait for it to complete). Please 536 see the BASICS note about MTWEOFI with respect to the 537 possible dangers of writing immediate filemarks. 538 MT_ST_SILI 539 enables setting the SILI bit in SCSI commands when 540 reading in variable block mode to enhance performance when 541 reading blocks shorter than the byte count; set this only 542 if you are sure that the drive supports SILI and the HBA 543 correctly returns transfer residuals 544 MT_ST_DEBUGGING 545 debugging (global; debugging must be 546 compiled into the driver) 547 548 * MT_ST_SETBOOLEANS, MT_ST_CLEARBOOLEANS 549 Sets or clears the option bits. 550 * MT_ST_WRITE_THRESHOLD 551 Sets the write threshold for this device to kilobytes 552 specified by the lowest bits. 553 * MT_ST_DEF_BLKSIZE 554 Defines the default block size set automatically. Value 555 0xffffff means that the default is not used any more. 556 * MT_ST_DEF_DENSITY, MT_ST_DEF_DRVBUFFER 557 Used to set or clear the density (8 bits), and drive buffer 558 state (3 bits). If the value is MT_ST_CLEAR_DEFAULT 559 (0xfffff) the default will not be used any more. Otherwise 560 the lowermost bits of the value contain the new value of 561 the parameter. 562 * MT_ST_DEF_COMPRESSION 563 The compression default will not be used if the value of 564 the lowermost byte is 0xff. Otherwise the lowermost bit 565 contains the new default. If the bits 8-15 are set to a 566 non-zero number, and this number is not 0xff, the number is 567 used as the compression algorithm. The value 568 MT_ST_CLEAR_DEFAULT can be used to clear the compression 569 default. 570 * MT_ST_SET_TIMEOUT 571 Set the normal timeout in seconds for this device. The 572 default is 900 seconds (15 minutes). The timeout should be 573 long enough for the retries done by the device while 574 reading/writing. 575 * MT_ST_SET_LONG_TIMEOUT 576 Set the long timeout that is used for operations that are 577 known to take a long time. The default is 14000 seconds 578 (3.9 hours). For erase this value is further multiplied by 579 eight. 580 * MT_ST_SET_CLN 581 Set the cleaning request interpretation parameters using 582 the lowest 24 bits of the argument. The driver can set the 583 generic status bit GMT_CLN if a cleaning request bit pattern 584 is found from the extended sense data. Many drives set one or 585 more bits in the extended sense data when the drive needs 586 cleaning. The bits are device-dependent. The driver is 587 given the number of the sense data byte (the lowest eight 588 bits of the argument; must be >= 18 (values 1 - 17 589 reserved) and <= the maximum requested sense data sixe), 590 a mask to select the relevant bits (the bits 9-16), and the 591 bit pattern (bits 17-23). If the bit pattern is zero, one 592 or more bits under the mask indicate cleaning request. If 593 the pattern is non-zero, the pattern must match the masked 594 sense data byte. 595 596 (The cleaning bit is set if the additional sense code and 597 qualifier 00h 17h are seen regardless of the setting of 598 MT_ST_SET_CLN.) 599 600The following ioctl uses the structure mtpos: 601 602MTIOCPOS 603 Reads the current position from the drive. Uses 604 Tandberg-compatible QFA for SCSI-1 drives and the SCSI-2 605 command for the SCSI-2 drives. 606 607The following ioctl uses the structure mtget to return the status: 608 609MTIOCGET 610 Returns some status information. 611 The file number and block number within file are returned. The 612 block is -1 when it can't be determined (e.g., after MTBSF). 613 The drive type is either MTISSCSI1 or MTISSCSI2. 614 The number of recovered errors since the previous status call 615 is stored in the lower word of the field mt_erreg. 616 The current block size and the density code are stored in the field 617 mt_dsreg (shifts for the subfields are MT_ST_BLKSIZE_SHIFT and 618 MT_ST_DENSITY_SHIFT). 619 The GMT_xxx status bits reflect the drive status. GMT_DR_OPEN 620 is set if there is no tape in the drive. GMT_EOD means either 621 end of recorded data or end of tape. GMT_EOT means end of tape. 622 623 624Miscellaneous Compile Options 625============================= 626 627The recovered write errors are considered fatal if ST_RECOVERED_WRITE_FATAL 628is defined. 629 630The maximum number of tape devices is determined by the define 631ST_MAX_TAPES. If more tapes are detected at driver initialization, the 632maximum is adjusted accordingly. 633 634Immediate return from tape positioning SCSI commands can be enabled by 635defining ST_NOWAIT. If this is defined, the user should take care that 636the next tape operation is not started before the previous one has 637finished. The drives and SCSI adapters should handle this condition 638gracefully, but some drive/adapter combinations are known to hang the 639SCSI bus in this case. 640 641The MTEOM command is by default implemented as spacing over 32767 642filemarks. With this method the file number in the status is 643correct. The user can request using direct spacing to EOD by setting 644ST_FAST_EOM 1 (or using the MT_ST_OPTIONS ioctl). In this case the file 645number will be invalid. 646 647When using read ahead or buffered writes the position within the file 648may not be correct after the file is closed (correct position may 649require backspacing over more than one record). The correct position 650within file can be obtained if ST_IN_FILE_POS is defined at compile 651time or the MT_ST_CAN_BSR bit is set for the drive with an ioctl. 652(The driver always backs over a filemark crossed by read ahead if the 653user does not request data that far.) 654 655 656Debugging Hints 657=============== 658 659Debugging code is now compiled in by default but debugging is turned off 660with the kernel module parameter debug_flag defaulting to 0. Debugging 661can still be switched on and off with an ioctl. To enable debug at 662module load time add debug_flag=1 to the module load options, the 663debugging output is not voluminous. Debugging can also be enabled 664and disabled by writing a '0' (disable) or '1' (enable) to the sysfs 665file /sys/bus/scsi/drivers/st/debug_flag. 666 667If the tape seems to hang, I would be very interested to hear where 668the driver is waiting. With the command 'ps -l' you can see the state 669of the process using the tape. If the state is D, the process is 670waiting for something. The field WCHAN tells where the driver is 671waiting. If you have the current System.map in the correct place (in 672/boot for the procps I use) or have updated /etc/psdatabase (for kmem 673ps), ps writes the function name in the WCHAN field. If not, you have 674to look up the function from System.map. 675 676Note also that the timeouts are very long compared to most other 677drivers. This means that the Linux driver may appear hung although the 678real reason is that the tape firmware has got confused. 679