1.\" Copyright (c) 1996
2.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\"
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
| 1.\" Copyright (c) 1996
2.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\"
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
|
26.\" $FreeBSD: head/share/man/man4/sa.4 117011 2003-06-28 23:53:39Z ru $
| 26.\" $FreeBSD: head/share/man/man4/sa.4 131530 2004-07-03 18:29:24Z ru $
|
27.\"
28.Dd June 6, 1999
29.Dt SA 4
30.Os
31.Sh NAME
32.Nm sa
33.Nd SCSI Sequential Access device driver
34.Sh SYNOPSIS
35.Cd device sa
36.Sh DESCRIPTION
37The
38.Nm
39driver provides support for all
40.Tn SCSI
41devices of the sequential access class that are attached to the system
42through a supported
43.Tn SCSI
44Host Adapter.
45The sequential access class includes tape and other linear access devices.
46.Pp
47A
48.Tn SCSI
49Host
50adapter must also be separately configured into the system
51before a
52.Tn SCSI
53sequential access device can be configured.
54.Sh MOUNT SESSIONS
55The
56.Nm
57driver is based around the concept of a
58.Dq Em mount session ,
59which is defined as the period between the time that a tape is
60mounted, and the time when it is unmounted.
61Any parameters set during
62a mount session remain in effect for the remainder of the session or
63until replaced.
64The tape can be unmounted, bringing the session to a
65close in several ways.
66These include:
67.Bl -enum
68.It
69Closing a `rewind device',
70referred to as sub-mode 00 below.
71An example is
72.Pa /dev/sa0 .
73.It
74Using the MTOFFL
75.Xr ioctl 2
76command, reachable through the
77.Sq Cm offline
78command of
79.Xr mt 1 .
80.El
81.Pp
82It should be noted that tape devices are exclusive open devices, except in
83the case where a control mode device is opened.
84In the latter case, exclusive
85access is only sought when needed (e.g., to set parameters).
86.Sh SUB-MODES
87Bits 0 and 1 of the minor number are interpreted as
88.Sq sub-modes .
89The sub-modes differ in the action taken when the device is closed:
90.Bl -tag -width XXXX
91.It 00
92A close will rewind the device; if the tape has been
93written, then a file mark will be written before the rewind is requested.
94The device is unmounted.
95.It 01
96A close will leave the tape mounted.
97If the tape was written to, a file mark will be written.
98No other head positioning takes place.
99Any further reads or writes will occur directly after the
100last read, or the written file mark.
101.It 10
102A close will rewind the device.
103If the tape has been
104written, then a file mark will be written before the rewind is requested.
105On completion of the rewind an unload command will be issued.
106The device is unmounted.
107.El
108.Sh BLOCKING MODES
109.Tn SCSI
110tapes may run in either
111.Sq Em variable
112or
113.Sq Em fixed
| 27.\"
28.Dd June 6, 1999
29.Dt SA 4
30.Os
31.Sh NAME
32.Nm sa
33.Nd SCSI Sequential Access device driver
34.Sh SYNOPSIS
35.Cd device sa
36.Sh DESCRIPTION
37The
38.Nm
39driver provides support for all
40.Tn SCSI
41devices of the sequential access class that are attached to the system
42through a supported
43.Tn SCSI
44Host Adapter.
45The sequential access class includes tape and other linear access devices.
46.Pp
47A
48.Tn SCSI
49Host
50adapter must also be separately configured into the system
51before a
52.Tn SCSI
53sequential access device can be configured.
54.Sh MOUNT SESSIONS
55The
56.Nm
57driver is based around the concept of a
58.Dq Em mount session ,
59which is defined as the period between the time that a tape is
60mounted, and the time when it is unmounted.
61Any parameters set during
62a mount session remain in effect for the remainder of the session or
63until replaced.
64The tape can be unmounted, bringing the session to a
65close in several ways.
66These include:
67.Bl -enum
68.It
69Closing a `rewind device',
70referred to as sub-mode 00 below.
71An example is
72.Pa /dev/sa0 .
73.It
74Using the MTOFFL
75.Xr ioctl 2
76command, reachable through the
77.Sq Cm offline
78command of
79.Xr mt 1 .
80.El
81.Pp
82It should be noted that tape devices are exclusive open devices, except in
83the case where a control mode device is opened.
84In the latter case, exclusive
85access is only sought when needed (e.g., to set parameters).
86.Sh SUB-MODES
87Bits 0 and 1 of the minor number are interpreted as
88.Sq sub-modes .
89The sub-modes differ in the action taken when the device is closed:
90.Bl -tag -width XXXX
91.It 00
92A close will rewind the device; if the tape has been
93written, then a file mark will be written before the rewind is requested.
94The device is unmounted.
95.It 01
96A close will leave the tape mounted.
97If the tape was written to, a file mark will be written.
98No other head positioning takes place.
99Any further reads or writes will occur directly after the
100last read, or the written file mark.
101.It 10
102A close will rewind the device.
103If the tape has been
104written, then a file mark will be written before the rewind is requested.
105On completion of the rewind an unload command will be issued.
106The device is unmounted.
107.El
108.Sh BLOCKING MODES
109.Tn SCSI
110tapes may run in either
111.Sq Em variable
112or
113.Sq Em fixed
|
114block-size modes. Most
| 114block-size modes.
115Most
|
115.Tn QIC Ns -type
116devices run in fixed block-size mode, where most nine-track tapes and
117many new cartridge formats allow variable block-size.
118The difference between the two is as follows:
119.Bl -inset
120.It Variable block-size:
121Each write made to the device results in a single logical record
122written to the tape.
123One can never read or write
124.Em part
125of a record from tape (though you may request a larger block and read
126a smaller record); nor can one read multiple blocks.
127Data from a single write is therefore read by a single read.
128The block size used
129may be any value supported by the device, the
130.Tn SCSI
131adapter and the system (usually between 1 byte and 64 Kbytes,
132sometimes more).
133.Pp
134When reading a variable record/block from the tape, the head is
135logically considered to be immediately after the last item read,
136and before the next item after that.
137If the next item is a file mark,
138but it was never read, then the next
139process to read will immediately hit the file mark and receive an end-of-file notification.
140.It Fixed block-size:
141Data written by the user is passed to the tape as a succession of
142fixed size blocks.
143It may be contiguous in memory, but it is
144considered to be a series of independent blocks.
145One may never write
146an amount of data that is not an exact multiple of the blocksize.
147One may read and write the same data as a different set of records.
148In other words, blocks that were written together may be read separately,
149and vice-versa.
150.Pp
151If one requests more blocks than remain in the file, the drive will
152encounter the file mark.
153As there is some data to return (unless
154there were no records before the file mark), the read will succeed,
155returning that data.
156The next read will return immediately with a value
157of 0.
158(As above, if the file mark is never read, it remains for the next
159process to read if in no-rewind mode.)
160.El
161.Sh FILE MARK HANDLING
162The handling of file marks on write is automatic.
163If the user has
164written to the tape, and has not done a read since the last write,
165then a file mark will be written to the tape when the device is
166closed.
167If a rewind is requested after a write, then the driver
168assumes that the last file on the tape has been written, and ensures
169that there are two file marks written to the tape.
170The exception to
171this is that there seems to be a standard (which we follow, but don't
172understand why) that certain types of tape do not actually write two
173file marks to tape, but when read, report a `phantom' file mark when the
174last file is read.
175These devices include the QIC family of devices.
176(It might be that this set of devices is the same set as that of fixed
177block devices.
178This has not been determined yet, and they are treated
179as separate behaviors by the driver at this time.)
180.Sh IOCTLS
181The
182.Nm
183driver supports all of the ioctls of
184.Xr mtio 4 .
185.Sh FILES
186.Bl -tag -width /dev/[n][e]sa[0-9] -compact
187.It Pa /dev/[n][e]sa[0-9]
188general form:
189.It Pa /dev/sa0
190Rewind on close
191.It Pa /dev/nsa0
192No rewind on close
193.It Pa /dev/esa0
194Eject on close (if capable)
195.It Pa /dev/sa0.ctl
196Control mode device (to examine state while another program is
197accessing the device, e.g.).
198.El
199.Sh BUGS
200This driver lacks many of the hacks required to deal with older devices.
201Many older
202.Tn SCSI-1
203devices may not work properly with this driver yet.
204.Pp
205Additionally, certain
206tapes (QIC tapes mostly) that were written under
207.Fx
2082.X
209aren't automatically read correctly with this driver: you may need to
210explicitly set variable block mode or set to the blocksize that works best
211for your device in order to read tapes written under
212.Fx
2132.X.
214.Pp
215Fine grained density and compression mode support that is bound to specific
216device names needs to be added.
217.Pp
218Support for fast indexing by use of partitions is missing.
219.Sh DIAGNOSTICS
220None.
221.Sh SEE ALSO
222.Xr mt 1 ,
223.Xr scsi 4
224.Sh AUTHORS
225.An -nosplit
226The
227.Nm
228driver was written for the
229.Tn CAM
230.Tn SCSI
231subsystem by
232.An Justin T. Gibbs
233and
234.An Kenneth Merry .
235Many ideas were gleaned from the
236.Nm st
237device driver written and ported from
238.Tn Mach
2392.5
240by
241.An Julian Elischer .
242.Pp
243The current owner of record is
244.An Matthew Jacob
245who has suffered too many
246years of breaking tape drivers.
| 116.Tn QIC Ns -type
117devices run in fixed block-size mode, where most nine-track tapes and
118many new cartridge formats allow variable block-size.
119The difference between the two is as follows:
120.Bl -inset
121.It Variable block-size:
122Each write made to the device results in a single logical record
123written to the tape.
124One can never read or write
125.Em part
126of a record from tape (though you may request a larger block and read
127a smaller record); nor can one read multiple blocks.
128Data from a single write is therefore read by a single read.
129The block size used
130may be any value supported by the device, the
131.Tn SCSI
132adapter and the system (usually between 1 byte and 64 Kbytes,
133sometimes more).
134.Pp
135When reading a variable record/block from the tape, the head is
136logically considered to be immediately after the last item read,
137and before the next item after that.
138If the next item is a file mark,
139but it was never read, then the next
140process to read will immediately hit the file mark and receive an end-of-file notification.
141.It Fixed block-size:
142Data written by the user is passed to the tape as a succession of
143fixed size blocks.
144It may be contiguous in memory, but it is
145considered to be a series of independent blocks.
146One may never write
147an amount of data that is not an exact multiple of the blocksize.
148One may read and write the same data as a different set of records.
149In other words, blocks that were written together may be read separately,
150and vice-versa.
151.Pp
152If one requests more blocks than remain in the file, the drive will
153encounter the file mark.
154As there is some data to return (unless
155there were no records before the file mark), the read will succeed,
156returning that data.
157The next read will return immediately with a value
158of 0.
159(As above, if the file mark is never read, it remains for the next
160process to read if in no-rewind mode.)
161.El
162.Sh FILE MARK HANDLING
163The handling of file marks on write is automatic.
164If the user has
165written to the tape, and has not done a read since the last write,
166then a file mark will be written to the tape when the device is
167closed.
168If a rewind is requested after a write, then the driver
169assumes that the last file on the tape has been written, and ensures
170that there are two file marks written to the tape.
171The exception to
172this is that there seems to be a standard (which we follow, but don't
173understand why) that certain types of tape do not actually write two
174file marks to tape, but when read, report a `phantom' file mark when the
175last file is read.
176These devices include the QIC family of devices.
177(It might be that this set of devices is the same set as that of fixed
178block devices.
179This has not been determined yet, and they are treated
180as separate behaviors by the driver at this time.)
181.Sh IOCTLS
182The
183.Nm
184driver supports all of the ioctls of
185.Xr mtio 4 .
186.Sh FILES
187.Bl -tag -width /dev/[n][e]sa[0-9] -compact
188.It Pa /dev/[n][e]sa[0-9]
189general form:
190.It Pa /dev/sa0
191Rewind on close
192.It Pa /dev/nsa0
193No rewind on close
194.It Pa /dev/esa0
195Eject on close (if capable)
196.It Pa /dev/sa0.ctl
197Control mode device (to examine state while another program is
198accessing the device, e.g.).
199.El
200.Sh BUGS
201This driver lacks many of the hacks required to deal with older devices.
202Many older
203.Tn SCSI-1
204devices may not work properly with this driver yet.
205.Pp
206Additionally, certain
207tapes (QIC tapes mostly) that were written under
208.Fx
2092.X
210aren't automatically read correctly with this driver: you may need to
211explicitly set variable block mode or set to the blocksize that works best
212for your device in order to read tapes written under
213.Fx
2142.X.
215.Pp
216Fine grained density and compression mode support that is bound to specific
217device names needs to be added.
218.Pp
219Support for fast indexing by use of partitions is missing.
220.Sh DIAGNOSTICS
221None.
222.Sh SEE ALSO
223.Xr mt 1 ,
224.Xr scsi 4
225.Sh AUTHORS
226.An -nosplit
227The
228.Nm
229driver was written for the
230.Tn CAM
231.Tn SCSI
232subsystem by
233.An Justin T. Gibbs
234and
235.An Kenneth Merry .
236Many ideas were gleaned from the
237.Nm st
238device driver written and ported from
239.Tn Mach
2402.5
241by
242.An Julian Elischer .
243.Pp
244The current owner of record is
245.An Matthew Jacob
246who has suffered too many
247years of breaking tape drivers.
|