diff options
author | dg <dg@FreeBSD.org> | 1995-01-25 09:18:56 +0000 |
---|---|---|
committer | dg <dg@FreeBSD.org> | 1995-01-25 09:18:56 +0000 |
commit | 2871de848d7f8b3dcc6fbba6a080a04e86479e02 (patch) | |
tree | 3e44c2eda318f56905393229154d72bc013e0ed5 /share/man/man4/sa.4 | |
parent | 2c76088f4621ddf401de9d8cecde525a86de9fbc (diff) | |
download | FreeBSD-src-2871de848d7f8b3dcc6fbba6a080a04e86479e02.zip FreeBSD-src-2871de848d7f8b3dcc6fbba6a080a04e86479e02.tar.gz |
Added more missing manual pages from 1.1.5.
Diffstat (limited to 'share/man/man4/sa.4')
-rw-r--r-- | share/man/man4/sa.4 | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/share/man/man4/sa.4 b/share/man/man4/sa.4 new file mode 100644 index 0000000..28f232b --- /dev/null +++ b/share/man/man4/sa.4 @@ -0,0 +1,308 @@ +.Dd August 27, 1993 +.Dt ST 4 +.Os FreeBSD +.Sh NAME +.Nm st +.Nd scsi tape driver +.Sh SYNOPSIS +.Nm device-driver st +.Op Ar count +.Sh DESCRIPTION +The +.Xr st +driver provides support for a +.Em scsi +tape. It allows the tape +to be run in upto four different modes depending on minor numbers +and supports several different 'sub modes'. +The device can have both a +.Em raw +interface +and a +.Em Block mode +interface however only the raw interface is usually used (or recommended). +In general the interfaces are similar to those described by +.Xr wt 4 +or +.Xr mt 4 . + +.Pp +Where the +.Xr wt 4 +device has a fairly low level interface to the system, +.Em SCSI +devices have a much higher level interface and talk to the system via +a +.Em SCSI Adapter +and a +.Em Scsi Adapter driver +e.g. +.Xr AHA1542 . +A scsi adapter must also be separatly configured into the system +before a scsi tape can be configured. +.Pp +As the scsi adapter is probed during boot, the +.Em SCSI +bus is scanned for devices. Any devices found which answer as 'Sequential' +type devices will be attached to the +.Nm +driver. The first found will be attached as +.Em st0 +and the next, +.Em st1 +etc. +.Pp +.Sh MOUNT SESSIONS +The +.Nm +driver is based around the concept of a +.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 +.Em 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 -tag -width ABOUT_THIS_BIG_BUT_REALLY_BIGGER +.It Pa closing an 'unmount device' +This is referred to as sub-mode 00 (see below). An example is /dev/rst0. +.It Pa an MTOFFL ioctl +Reachable throught the 'offline' command of +.Xr st 1 +.It Pa Openning another mode. +Openning a different mode will implicitly unmount the tape, thereby closing +off the mode that was previously mounted. All parameters will be loaded +freshly from the new mode. (see below for more on 'modes'). +.El +.Pp +Parameters that are required to last across the unmounting of a tape, +should be set on the control device. This is submode 3 (see below) and is +reached through a file with a name of the form /dev/st{y}ctl.{x}, where +{y} is the drive number and {x} is the mode number. +.Pp +.Sh MODES AND SUB MODES +There are four Operation modes. These are controlled by bits 2 +and 3 of the minor number and are designed to allow people to easily +read and write different formats of tape on devices that allow +multiple formats. The parameters for each mode can be set individually +by hand with the +.Xr st 1 +variant of the +.Xr mt 1 +command. When a device corresponding to a particular mode is first mounted, +The operating parameters for that +.Em Mount Session +Are copied from that mode. Further changes to the parameters during the +session will change those in effect for the session but not those set +in the Operating Mode. To change the parameters for an Operating Mode, +One must either assign the parameters to the control device, or compile +them into the 'Rogues Gallery' table within the driver. +.Pp +In addition to the four Operation Modes mentionned above, +bits 0 and 1 of the minor number are interpretted as being 'sub-modes'. +The following sub-modes are supported +.Bl -tag -width ABOUT_THIS_BIG +.It Pa 00 +A close will rewind the device. If the tape has been +written, then a Filemark will be written before the rewind is requested. +The device is UNMOUNTED. +.It Pa 01 +A close will leave the tape MOUNTED. +If the tape was written to a filemark will be written. +No other head positioning takes place. +Any further reads or writes will occur directly after the +last read, or the written filemark. +.It Pa 10 +A close will rewind the device. If the tape has been +written, then a Filemark will be written before the rewind is requested. +On completion of the rewind an UNLOAD command will be issued. +The device is UNMOUNTED. +.It Pa 11 +This is a special mode. +It is known as the +.Em CONTROL DEVICE +for the mode. Parameters set for the mode while in this sub +mode will be remembered from one mount to the next. This allows the +system administrator to set different characteristics (e.g. density, +blocksize, (and eventually compression)) on each mode, and have the +different modes keep those parameters independent of any parameter +changes a user may invoke during a single mount session. At the +completion of the user's mount session, drive parameters will revert +to those set by the administrator. IO operations cannot be performed +on this device/submode. General +.Xr scsi 4 +ioctls +.Em MUST +be performed against the control device. +.El +.Sh BLOCKING MODES +Scsi Tapes may run in either 'variable' or 'fixed block' modes. +Most QIC type devices run in Fixed block mode, where most 'reel to reel' tapes and +many new cartridge formats, allow variable blocksize. The difference between +the two is as follows: +.Bl -tag -width variable-blocksize +.It Pa Variable Blocksize +Each write made to the device results in a single logical record +written to the tape. You can never read or write PART of a record +from tape, (though you may request a larger block and read a smaller +record). You cannot read multiple blocks either. 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. (often variable between 1 byte and 64k (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 Filemark, +but you never read it because you have all the data, then the next +process to read will immediately read the filemark and return EOF. +(assuming you were in non-rewind mode). +.It Pa fixed Blocksize +Data written by the user is passed to the tape as a succession of +fixed size blocks. It may be contiguouse in ram and read in a single +DMA pass, however it is considered to be a series of independent +blocks. You may never write an amount of data that is not an exact +multiple of the blocksize. You may read and write the same data +as a different set of records, In other words, blocks that were +written together may be read separatly, and visa versa. +.Pp +If you ask for more blocks than there are left in the file, then +the drive will encounter the filemark. Because there is some data +to return to you (unless there were no records before the filemark) +the driver will return the data to you (less than you requested), +but hide from you the discovery of the Filemark. The NEXT read +will be returned immediately with an EOF. If you never Make the next +read, but close the device, the next process to read will immediately +read the filemark and return EOF. (assuming you were in non-rewind +mode). +.El +.Sh FILEMARK HANDLING +The handling of filemarks on write is pretty much automatic. If you +have written to the tape, and not done a read since, then a filemark will +be written to the tape when you close the device. If a rewind is requested +after a write, then the driver assumes that you have written the last file +on the tape and ensures that there are two filemarks written to the tape. +It takes into account any filemarks already written (whether by close +or by explicit ioctl). The exception to this is that there seems to be +a standard (which we follow, but don't understand why) that certain +types of tape do not actually write two filemarks to tape, +but when read, report a 'phantom' filemark 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 detirmined yet, and they are treated as separate behaviors by the +driver at this time. +.Pp +.SH KERNEL CONFIGURATION +In configuring, if an optional +.Ar count +is given in +the specification, that number of scsi tapes are configured; +Most storage for them is allocated only when found so a large number +of configured devices is cheap. (once the first has included the driver). +.Pp +Because different tape drives behave differently, there is a mechanism +within the source to st, to quickly and conveniently recognise and deal +with brands and models of drive that have special requirements. +.Pp +There is a table (called the rogues gallery) in which the indentification +strings of known errant drives can be stored. Along with each is +a set of flags that allows the setting of densities and blocksizes for each +of the 4 modes, along with a set of 'QUIRK' flags that can be +used to enable or disable sections of code within the driver if a particular +drive is recognised. +.Pp +.Sh IOCTLS +The following +.Xr ioctl 2 +calls apply to scsi tapes. Some also apply to other tapes. They are defined +in the header file +.Em /sys/mtio.h. + +.Bl -tag -width MTIOCEEOT +.It Pa MTIOCGET +Get the mt control structure filled out by the driver, showing +all the present settings. +.It Pa MTIOCTOP +Perform one of the following operations. These operations all have a +single argument, which is either a boolean, or a signed integer, depending +on the operation. +.Bl -tag -width MTSELDNSTY +.It Pa MTWEOF +Write N end of file marks at the present head position. +.It Pa MTFSF +Skip over N Filemarks. Leave the head on the EOM side of the last skipped +Filemark. +.It Pa MTBSF +Skip BACKWARDS over N Filemarks. Leave the head on the BOM (beginning of media) +side of the last skipped Filemark. +.It Pa MTFSR +Skip forwards over N records. +.It Pa MTBSR +Skip backwards over N records. +.It Pa MTREW +Rewind the device to the beginning of the media. +.It Pa MTOFFL +Rewind the media (and if possible eject). Even if the device cannot +eject the media it will often no longer respond to normal requests. +.It Pa MTNOP +No Op, set status only.. +.It Pa MTCACHE +Enable controller Buffering. +.It Pa MTNOCACHE +Disable controller Buffering. +.It Pa MTSETBSIZ +Set the blocksize to use for the device/mode. If the device is capable of +variable blocksize operation, and the blocksize is set to 0, then the drive +will be driven in variable mode. This parameter is in effect for the present +mount session only, unless set on the control device. +.It Pa MTSETDNSTY +Set the Density value (see +.Xr st 1 +) to use when running in the mode openned (minor bits 2,3). +This parameter is in effect for the present +mount session only, unless set on the control device. +.El +.It Pa MTIOCIEOT +?Set END of TAPE processing... not yet supported. +.It Pa MTIOCEEOT +?Set END of TAPE processing... not yet supported. +.El +.Pp +In addition, The +.Nm +driver will allow the use of any of the general +.Xr scsi 4 +ioctls, as long as the control device is used. + +.Sh FILES +.Bl -tag -width /dev/[n][e]rst[0-9].[0-3] -compact +.It Pa /dev/[n][e]rst[0-9].[0-3] +general form: +.It Pa /dev/rst0.0 +Mode 0, rewind on close +.It Pa /dev/nrst0.2 +Mode 2, No rewind on close +.It Pa /dev/erst0.3 +Mode 3, Eject on close (if capable) +.It Pa /dev/rst0 +Another name for rst0.0 +.It Pa /dev/nrst0 +Another name for nrst0.0 +.It Pa /dev/st0ctl.0 +Parameters set to this device become the default parameters for [en]rst0.0 +.It Pa /dev/st0ctl.1 +Parameters set to this device become the default parameters for [en]rst0.1 +.It Pa /dev/st0ctl.2 +Parameters set to this device become the default parameters for [en]rst0.2 +.It Pa /dev/st0ctl.3 +Parameters set to this device become the default parameters for [en]rst0.3 +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr mt 1 +.Xr st 1 +.Sh HISTORY +This +.Nm +driver appeared in MACH 2.5 . + |