Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SA(4)		       FreeBSD Kernel Interfaces Manual			 SA(4)

NAME
     sa	-- SCSI	Sequential Access device driver

SYNOPSIS
     device sa

DESCRIPTION
     The sa driver provides support for	all SCSI devices of the	sequential
     access class that are attached to the system through a supported SCSI
     Host Adapter.  The	sequential access class	includes tape and other	linear
     access devices.

     A SCSI Host adapter must also be separately configured into the system
     before a SCSI sequential access device can	be configured.

MOUNT SESSIONS
     The sa driver is based around the concept of a ``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:

     1.	  Closing a `rewind device', referred to as sub-mode 00	below.	An
	  example is /dev/sa0.

     2.	  Using	the MTOFFL ioctl(2) command, reachable through the `offline'
	  command of mt(1).

     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).

SUB-MODES
     Bits 0 and	1 of the minor number are interpreted as `sub-modes'.  The
     sub-modes differ in the action taken when the device is closed:

     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.

     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.

     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.

BLOCKING MODES
     SCSI tapes	may run	in either `variable' or	`fixed'	block-size modes.
     Most QIC-type devices run in fixed	block-size mode, where most nine-track
     tapes and many new	cartridge formats allow	variable block-size.  The dif-
     ference between the two is	as follows:

     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 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	SCSI adapter and the system (usually
     between 1 byte and	64 Kbytes, sometimes more).

     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.

     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.

     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.)

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 FreeBSD behavior, prior to
     FreeBSD 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.

     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	tun-
     ables WILL	GO AWAY	in FreeBSD 11.0.  They are provided for	transition
     purposes only.

     kern.cam.sa.allow_io_split

	 This variable,	when set to 1, will configure all sa devices to	split
	 large buffers into smaller pieces when	needed.

     kern.cam.sa.%d.allow_io_split

	 This variable,	when set to 1, will configure the given	sa unit	to
	 split large buffers into multiple pieces.  This will override the
	 global	setting, if it exists.

     There are several sysctl(8) variables available to	view block handling
     parameters:

     kern.cam.sa.%d.allow_io_split

	 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.

     kern.cam.sa.%d.maxio

	 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 max-
	 imum may be restricted	further	by the tape drive via the SCSI READ
	 BLOCK LIMITS command.

     kern.cam.sa.%d.cpi_maxio

	 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.

FILE MARK HANDLING
     The handling of file marks	on write is automatic.	If the user has	writ-
     ten 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.)

IOCTLS
     The sa driver supports all	of the ioctls of mtio(4).

FILES
     /dev/[n][e]sa[0-9]	 general form:
     /dev/sa0		 Rewind	on close
     /dev/nsa0		 No rewind on close
     /dev/esa0		 Eject on close	(if capable)
     /dev/sa0.ctl	 Control mode device (to examine state while another
			 program is accessing the device, e.g.).

DIAGNOSTICS
     None.

SEE ALSO
     cam(4), mt(1)

AUTHORS
     The sa driver was written for the CAM SCSI	subsystem by Justin T. Gibbs
     and Kenneth Merry.	 Many ideas were gleaned from the st device driver
     written and ported	from Mach 2.5 by Julian	Elischer.

     The current owner of record is Matthew Jacob who has suffered too many
     years of breaking tape drivers.

BUGS
     This driver lacks many of the hacks required to deal with older devices.
     Many older	SCSI-1 devices may not work properly with this driver yet.

     Additionally, certain tapes (QIC tapes mostly) that were written under
     FreeBSD 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
     FreeBSD 2.X.

     Fine grained density and compression mode support that is bound to	spe-
     cific device names	needs to be added.

     Support for fast indexing by use of partitions is missing.

FreeBSD	9.2			August 23, 2013			   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | MOUNT SESSIONS | SUB-MODES | BLOCKING MODES | BLOCK SIZES | FILE MARK HANDLING | IOCTLS | FILES | DIAGNOSTICS | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=sa&sektion=4&manpath=FreeBSD+10.0-RELEASE>

home | help