Documentation/scsi/st.rst

1 .. SPDX-License-Identifier: GPL-2.0
23 flexible method and applicable to single-user workstations. However,
28 parameters, like block size and density using the MTSETDRVBUFFER ioctl.
32 drive performs auto-detection of the tape format well (like some
33 QIC-drives). The result is that any tape can be read, writing can be
37 does not perform auto-detection well enough and there is a single
39 used only in variable block mode (I don't know if this is sensible
40 or not :-).
47 number (bits 5 and 6). The number of modes can be changed by changing
57 between formats in multi-tape operations (the explicitly overridden
71 The driver supports fixed and variable block size (within buffer
72 limits). Both the auto-rewind (minor equals device number) and
73 non-rewind devices (minor is 128 + device number) are implemented.
75 In variable block mode, the byte count in write() determines the size
76 of the physical block on tape. When reading, the drive reads the next
77 tape block and returns to the user the data if the read() byte count
78 is at least the block size. Otherwise, error ENOMEM is returned.
80 In fixed block mode, the data transfer between the drive and the
81 driver is in multiples of the block size. The write() byte count must
82 be a multiple of the block size. This is not required when reading but
95 Writing filemarks without the immediate bit set in the SCSI command block acts
128     dev_upper non-rew mode dev-lower
129     20 -  8     7    6 5  4      0
131 The non-rewind bit is always bit 7 (the uppermost bit in the lowermost
132 byte). The bits defining the mode are below the non-rewind bit. The
133 remaining bits define the tape device number. This numbering is
134 backward compatible with the numbering used when the minor number was
143 and non-rewind entries for each mode. The names are stxy and nstxy, where x
144 is the tape number and y a character corresponding to the mode (none, l, m,
151 the defaults set by the user. The value -1 means the default is not set. The
166 directory corresponding to the mode 0 auto-rewind device (e.g., st0).
179    regular expression "^st[0-9]+$"
191       - The number of I/Os currently outstanding to this device.
193       - The amount of time spent waiting (in nanoseconds) for all I/O
198       - The number of I/Os issued to the tape drive other than read or
200         following calculation io_ms-read_ms-write_ms.
202       - The number of bytes read from the tape drive.
204       - The number of read requests issued to the tape drive.
206       - The amount of time (in nanoseconds) spent waiting for read
209       - The number of bytes written to the tape drive.
211       - The number of write requests issued to the tape drive.
213       - The amount of time (in nanoseconds) spent waiting for write
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
257 is not possible, a driver buffer allocated at run-time is used. If
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
265 - one or more pages can't be locked into memory (should not happen in
268 The size of the driver buffers is always at least one tape block. In fixed
269 block mode, the minimum buffer size is defined (in 1024 byte units) by
270 ST_FIXED_BUFFER_BLOCKS. With small block size this allows buffering of
272 blocks. Buffering of data across write calls in fixed block mode is
273 allowed if ST_BUFFER_WRITES is non-zero and direct i/o is not used.
280 -b option) may have had good throughput but this is not true any more with
282 is to use bigger write() byte counts (e.g., tar -b 64).
287 direct i/o and not in fixed block mode.
291 tape after the early-warning mark to flush the driver buffer.
293 Read ahead for fixed block mode (ST_READ_AHEAD). Filling the buffer is
298 Scatter/gather buffers (buffers that consist of chunks non-contiguous
313    allocated so that as many segments as possible are used but the number
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,
329 is finished and the number of bytes is returned. The next write
330 returns -1 and errno is set to ENOSPC. To enable writing a trailer,
331 the next write is allowed to proceed and, if successful, the number of
332 bytes is returned. After this, -1 and the number of bytes are
339 The buffer size, write threshold, and the maximum number of allocated buffers
343 buffer_kbs=xxx             the buffer size for fixed block mode is set
346 max_sg_segs=xxx		   the maximum number of scatter/gather
349 			   tape drive if this is non-zero
353 set, the write threshold is set to the new buffer size - 2 kB.
362 with 'st.'. For instance, to set the maximum number of scatter/gather
364 number of scatter/gather segments).
368 the driver as module. If several parameters are set, the keyword-value
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
393 (look for a package mt-st* from the Linux ftp sites; the GNU mt does
431 	Re-tension tape.
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.
443 	Set the drive block size. Setting to zero sets the drive into
444         variable block mode (if applicable).
453 	MT_ST_HPLOADER_OFFSET + 6, the number x is used sent to 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
469 	MTSEEK. In this case the tape is moved directly to the block
474 	partitions (argument non-zero). If the argument is positive,
480 	LTO drives from LTO-5 upwards. The drive has to support partitions
516 		the driver does not ask the block limits
517 		from the drive (block size can be changed only to
523 		the logical block number is used in
524 		the MTSEEK and MTIOCPOS for SCSI-2 drives instead of
540 		reading in variable block mode to enhance performance when
554 	   Defines the default block size set automatically. Value
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
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
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
593 	   the pattern is non-zero, the pattern must match the masked
604         Tandberg-compatible QFA for SCSI-1 drives and the SCSI-2
605         command for the SCSI-2 drives.
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).
614         The number of recovered errors since the previous status call
616         The current block size and the density code are stored in the field
630 The maximum number of tape devices is determined by the define
642 filemarks. With this method the file number in the status is
645 number will be invalid.
668 the driver is waiting. With the command 'ps -l' you can see the state