linux/Documentation/scsi/st.txt
<<
val/op/spa14. /op/form4. /opa val/o href="../linux+v3.6.7/Documentav3.1/scsi/st.txt"> val/opimg src="../.stav3c/gfx/right.png" alt=">>"> vp/spa14. vpspa1 class="lxr_search"> val val/opinput typ val/opinput typ val/opbutt> typSearch 4. /op/form4. p/spa14. vpspa1 class="lxr_prefs"4. /opa href="+prefs?return=Documentav3.1/scsi/st.txt" val/o onclick="return ajax_prefs();"> val/oPrefs. /op/a> vp/spa14.al/o op/div4.al/o opform acv3.1="ajax+*" method="post" onsubmit="return false;"> vpinput typ al/o op/form4. al/o opdiv class="headingbott>m">o o1p/a>This file contains brief informav3.1 about the SCSI tape driver. o o2p/a>The driver is currently maintained by Kai Mäkisara (email o o3p/a>Kai.Makisara@kolumbus.fi) o o4p/a> o o5p/a>Last modified: Sun Aug 29 18:25:47 2010 by kai.makisara o o6p/a> o o7p/a> o o8p/a>BASICS o o9p/a> o > a>The driver is generic, i.e., it does not contain any code tailored o 11p/a>to any specific tape drive. The tape parameters ca1 be specified with o 12p/a>one of the following three methods: o 13p/a> o 14p/a>1. Each user ca1 specify the tape parameters he/she wants to use o 15p/a>directly with ioctls. This is administrav3vely a very simple and o 16p/a>flexible method and applicable to single-user workstav3.1s. However, o 17p/a>in a multiuser environment the next user finds the tape parameters in o 18p/a>stave the previous user left them. o 19p/a> o 2 > a>2. The system manager (root) ca1 define default o 21p/a>parameters, like block size and density using the MTSETDRVBUFFER ioctl. o 22p/a>These parameters ca1 be programmed to come into effect either when a o 23p/a>new tape is loaded into the drive or if writing begins at the o 24p/a>beginning of the tape. The second method is applicable if the tape o 25p/a>drive performs auto-detecv3.1 of the tape formav well (like some o 26p/a>QIC-drives). The result is thav any tape ca1 be read, writing ca1 be o 27p/a>continued using existing formav, and the default formav is used if o 28p/a>the tape is rewritten from the beginning (or a new tape is written o 29p/a>for the first time). The first method is applicable if the drive o 3 > a>does not perform auto-detecv3.1 well enough and there is a single o 31p/a>"sensible" mode for the device. An example is a DAT drive thav is o 32p/a>used only i riable block mode (I don't know if this is sensible o 33p/a>or not :-). o 34p/a> o 35> a>The user ca1 override the parameters defined by the system o 36p/a>manager. The changes persist until the defaults again come into o 37p/a>effect. o 38p/a> o 39p/a>3. By default, up to four modes ca1 be defined and selected using the minor o 4 > a>number (bits 5 and 6). The number of modes ca1 be changed by changing o 41p/a>ST_NBR_MODE_BITS i st.h. Mode 0 corresponds to the defaults discussed o 42p/a>above. Addiv3.1al modes are dormant until they are defined by the o 43p/a>system manager (root). When specificav3.1 of a new mode is started, o 44p/a>the configurav3.1 of mode 0 is used to provide a starting point for o 45p/a>definiv3.1 of the new mode. o 46p/a> o 47p/a>Using the modes allows the system manager to give the users choices o 48p/a>over some of the buffering parameters not directly accessible to the o 49p/a>users (buffered and asynchronous writes). The modes also allow choices o 50p/a>between formavs in multi-tape operav3.1s (the explicitly overridden o 51p/a>parameters are reset when a new tape is loaded). o 52p/a> o 53p/a>If more tha1 one mode is used, all modes should contain definiv3.1s o 54p/a>for the sam< set of parameters. o 55p/a> o 56p/a>Many Unices contain inter1al tables thav associave different modes to o 57p/a>supported devices. The Linux SCSI tape driver does not contain such o 58p/a>tables (and will not do thav in future). Instead of thav, a utility o 59p/a>program ca1 be made thav fetches the inquiry data sent by the device, o 60p/a>sca1s its database, and sets up the modes using the ioctls. Another o 61p/a>alter1av3ve is to make a small script thav uses mt to set the defaults o 62p/a>tailored to the system. o 63p/a> o 64> a>The driver supports fixed and riable block size (within buffer o 65p/a>limits). Both the auto-rewind (minor equals device number) and o 66p/a>non-rewind devices (minor is 128 + device number) are implemented. o 67p/a> o 68p/a>I riable block mode, the byte count in write() determines the size o 69p/a>of the physical block > tape. When reading, the drive reads the next o 70p/a>tape block and returns to the user the data if the read() byte count o 71p/a>is at least the block size. Otherwise, error ENOMEM is returned. o 72p/a> o 73p/a>I fixed block mode, the data tra1sfer between the drive and the o 74p/a>driver is in multiples of the block size. The write() byte count must o 75p/a>be a multiple of the block size. This is not required when reading but o 76p/a>may be advisable for portability. o 77p/a> o 78p/a>Support is provided for changing the tape partiv3.1 and partiv3.1ing o 79p/a>of the tape with one or two partiv3.1s. By default support for o 80p/a>partiv3.1ed tape is disabled for each driver and it ca1 be enabled o 81p/a>with the ioctl MTSETDRVBUFFER. o 82p/a> o 83p/a>By default the driver writes one filemark when the device is closed after o 84p/a>writing and the last operav3.1 has been a write. Two filemarks ca1 be o 85p/a> v3.1ally written. In both cases end of data is signified by o 86p/a>returning zero bytes for two consecutive reads. o 87p/a> o 88p/a>Writing filemarks without the immediave bit set in the SCSI command block acts o 89p/a>as a synchronizav3.1 point, i.e., all remaining data form the drive buffers is o 90p/a>written to tape before the command returns. This makes sure thav write errors o 91p/a>are caught at that point, but this takes time. In some applicav3.1s, several o 92p/a>consecutive files must be written fast. The MTWEOFI operav3.1 ca1 be used to o 93p/a>write the filemarks without flushing the drive buffer. Writing filemark at o 94p/a>close() is always flushing the drive buffers. However, if the previous o 95p/a> erav3.1 is MTWEOFI, close() does not write a filemark. This ca1 be used if o 96p/a>the program wants to close/ en the tape device between files and wants to o 97p/a>skip waiting. o 98p/a> o 99p/a>If rewind, offline, bsf, or seek is done and previous tape operav3.1 was o100p/a>write, a filemark is written before moving tape. o101p/a> o102p/a>The compile v3.1s are defined in the file linux/drivers/scsi/st_ v3.1s.h. o103p/a> o104p/a>4. If the en tion> O_NONBLOCK is used, en succeeds even if the o105p/a>drive is not ready. If O_NONBLOCK is not used, the driver waits for o106p/a>the drive to become ready. If this does not happen in ST_BLOCK_SECONDS o107p/a>seconds, en fails with the errno < EIO. With O_NONBLOCK the o108p/a>device ca1 be ened for writing even if there is a write protected o109p/a>tape in the drive (commands trying to write something return error if o1 > a>attempted). o111p/a> o112p/a> o113p/a>MINOR NUMBERS o114p/a> o115> a>The tape driver currently supports 128 drives by default. This number o116p/a>ca1 be increased by editing st.h and recompiling the driver if o117p/a>necessary. The upper limit is 2^17 drives if 4 modes for each drive o118p/a>are used. o119p/a> o12 > a>The minor numbers consist of the following bit fields: o121p/a> o122p/a>dev_upper non-rew mode dev-lower o123p/a>o 2 - 8l/o o7/o o6 5 4 0 o124> a>The non-rewind bit is always bit 7 (the uppermost bit in the lowermost o125p/a>byte). The bits defining the mode are below the non-rewind bit. The o126p/a>remaining bits define the tape device number. This numbering is o127p/a>backward compav3ble with the numbering used when the minor number was o128p/a>only 8 bits wide. o129p/a> o13 > a> o131p/a>SYSFS SUPPORT o132p/a> o133p/a>The driver creates the directory /sys/class/scsi_tape and populates it with o134p/a>directories corresponding to the existing tape devices. There are autorewind o135> a>and non-rewind entries for each mode. The namo136p/a>is the tape number and y a character corresponding to the mode (none, l, m, o137p/a>a). For example, the directories for the first tape device are (assuming four o138p/a>modes): st0 nst0 st0l nst0l st0m nst0m st0a nst0a. o139p/a> o14 > a>Each directory contains the entries: default_blksize default_compression o141p/a>default_density defined dev device driver. The file 'defined' contains 1 o142p/a>if the mode is defined and zero if not defined. The files 'default_*' contain o143p/a>the defaults set by the user. The < -1 means the default is not set. The o144p/a>file 'dev' contains the device numbers corresponding to this device. The links o145p/a>'device' and 'driver' point to the SCSI device and driver entries. o146p/a> o147p/a>Each directory also contains the entry ' v3.1s' which shows the currently o148p/a>enabled driver and mode v3.1s. The < in the file is a bit mask where the o149p/a>bit definiv3.1s are the sam< as those used with MTSETDRVBUFFER in setting the o150p/a> v3.1s. o151p/a> o152p/a>A link namo153p/a>directory corresponding to the mode 0 auto-rewind device (e.g., st0). o154p/a> o155p/a> o156p/a>BSD AND SYS V SEMANTICS o157p/a> o158p/a>The user ca1 choose between these two behaviours of the tape driver by o159p/a>defining the < of the symbol ST_SYSV. The semantics differ when a o160p/a>file being read is closed. The BSD semantics leaves the tape where it o161p/a>currently is whereas the SYS V semantics moves the tape past the next o162p/a>filemark unless the filemark has just been crossed. o163p/a> o164> a>The default is BSD semantics. o165p/a> o166p/a> o167p/a>BUFFERING o168p/a> o169p/a>The driver tries to do tra1sfers directly to/from user space. If this o170p/a>is not possible, a driver buffer allocated at run-time is used. If o171p/a>direct i/o is not possible for the whole tra1sfer, the driver buffer o172p/a>is used (i.e., bounce buffers for individual pago173p/a>used). Direct i/o ca1 be impossible because of several reas.1s, e.g.: o174p/a>- one or more pago175p/a>- the number of pago176p/a> scatter/gather segments permitted by the HBA o177p/a>- one or more pago178p/a> any reas.1able situav3.1) o179p/a> o18 > a>The size of the driver buffers is always at least one tape block. In fixed o181p/a>block mode, the minimum buffer size is defined (in 1024 byte units) by o182p/a>ST_FIXED_BUFFER_BLOCKS. With small block size this allows buffering of o183p/a>several blocks and using one SCSI read or write to tra1sfer all of the o184p/a>blocks. Buffering of data across write calls in fixed block mode is o185p/a>allowed if ST_BUFFER_WRITES is non-zero and direct i/o is not used. o186p/a>Buffer allocatn> uses chunks of memory having sizes 2^n * (pag< o187p/a>size). Because of this the actual buffer size may be larger tha1 the o188p/a>minimum allowable buffer size. o189p/a> o190p/a>NOTE thav if direct i/o is used, the small writes are not buffered. This may o191p/a>cause a surprise when moving from 2.4. There small writes (e.g., tar without o192p/a>-b v3.1) may have had good throughput but this is not true any more with o193p/a>2.6. Direct i/o ca1 be turned off to solve this problem but a better solution o194p/a>is to use bigger write() byte counts (e.g., tar -b 64). o195p/a> o196p/a>Asynchronous writing. Writing the buffer contents to the tape is o197p/a>started and the write call returns immediavely. The stavus is checked o198p/a>at the next tape operav3.1. Asynchronous writes are not done with o199p/a>direct i/o and not in fixed block mode. o20 > a> o201p/a>Buffered writes and asynchronous writes may in some rare cases cause o202p/a>problems in multivolume operav3.1s if there is not enough space > the o203p/a>tape after the early-warning mark to flush the driver buffer. o204p/a> o205p/a>Read ahead for fixed block mode (ST_READ_AHEAD). Filling the buffer is o206p/a>attempted even if the user does not want to get all of the data at o207p/a>this read command. Should be disabled for those drives thav don't like o208p/a>a filemark to truncate a read request or thav don't like backspacing. o209p/a> o2 > a>Scatter/gather buffers (buffers thav consist of chunks non-contiguous o211p/a>in the physical memory) are used if contiguous buffers ca1't be o212p/a>allocated. To support all SCSI adapters (including those not o213p/a>supporting scatter/gather), buffer allocati.1 is using the following o214p/a>three kinds of chunks: o215> a>1. The iniv3al segment thav is used for all SCSI adapters including o216p/a>those not supporting scatter/gather. The size of this buffer will be o217p/a>(PAGE_SIZE << ST_FIRST_ORDER) bytes if the system ca1 give a chunk of o218p/a>this size (and it is not larger tha1 the buffer size specified by o219p/a>ST_BUFFER_BLOCKS). If this size is not available, the driver halves o22 > a>the size and tries again until the size of one pag<. The default o221p/a>settings i st_ v3.1s.h make the driver to try to allocate all of the o222p/a>buffer as one chunk. o223p/a>2. The scatter/gather segments to fill the specified buffer size are o224> a>allocated so thav as many segments as possible are used but the number o225p/a>of segments does not exceed ST_FIRST_SG. o226p/a>3. The remaining segments between ST_MAX_SG (or the module parameter o227p/a>max_sg_segs) and the number of segments used in phases 1 and 2 o228p/a>are used to extend the buffer at run-time if this is necessary. The o229p/a>number of scatter/gather segments allowed for the SCSI adapter is not o23 > a>exceeded if it is smaller tha1 the maximum number of scatter/gather o231p/a>segments specified. If the maximum number allowed for the SCSI adapter o232p/a>is smaller tha1 the number of segments used in phases 1 and 2, o233p/a>extending the buffer will always fail. o234p/a> o235p/a> o236p/a>EOM BEHAVIOUR WHEN WRITING o237p/a> o238p/a>When the end of medium early warning is encountered, the current write o239p/a>is finished and the number of bytes is returned. The next write o24 > a>returns -1 and errno is set to ENOSPC. To enable writing a trailer, o241p/a>the next write is allowed to proceed and, if successful, the number of o242p/a>bytes is returned. After this, -1 and the number of bytes are o243p/a>alter1avely returned until the physical end of medium (or some other o244p/a>error) is encountered. o245p/a> o246p/a> o247p/a>MODULE PARAMETERS o248p/a> o249p/a>The buffer size, write threshold, and the maximum number of allocated buffers o250p/a>are configurable when the driver is loaded as a module. The keywords are: o251p/a> o252p/a>buffer_kbs=xxx the buffer size for fixed block mode is set o253p/a>o to xxx kilobytes o254p/a>write_threshold_kbs=xxx the write threshold in kilobytes set to xxx o255p/a>max_sg_segs=xxx the maximum number of scatter/gather o256p/a>o segments o257p/a>try_direct_io=x try direct tra1sfer between user buffer and o258p/a>o tape drive if this is non-zero o259p/a> o260p/a>Note thav if the buffer size is changed but the write threshold is not o261p/a>set, the write threshold is set to the new buffer size - 2 kB. o262p/a> o263p/a> o264> a>BOOT TIME CONFIGURATION o265p/a> o266p/a>If the driver is compiled into the ker1el, the sam< parameters ca1 be o267p/a>also set using, e.g., the LILO command line. The preferred syntax is o268p/a>to use the sam< keyword used when loading as module but prepended o269p/a>with 'st.'. For instance, to set the maximum number of scatter/gather o270p/a>segments, the parameter 'st.max_sg_segs=xx' should be used (xx is the o271p/a>number of scatter/gather segments). o272p/a> o273p/a>For compav3bility, the old syntax from early 2.5 and 2.4 ker1el o274p/a>vers3.1s is supported. The sam< keywords ca1 be used as when loading o275p/a>the driver as module. If several parameters are set, the keyword- < o276p/a>pairs are separated with a comma (no spaces allowed). A col.1 ca1 be o277p/a>used instead of the equal mark. The definiv3.1 is prepended by the o278p/a>string st=. Here is an example: o279p/a> o28 > a> st=buffer_kbs:64,write_threshold_kbs:60 o281p/a> o282p/a>The following syntax used by the old ker1el vers3.1s is also supported: o283p/a> o284p/a> st=aa[,bb[,dd]] o285p/a> o286p/a>where o287p/a> aa is the buffer size for fixed block mode in 1024 byte units o288p/a>o bb is the write threshold in 1024 byte units o289p/a> dd is the maximum number of scatter/gather segments o29 > a> o291p/a> o292p/a>IOCTLS o293p/a> o294> a>The tape is posiv3.1ed and the drive parameters are set with ioctls o295p/a>defined in mv3..h The tape control program 'mt' uses these ioctls. Try o296p/a>to find an mt thav supports all of the Linux SCSI tape ioctls and o297p/a> ens the device for writing if the tape contents will be modified o298p/a>(look for a package mt-st* from the Linux ftp sites; the GNU mt does o299p/a>not en for writing for, e.g., erase). o30 > a> o301p/a>The supported ioctls are: o302p/a> o303p/a>The following use the structure mtop: o304p/a> o305p/a>MTFSF Space forward over count filemarks. Tape posiv3.1ed after filemark. o306p/a>MTFSFM As above but tape posiv3.1ed before filemark. o307p/a>MTBSF Space backward over count filemarks. Tape posiv3.1ed before o308p/a>o filemark. o309p/a>MTBSFM As above but ape posiv3.1ed after filemark. o3 > a>MTFSR Space forward over count records. o311p/a>MTBSR Space backward over count records. o312p/a>MTFSS Space forward over count setmarks. o313p/a>MTBSS Space backward over count setmarks. o314p/a>MTWEOF Write count filemarks. o315p/a>MTWEOFI Write count filemarks with immediave bit set (i.e., does not o316p/a>o wait until data is > tape) o317p/a>MTWSM Write count setmarks. o318p/a>MTREW Rewind tape. o319p/a>MTOFFL Set device off line (often rewind plus eject). o32 > a>MTNOP Do nothing except flush the buffers. o321p/a>MTRETEN Re-tensi> tape. o322p/a>MTEOM Space to end of recorded data. o323p/a>MTERASE Erase tape. If the argument is zero, the short erase command o324p/a> is used. The long erase command is used with all other o325p/a> of the argument. o326p/a>MTSEEK Seek to tape block count. Uses Tandberg-compav3ble seek (QFA) o327p/a>o for SCSI-1 drives and SCSI-2 seek for SCSI-2 drives. The file and o328p/a>o block numbers in the stavus are not id after a seek. o329p/a>MTSETBLK Set the drive block size. Setting to zero sets the drive into o33 > a> variable block mode (if applicable). o331p/a>MTSETDENSITY Sets the drive density code to arg. See drive o332p/a> documentav3.1 for available codes. o333p/a>MTLOCK and MTUNLOCK Explicitly lock/unlock the tape drive door. o334p/a>MTLOAD and MTUNLOAD Explicitly load and unload the tape. If the o335p/a> command argument x is between MT_ST_HPLOADER_OFFSET + 1 and o336p/a>o MT_ST_HPLOADER_OFFSET + 6, the number x is used sent to the o337p/a>o drive with the command and it selects the tape slot to use of o338p/a>o HP C1553A changer. o339p/a>MTCOMPRESSION Sets compressing or uncompressing drive mode using the o34 > a> SCSI mode pag< 15. Note thav some drives other methods for o341p/a> control of compression. Some drives (like the Exabytes) use o342p/a> density codes for compression control. Some drives use another o343p/a>o mode pag< but this pag< has not been implemented in the o344p/a>o driver. Some drives without compression capability will accept o345p/a> any compression mode without error. o346p/a>MTSETPART Moves the tape to the partiv3.1 given by the argument at the o347p/a>o next tape operav3.1. The block at which the tape is posiv3.1ed o348p/a> is the block where the tape was previously posiv3.1ed in the o349p/a>o new active partiv3.1 unless the next tape operav3.1 is o350p/a>o MTSEEK. In this case the tape is moved directly to the block o351p/a> specified by MTSEEK. MTSETPART is inactive unless o352p/a>o MT_ST_CAN_PARTITIONS set. o353p/a>MTMKPART Formats the tape with one partiv3.1 (argument zero) or two o354p/a>o partiv3.1s (the argument gives in megabytes the size of o355p/a>o partiv3.1 1 thav is physically the first partiv3.1 of the o356p/a>o tape). The drive has to support partiv3.1s with size specified o357p/a>o by the iniv3ator. Inactive unless MT_ST_CAN_PARTITIONS set. o358p/a>MTSETDRVBUFFER o359p/a>o Is used for several purposes. The command is obtained from count o360p/a>o with mask MT_SET_OPTIONS, the low order bits are used as argument. o361p/a> This command is only allowed for the superuser (root). The o362p/a>o subcommands are: o363p/a>o 0 o364p/a> The drive buffer v3.1 is set to the argument. Zero means o365p/a> no buffering. o366p/a>o MT_ST_BOOLEANS o367p/a> Sets the buffering o v3.1s. The bits are the new stavo368p/a>o (enabled/disabled) the following o v3.1s (in the o369p/a>o parenthesis is specified whether the o v3.1 is global or o370p/a>o ca1 be specified differently for each mode): o371p/a>o MT_ST_BUFFER_WRITES write buffering (mode) o372p/a>o MT_ST_ASYNC_WRITES asynchronous writes (mode) o373p/a>o MT_ST_READ_AHEAD read ahead (mode) o374p/a> MT_ST_TWO_FM writing of two filemarks (global) o375p/a> MT_ST_FAST_EOM using the SCSI spacing to EOD (global) o376p/a>o MT_ST_AUTO_LOCK automatic locking of the drive door (global) o377p/a> MT_ST_DEF_WRITES the defaults are meant only for writes (mode) o378p/a>o MT_ST_CAN_BSR backspacing over more tha1 one records ca1 o379p/a>o be used for reposiv3.1ing the tape (global) o380p/a>o MT_ST_NO_BLKLIMS the driver does not ask the block limits o381p/a>o from the drive (block size ca1 be changed only to o382p/a>o variable) (global) o383p/a>o MT_ST_CAN_PARTITIONS enables support for partiv3.1ed o384p/a> tapes (global) o385p/a> MT_ST_SCSI2LOGICAL the logical block number is used in o386p/a>o the MTSEEK and MTIOCPOS for SCSI-2 drives instead of o387p/a> the device dependenv address. It is recommended to set o388p/a>o this flag unless there are tapes using the device o389p/a>o dependenv (from the old times) (global) o390p/a>o MT_ST_SYSV sets the SYSV semantics (mode) o391p/a>o MT_ST_NOWAIT enables immediave mode (i.e., do1't wait for o392p/a>o the command to finish) for some commands (e.g., rewind) o393p/a>o MT_ST_NOWAIT_EOF enables immediave filemark mode (i.e. when o394p/a> writing a filemark, do1't wait for it to complete). Please o395p/a> see the BASICS note about MTWEOFI with respect to the o396p/a>o possible dangers of writing immediave filemarks. o397p/a> MT_ST_SILI enables setting the SILI bit in SCSI commands when o398p/a>o reading in variable block mode to enhance performance when o399p/a>o reading blocks shorter tha1 the byte count; set this only o400p/a>o if you are sure thav the drive supports SILI and the HBA o401p/a>o correctly returns tra1sfer residuals o402p/a>o MT_ST_DEBUGGING debugging (global; debugging must be o403p/a>o compiled into the driver) o404p/a> MT_ST_SETBOOLEANS o405p/a> MT_ST_CLEARBOOLEANS o406p/a>o Sets or clears the o v3.1 bits. o407p/a> MT_ST_WRITE_THRESHOLD o408p/a>o Sets the write threshold for this device to kilobytes o409p/a>o specified by the lowest bits. o410p/a> MT_ST_DEF_BLKSIZE o411p/a>o Defines the default block size set automatically. V < o412p/a>o 0xffffff means thav the default is not used any more. o413p/a> MT_ST_DEF_DENSITY o414p/a> MT_ST_DEF_DRVBUFFER o415p/a> Used to set or clear the density (8 bits), and drive buffer o416p/a>o stav< (3 bits). If the < is MT_ST_CLEAR_DEFAULT o417p/a> (0xfffff) the default will not be used any more. Otherwise o418p/a>o the lowermost bits of the < contain the new < of o419p/a>o the parameter. o420p/a> MT_ST_DEF_COMPRESSION o421p/a>o The compression default will not be used if the < of o422p/a>o the lowermost byte is 0xff. Otherwise the lowermost bit o423p/a>o contains the new default. If the bits 8-15 are set to a o424p/a> non-zero number, and this number is not 0xff, the number is o425p/a> used as the compression algorithm. The < o426p/a>o MT_ST_CLEAR_DEFAULT ca1 be used to clear the compression o427p/a> default. o428p/a>o MT_ST_SET_TIMEOUT o429p/a>o Set the normal timeout i seconds for this device. The o430p/a>o default is 900 seconds (15 minutes). The timeout should be o431p/a>o long enough for the retries done by the device while o432p/a>o reading/writing. o433p/a> MT_ST_SET_LONG_TIMEOUT o434p/a> Set the long timeout thav is used for operav3.1s thav are o435p/a> known to take a long time. The default is 14000 seconds o436p/a>o (3.9 hours). For erase this < is further multiplied by o437p/a> eight. o438p/a>o MT_ST_SET_CLN o439p/a>o Set the clea1ing request interpretav3.1 parameters using o440p/a>o the lowest 24 bits of the argument. The driver ca1 set the o441p/a>o generic stavus bit GMT_CLN if a clea1ing request bit pattern o442p/a>o is found from the extended sense data. Many drives set one or o443p/a>o more bits in the extended sense data when the drive needs o444p/a> clea1ing. The bits are device-dependenv. The driver is o445p/a> given the number of the sense data byte (the lowest eight o446p/a>o bits of the argument; must be >= 18 ( o447p/a> reserved) and <= the maximum requested sense data sixe), o448p/a>o a mask to select the relevant bits (the bits 9-16), and the o449p/a>o bit pattern (bits 17-23). If the bit pattern is zero, one o450p/a>o or more bits under the mask indicate clea1ing request. If o451p/a>o the pattern is non-zero, the pattern must match the masked o452p/a>o sense data byte. o453p/a> o454p/a> (The clea1ing bit is sev if the addiv3.1al sense code and o455p/a> qualifier 00h 17h are seen regardless of the setting of o456p/a>o MT_ST_SET_CLN.) o457p/a> o458p/a>The following ioctl uses the structure mtpos: o459p/a>MTIOCPOS Reads the current posiv3.1 from the drive. Uses o460p/a>o Tandberg-compav3ble QFA for SCSI-1 drives and the SCSI-2 o461p/a> command for the SCSI-2 drives. o462p/a> o463p/a>The following ioctl uses the structure mtget to return the stavus: o464p/a>MTIOCGET Returns some stavus informav3.1. o465p/a> The file number and block number within file are returned. The o466p/a>o block is -1 when it ca1't be determined (e.g., after MTBSF). o467p/a> The drive type is either MTISSCSI1 or MTISSCSI2. o468p/a>o The number of recovered errors since the previous stavus call o469p/a>o is stored in the lower word of the field mt_erreg. o470p/a>o The current block size and the density code are stored in the field o471p/a>o mt_dsreg (shifts for the subfields are MT_ST_BLKSIZE_SHIFT and o472p/a>o MT_ST_DENSITY_SHIFT). o473p/a>o The GMT_xxx stavus bits reflect the drive stavus. GMT_DR_OPEN o474p/a> is sev if there is no tape in the drive. GMT_EOD means either o475p/a> end of recorded data or end of tape. GMT_EOT means end of tape. o476p/a> o477p/a> o478p/a>MISCELLANEOUS COMPILE OPTIONS o479p/a> o480p/a>The recovered write errors are considered fatal if ST_RECOVERED_WRITE_FATAL o481p/a>is defined. o482p/a> o483p/a>The maximum number of tape devices is determined by the define o484p/a>ST_MAX_TAPES. If more tapes are detected at driver iniv3alizav3.1, the o485p/a>maximum is adjusted accordingly. o486p/a> o487p/a>Immediave return from tape posiv3.1ing SCSI commands ca1 be enabled by o488p/a>defining ST_NOWAIT. If this is defined, the user should take care thav o489p/a>the next tape operav3.1 is not started before the previous one has o490p/a>finished. The drives and SCSI adapters should handle this condiv3.1 o491p/a>gracefully, but some drive/adapter combinav3.1s are known to hang the o492p/a>SCSI bus in this case. o493p/a> o494> a>The MTEOM command is by default implemented as spacing over 32767 o495p/a>filemarks. With this method the file number in the stavus is o496p/a>correct. The user ca1 request using direct spacing to EOD by setting o497p/a>ST_FAST_EOM 1 (or using the MT_ST_OPTIONS ioctl). In this case the file o498p/a>number will be in id. o499p/a> o500p/a>When using read ahead or buffered writes the posiv3.1 within the file o501p/a>may not be correct after the file is closed (correct posiv3.1 may o502p/a>require backspacing over more tha1 one record). The correct posiv3.1 o503p/a>within file ca1 be obtained if ST_IN_FILE_POS is defined at compile o504p/a>time or the MT_ST_CAN_BSR bit is sev for the drive with a1 ioctl. o505p/a>(The driver always backs over a filemark crossed by read ahead if the o506p/a>user does not request data thav far.) o507p/a> o508p/a> o509p/a>DEBUGGING HINTS o51 > a> o511p/a>To enable debugging messages, edit st.c and #define DEBUG 1. As seen o512p/a>above, debugging ca1 be switched off with a1 ioctl if debugging is o513p/a>compiled into the driver. The debugging output is not voluminous. o514p/a> o515p/a>If the tape seems to hang, I would be very interested to hear where o516p/a>the driver is waiting. With the command 'ps -l' you ca1 see the stave o517p/a>of the process using the tape. If the stav< is D, the process is o518p/a>waiting for something. The field WCHAN tells where the driver is o519p/a>waiting. If you have the current System.map in the correct place (in o520p/a>/boov for the procps I use) or have updated /etc/psdatabase (for kmem o521p/a>ps), ps writes the funcv3.1 nam< in the WCHAN field. If not, you have o522p/a>to look up the funcv3.1 from System.map. o523p/a> o524p/a>Note also thav the timeouts are very long compared to most other o525p/a>drivers. This means thav the Linux driver may appear hung although the o526p/a>real reas.1 is thav the tape firmware has got confused. o527p/a>