Commit | Line | Data |
---|---|---|
0f4bf035 RG |
1 | .Dd August 27, 1993 |
2 | .Dt ST 4 | |
3 | .Os 386BSD/NetBSD | |
4 | .Sh NAME | |
5 | .Nm st | |
6 | .Nd scsi tape driver | |
7 | .Sh SYNOPSIS | |
8 | .Nm device-driver st | |
9 | .Op Ar count | |
10 | .Sh DESCRIPTION | |
11 | The | |
12 | .Xr st | |
13 | driver provides support for a | |
14 | .Em scsi | |
15 | tape. It allows the tape | |
16 | to be run in upto four different modes depending on minor numbers | |
22c961eb | 17 | and supports several different 'sub modes'. |
0f4bf035 RG |
18 | The device can have both a |
19 | .Em raw | |
20 | interface | |
21 | and a | |
22 | .Em Block mode | |
23 | interface however only the raw interface is usually used (or recommended). | |
24 | In general the interfaces are similar to those described by | |
25 | .Xr wt 4 | |
26 | or | |
27 | .Xr mt 4 . | |
28 | ||
29 | .Pp | |
30 | Where the | |
31 | .Xr wt 4 | |
32 | device has a fairly low level interface to the system, | |
33 | .Em SCSI | |
34 | devices have a much higher level interface and talk to the system via | |
35 | a | |
36 | .Em SCSI Adapter | |
37 | and a | |
38 | .Em Scsi Adapter driver | |
39 | e.g. | |
40 | .Xr AHA1542 . | |
41 | A scsi adapter must also be separatly configured into the system | |
42 | before a scsi tape can be configured. | |
43 | .Pp | |
44 | As the scsi adapter is probed during boot, the | |
45 | .Em SCSI | |
46 | bus is scanned for devices. Any devices found which answer as 'Sequential' | |
47 | type devices will be attached to the | |
48 | .Nm | |
49 | driver. The first found will be attached as | |
50 | .Em st0 | |
51 | and the next, | |
52 | .Em st1 | |
53 | etc. | |
54 | .Pp | |
22c961eb | 55 | .Sh MOUNT SESSIONS |
0f4bf035 RG |
56 | The |
57 | .Nm | |
22c961eb RG |
58 | driver is based around the concept of a |
59 | .Em Mount Session | |
60 | , which is defined as the period between the time that a tape is mounted, | |
61 | and the time when it is unmounted. Any parameters set during a | |
62 | .Em Mount Session | |
63 | remain in effect for the remainder of the session or until replaced. The | |
64 | Tape can be unmounted, bringing the session to a close in several ways. | |
65 | These include: | |
66 | .Bl -tag -width ABOUT_THIS_BIG_BUT_REALLY_BIGGER | |
67 | .It Pa closing an 'unmount device' | |
68 | This is referred to as sub-mode 00 (see below). An example is /dev/rst0. | |
69 | .It Pa an MTOFFL ioctl | |
70 | Reachable throught the 'offline' command of | |
71 | .Xr st 1 | |
72 | .It Pa Openning another mode. | |
73 | Openning a different mode will implicitly unmount the tape, thereby closing | |
74 | off the mode that was previously mounted. All parameters will be loaded | |
75 | freshly from the new mode. (see below for more on 'modes'). | |
76 | .El | |
77 | .Pp | |
78 | Parameters that are required to last across the unmounting of a tape, | |
79 | should be set on the control device. This is submode 3 (see below) and is | |
80 | reached through a file with a name of the form /dev/st{y}ctl.{x}, where | |
81 | {y} is the drive number and {x} is the mode number. | |
82 | .Pp | |
83 | .Sh MODES AND SUB MODES | |
84 | There are four Operation modes. These are controlled by bits 2 | |
85 | and 3 of the minor number and are designed to allow people to easily | |
86 | read and write different formats of tape on devices that allow | |
87 | multiple formats. The parameters for each mode can be set individually | |
88 | by hand with the | |
89 | .Xr st 1 | |
90 | variant of the | |
91 | .Xr mt 1 | |
92 | command. When a device corresponding to a particular mode is first mounted, | |
93 | The operating parameters for that | |
94 | .Em Mount Session | |
95 | Are copied from that mode. Further changes to the parameters during the | |
96 | session will change those in effect for the session but not those set | |
97 | in the Operating Mode. To change the parameters for an Operating Mode, | |
98 | One must either assign the parameters to the control device, or compile | |
99 | them into the 'Rogues Gallery' table within the driver. | |
100 | .Pp | |
101 | In addition to the four Operation Modes mentionned above, | |
102 | bits 0 and 1 of the minor number are interpretted as being 'sub-modes'. | |
103 | The following sub-modes are supported | |
0f4bf035 RG |
104 | .Bl -tag -width ABOUT_THIS_BIG |
105 | .It Pa 00 | |
106 | A close will rewind the device. If the tape has been | |
107 | written, then a Filemark will be written before the rewind is requested. | |
22c961eb | 108 | The device is UNMOUNTED. |
0f4bf035 | 109 | .It Pa 01 |
22c961eb | 110 | A close will leave the tape MOUNTED. |
0f4bf035 RG |
111 | If the tape was written to a filemark will be written. |
112 | No other head positioning takes place. | |
113 | Any further reads or writes will occur directly after the | |
114 | last read, or the written filemark. | |
115 | .It Pa 10 | |
116 | A close will rewind the device. If the tape has been | |
117 | written, then a Filemark will be written before the rewind is requested. | |
118 | On completion of the rewind an UNLOAD command will be issued. | |
22c961eb | 119 | The device is UNMOUNTED. |
0f4bf035 | 120 | .It Pa 11 |
22c961eb RG |
121 | This is a special mode. |
122 | It is known as the | |
123 | .Em CONTROL DEVICE | |
124 | for the mode. Parameters set for the mode while in this sub | |
125 | mode will be remembered from one mount to the next. This allows the | |
126 | system administrator to set different characteristics (e.g. density, | |
127 | blocksize, (and eventually compression)) on each mode, and have the | |
128 | different modes keep those parameters independent of any parameter | |
129 | changes a user may invoke during a single mount session. At the | |
130 | completion of the user's mount session, drive parameters will revert | |
131 | to those set by the administrator. IO operations cannot be performed | |
132 | on this device/submode. General | |
133 | .Xr scsi 4 | |
134 | ioctls | |
135 | .Em MUST | |
136 | be performed against the control device. | |
0f4bf035 | 137 | .El |
22c961eb | 138 | .Sh BLOCKING MODES |
0f4bf035 RG |
139 | Scsi Tapes may run in either 'variable' or 'fixed block' modes. |
140 | Most QIC type devices run in Fixed block mode, where most 'reel to reel' tapes and | |
141 | many new cartridge formats, allow variable blocksize. The difference between | |
142 | the two is as follows: | |
143 | .Bl -tag -width variable-blocksize | |
144 | .It Pa Variable Blocksize | |
22c961eb RG |
145 | Each write made to the device results in a single logical record |
146 | written to the tape. You can never read or write PART of a record | |
147 | from tape, (though you may request a larger block and read a smaller | |
148 | record). You cannot read multiple blocks either. Data from a single | |
149 | write is therefore read by a single read. The block size used may | |
150 | be any value supported by the device, the scsi adapter and the | |
151 | system. (often variable between 1 byte and 64k (sometimes more)). | |
0f4bf035 | 152 | .Pp |
22c961eb RG |
153 | When reading a variable record/block from the tape, the head is |
154 | logically considered to be immediatly after the last item read, | |
155 | and before the next item after that. If the next item is a Filemark, | |
156 | but you never read it because you have all the data, then the next | |
157 | process to read will immediatly read the filemark and return EOF. | |
158 | (assuming you were in non-rewind mode). | |
0f4bf035 | 159 | .It Pa fixed Blocksize |
22c961eb RG |
160 | Data written by the user is passed to the tape as a succession of |
161 | fixed size blocks. It may be contiguouse in ram and read in a single | |
162 | DMA pass, however it is considered to be a series of independent | |
163 | blocks. You may never write an amount of data that is not an exact | |
164 | multiple of the blocksize. You may read and write the same data | |
165 | as a different set of records, In other words, blocks that were | |
166 | written together may be read separatly, and visa versa. | |
0f4bf035 | 167 | .Pp |
22c961eb RG |
168 | If you ask for more blocks than there are left in the file, then |
169 | the drive will encounter the filemark. Because there is some data | |
170 | to return to you (unless there were no records before the filemark) | |
171 | the driver will return the data to you (less than you requested), | |
172 | but hide from you the discovery of the Filemark. The NEXT read | |
173 | will be returned immediatly with an EOF. If you never Make the next | |
174 | read, but close the device, the next process to read will immediatly | |
175 | read the filemark and return EOF. (assuming you were in non-rewind | |
176 | mode). | |
0f4bf035 | 177 | .El |
22c961eb | 178 | .Sh FILEMARK HANDLING |
6d2c4694 RG |
179 | The handling of filemarks on write is pretty much automatic. If you |
180 | have written to the tape, and not done a read since, then a filemark will | |
181 | be written to the tape when you close the device. If a rewind is requested | |
182 | after a write, then the driver assumes that you have written the last file | |
183 | on the tape and ensures that there are two filemarks written to the tape. | |
184 | It takes into account any filemarks already written (whether by close | |
185 | or by explicit ioctl). The exception to this is that there seems to be | |
186 | a standard (which we follow, but don't understand why) that certain | |
187 | types of tape do not actually write two filemarks to tape, | |
188 | but when read, report a 'phantom' filemark when the last file is read. | |
189 | These devices include the QIC family of devices. It might be that this | |
190 | set of devices is the same set as that of fixed block devices. This has not | |
191 | been detirmined yet, and they are treated as separate behaviours by the | |
192 | driver at this time. | |
193 | .Pp | |
22c961eb | 194 | .SH KERNEL CONFIGURATION |
0f4bf035 RG |
195 | In configuring, if an optional |
196 | .Ar count | |
197 | is given in | |
198 | the specification, that number of scsi tapes are configured; | |
199 | Most storage for them is allocated only when found so a large number | |
200 | of configured devices is cheap. (once the first has included the driver). | |
201 | .Pp | |
22c961eb RG |
202 | Because different tape drives behave differently, there is a mechanism |
203 | within the source to st, to quickly and conveniently recognise and deal | |
204 | with brands and models of drive that have special requirements. | |
205 | .Pp | |
206 | There is a table (called the rogues gallery) in which the indentification | |
207 | strings of known errant drives can be stored. Along with each is | |
208 | a set of flags that allows the setting of densities and blocksizes for each | |
209 | of the 4 modes, along with a set of 'QUIRK' flags that can be | |
210 | used to enable or disable sections of code within the driver if a particular | |
211 | drive is recognised. | |
212 | .Pp | |
213 | .Sh IOCTLS | |
0f4bf035 RG |
214 | The following |
215 | .Xr ioctl 2 | |
216 | calls apply to scsi tapes. Some also apply to other tapes. They are defined | |
217 | in the header file | |
218 | .Em /sys/mtio.h. | |
219 | ||
220 | .Bl -tag -width MTIOCEEOT | |
221 | .It Pa MTIOCGET | |
222 | Get the mt control structure filled out by the driver, showing | |
223 | all the present settings. | |
224 | .It Pa MTIOCTOP | |
225 | Perform one of the following operations. These operations all have a | |
226 | single argument, which is either a boolean, or a signed integer, depending | |
227 | on the operation. | |
fa0c0320 | 228 | .Bl -tag -width MTSELDNSTY |
0f4bf035 RG |
229 | .It Pa MTWEOF |
230 | Write N end of file marks at the present head position. | |
231 | .It Pa MTFSF | |
232 | Skip over N Filemarks. Leave the head on the EOM side of the last skipped | |
233 | Filemark. | |
234 | .It Pa MTBSF | |
235 | Skip BACKWARDS over N Filemarks. Leave the head on the BOM (beginning of media) | |
236 | side of the last skipped Filemark. | |
237 | .It Pa MTFSR | |
238 | Skip forwards over N records. | |
239 | .It Pa MTBSR | |
240 | Skip backwards over N records. | |
241 | .It Pa MTREW | |
242 | Rewind the device to the beginning of the media. | |
243 | .It Pa MTOFFL | |
244 | Rewind the media (and if possible eject). Even if the device cannot | |
245 | eject the media it will often no longer respond to normal requests. | |
246 | .It Pa MTNOP | |
247 | No Op, set status only.. | |
248 | .It Pa MTCACHE | |
249 | Enable controller Buffering. | |
250 | .It Pa MTNOCACHE | |
251 | Disable controller Buffering. | |
252 | .It Pa MTSETBSIZ | |
22c961eb | 253 | Set the blocksize to use for the device/mode. If the device is capable of |
0f4bf035 | 254 | variable blocksize operation, and the blocksize is set to 0, then the drive |
22c961eb RG |
255 | will be driven in variable mode. This parameter is in effect for the present |
256 | mount session only, unless set on the control device. | |
fa0c0320 | 257 | .It Pa MTSETDNSTY |
0f4bf035 RG |
258 | Set the Density value (see |
259 | .Xr st 1 | |
fa0c0320 | 260 | ) to use when running in the mode openned (minor bits 2,3). |
22c961eb RG |
261 | This parameter is in effect for the present |
262 | mount session only, unless set on the control device. | |
0f4bf035 RG |
263 | .El |
264 | .It Pa MTIOCIEOT | |
265 | ?Set END of TAPE processing... not yet supported. | |
266 | .It Pa MTIOCEEOT | |
267 | ?Set END of TAPE processing... not yet supported. | |
268 | .El | |
22c961eb RG |
269 | .Pp |
270 | In addition, The | |
271 | .Nm | |
272 | driver will allow the use of any of the general | |
273 | .Xr scsi 4 | |
274 | ioctls, as long as the control device is used. | |
0f4bf035 RG |
275 | |
276 | .Sh FILES | |
22c961eb RG |
277 | .Bl -tag -width /dev/[n][e]rst[0-9].[0-3] -compact |
278 | .It Pa /dev/[n][e]rst[0-9].[0-3] | |
0f4bf035 | 279 | general form: |
22c961eb RG |
280 | .It Pa /dev/rst0.0 |
281 | Mode 0, rewind on close | |
282 | .It Pa /dev/nrst0.2 | |
283 | Mode 2, No rewind on close | |
284 | .It Pa /dev/erst0.3 | |
285 | Mode 3, Eject on close (if capable) | |
0f4bf035 | 286 | .It Pa /dev/rst0 |
22c961eb | 287 | Another name for rst0.0 |
0f4bf035 | 288 | .It Pa /dev/nrst0 |
22c961eb RG |
289 | Another name for nrst0.0 |
290 | .It Pa /dev/st0ctl.0 | |
291 | Parameters set to this device become the default parameters for [en]rst0.0 | |
292 | .It Pa /dev/st0ctl.1 | |
293 | Parameters set to this device become the default parameters for [en]rst0.1 | |
294 | .It Pa /dev/st0ctl.2 | |
295 | Parameters set to this device become the default parameters for [en]rst0.2 | |
296 | .It Pa /dev/st0ctl.3 | |
297 | Parameters set to this device become the default parameters for [en]rst0.3 | |
0f4bf035 RG |
298 | .El |
299 | .Sh DIAGNOSTICS | |
300 | None. | |
301 | .Sh SEE ALSO | |
302 | .Xr mt 1 | |
303 | .Xr st 1 | |
304 | .Sh HISTORY | |
305 | This | |
306 | .Nm | |
307 | driver appeared in MACH 2.5 . | |
308 |