diff options
Diffstat (limited to 'share/man/man4/sa.4')
| -rw-r--r-- | share/man/man4/sa.4 | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/share/man/man4/sa.4 b/share/man/man4/sa.4 new file mode 100644 index 0000000..aa72f68 --- /dev/null +++ b/share/man/man4/sa.4 @@ -0,0 +1,311 @@ +.\" Copyright (c) 1996 +.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 23, 2013 +.Dt SA 4 +.Os +.Sh NAME +.Nm sa +.Nd SCSI Sequential Access device driver +.Sh SYNOPSIS +.Cd device sa +.Sh DESCRIPTION +The +.Nm +driver provides support for all +.Tn SCSI +devices of the sequential access class that are attached to the system +through a supported +.Tn SCSI +Host Adapter. +The sequential access class includes tape and other linear access devices. +.Pp +A +.Tn SCSI +Host +adapter must also be separately configured into the system +before a +.Tn SCSI +sequential access device can be configured. +.Sh MOUNT SESSIONS +The +.Nm +driver is based around the concept of a +.Dq Em mount session , +which is defined as the period between the time that a tape is +mounted, and the time when it is unmounted. +Any parameters set during +a mount session remain in effect for the remainder of the session or +until replaced. +The tape can be unmounted, bringing the session to a +close in several ways. +These include: +.Bl -enum +.It +Closing a `rewind device', +referred to as sub-mode 00 below. +An example is +.Pa /dev/sa0 . +.It +Using the MTOFFL +.Xr ioctl 2 +command, reachable through the +.Sq Cm offline +command of +.Xr mt 1 . +.El +.Pp +It should be noted that tape devices are exclusive open devices, except in +the case where a control mode device is opened. +In the latter case, exclusive +access is only sought when needed (e.g., to set parameters). +.Sh SUB-MODES +Bits 0 and 1 of the minor number are interpreted as +.Sq sub-modes . +The sub-modes differ in the action taken when the device is closed: +.Bl -tag -width XXXX +.It 00 +A close will rewind the device; if the tape has been +written, then a file mark will be written before the rewind is requested. +The device is unmounted. +.It 01 +A close will leave the tape mounted. +If the tape was written to, a file mark will be written. +No other head positioning takes place. +Any further reads or writes will occur directly after the +last read, or the written file mark. +.It 10 +A close will rewind the device. +If the tape has been +written, then a file mark will be written before the rewind is requested. +On completion of the rewind an unload command will be issued. +The device is unmounted. +.El +.Sh BLOCKING MODES +.Tn SCSI +tapes may run in either +.Sq Em variable +or +.Sq Em fixed +block-size modes. +Most +.Tn QIC Ns -type +devices run in fixed block-size mode, where most nine-track tapes and +many new cartridge formats allow variable block-size. +The difference between the two is as follows: +.Bl -inset +.It Variable block-size: +Each write made to the device results in a single logical record +written to the tape. +One can never read or write +.Em part +of a record from tape (though you may request a larger block and read +a smaller record); nor can one read multiple blocks. +Data from a single write is therefore read by a single read. +The block size used +may be any value supported by the device, the +.Tn SCSI +adapter and the system (usually between 1 byte and 64 Kbytes, +sometimes more). +.Pp +When reading a variable record/block from the tape, the head is +logically considered to be immediately after the last item read, +and before the next item after that. +If the next item is a file mark, +but it was never read, then the next +process to read will immediately hit the file mark and receive an end-of-file notification. +.It Fixed block-size: +Data written by the user is passed to the tape as a succession of +fixed size blocks. +It may be contiguous in memory, but it is +considered to be a series of independent blocks. +One may never write +an amount of data that is not an exact multiple of the blocksize. +One may read and write the same data as a different set of records. +In other words, blocks that were written together may be read separately, +and vice-versa. +.Pp +If one requests more blocks than remain in the file, the drive will +encounter the file mark. +As there is some data to return (unless +there were no records before the file mark), the read will succeed, +returning that data. +The next read will return immediately with a value +of 0. +(As above, if the file mark is never read, it remains for the next +process to read if in no-rewind mode.) +.El +.Sh BLOCK SIZES +By default, the driver will NOT accept reads or writes to a tape device that +are larger than may be written to or read from the mounted tape using a single +write or read request. +Because of this, the application author may have confidence that his wishes +are respected in terms of the block size written to tape. +For example, if the user tries to write a 256KB block to the tape, but the +controller can handle no more than 128KB, the write will fail. +The previous +.Fx +behavior, prior to +.Fx +10.0, +was to break up large reads or writes into smaller blocks when going to the +tape. +The problem with that behavior, though, is that it hides the actual on-tape +block size from the application writer, at least in variable block mode. +.Pp +If the user would like his large reads and writes broken up into separate +pieces, he may set the following loader tunables. +Note that these tunables WILL GO AWAY in +.Fx 11.0 . +They are provided for transition purposes only. +.Bl -tag -width 12 +.It kern.cam.sa.allow_io_split +.Pp +This variable, when set to 1, will configure all +.Nm +devices to split large buffers into smaller pieces when needed. +.It kern.cam.sa.%d.allow_io_split +.Pp +This variable, when set to 1, will configure the given +.Nm +unit to split large buffers into multiple pieces. +This will override the global setting, if it exists. +.El +.Pp +There are several +.Xr sysctl 8 +variables available to view block handling parameters: +.Bl -tag -width 12 +.It kern.cam.sa.%d.allow_io_split +.Pp +This variable allows the user to see, but not modify, the current I/O split +setting. +The user is not permitted to modify this setting so that there is no chance +of behavior changing for the application while a tape is mounted. +.It kern.cam.sa.%d.maxio +.Pp +This variable shows the maximum I/O size in bytes that is allowed by the +combination of kernel tuning parameters (MAXPHYS, DFLTPHYS) and the +capabilities of the controller that is attached to the tape drive. +Applications may look at this value for a guide on how large an I/O may be +permitted, but should keep in mind that the actual maximum may be +restricted further by the tape drive via the +.Tn SCSI +READ BLOCK LIMITS command. +.It kern.cam.sa.%d.cpi_maxio +.Pp +This variable shows the maximum I/O size supported by the controller, in +bytes, that is reported via the CAM Path Inquiry CCB (XPT_PATH_INQ). +If this is 0, that means that the controller has not reported a maximum I/O +size. +.El +.Sh FILE MARK HANDLING +The handling of file marks on write is automatic. +If the user has +written to the tape, and has not done a read since the last write, +then a file mark will be written to the tape when the device is +closed. +If a rewind is requested after a write, then the driver +assumes that the last file on the tape has been written, and ensures +that there are two file marks written to the tape. +The exception to +this is that there seems to be a standard (which we follow, but do not +understand why) that certain types of tape do not actually write two +file marks to tape, but when read, report a `phantom' file mark when the +last file is read. +These devices include the QIC family of devices. +(It might be that this set of devices is the same set as that of fixed +block devices. +This has not been determined yet, and they are treated +as separate behaviors by the driver at this time.) +.Sh IOCTLS +The +.Nm +driver supports all of the ioctls of +.Xr mtio 4 . +.Sh FILES +.Bl -tag -width /dev/[n][e]sa[0-9] -compact +.It Pa /dev/[n][e]sa[0-9] +general form: +.It Pa /dev/sa0 +Rewind on close +.It Pa /dev/nsa0 +No rewind on close +.It Pa /dev/esa0 +Eject on close (if capable) +.It Pa /dev/sa0.ctl +Control mode device (to examine state while another program is +accessing the device, e.g.). +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr cam 4 , +.Xr mt 1 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written for the +.Tn CAM +.Tn SCSI +subsystem by +.An Justin T. Gibbs +and +.An Kenneth Merry . +Many ideas were gleaned from the +.Nm st +device driver written and ported from +.Tn Mach +2.5 +by +.An Julian Elischer . +.Pp +The current owner of record is +.An Matthew Jacob +who has suffered too many +years of breaking tape drivers. +.Sh BUGS +This driver lacks many of the hacks required to deal with older devices. +Many older +.Tn SCSI-1 +devices may not work properly with this driver yet. +.Pp +Additionally, certain +tapes (QIC tapes mostly) that were written under +.Fx +2.X +are not automatically read correctly with this driver: you may need to +explicitly set variable block mode or set to the blocksize that works best +for your device in order to read tapes written under +.Fx +2.X. +.Pp +Fine grained density and compression mode support that is bound to specific +device names needs to be added. +.Pp +Support for fast indexing by use of partitions is missing. |
