summaryrefslogtreecommitdiffstats
path: root/share/man/man4/ch.4
blob: 0db548c81e60249d85b5fc20a33241427a8a1309 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
.\" $FreeBSD$
.\" 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.
.\"
.Dd May 14, 1998
.Dt CH 4
.Os
.Sh NAME
.Nm ch
.Nd SCSI media-changer (juke box) driver
.Sh SYNOPSIS
.Cd device ch
.Cd device ch1 target 4 unit 0
.Sh DESCRIPTION
The
.Nm
driver provides support for a
.Em SCSI
media changer.
It allows many slots of media to be multiplexed between
a number of drives.
The changer device may optionally be equipped
with a bar code reader, which reads label information attached to
the media.
.Pp
A SCSI adapter must also be separately configured into the system
before a SCSI changer 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 'Changer'
type devices will be 'attached' to the
.Nm
driver.
In
.Fx
releases prior to 2.1, the first found will be attached as
.Em ch0
and the next,
.Em ch1
etc.
Beginning in 2.1 it is possible to specify what ch unit a device should
come on line as; refer to
.Xr scsi 4
for details on kernel configuration.
.Sh KERNEL CONFIGURATION
In configuring, if an optional
.Ar count
is given in the specification, that number of SCSI media changers
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).
.Sh IOCTLS
User mode programs communicate with the changer driver through a
number of ioctls which are described below.
Changer element addresses
used in the communication between the kernel and the changer device are
mapped to zero-based logical addresses.
Element types are specified as follows:
.Bl -tag -width CHET_MT
.It Dv CHET_MT
Medium transport element (picker).
.It Dv CHET_ST
Storage element (slot).
.It Dv CHET_IE
Import/export element (portal).
.It Dv CHET_DT
Data transfer element (drive).
.El
.Pp
The following
.Xr ioctl 2
calls apply to the changer.
They are defined
in the header file
.In sys/chio.h .
.Pp
.Bl -tag -width CHIOEXCHANGE
.It Dv CHIOMOVE
.Pq Vt "struct changer_move"
Move a medium from one element to another
.Pq Sy "MOVE MEDIUM"
using the current picker.
The source and destination elements are specified
in a changer_move structure, which includes at least the following
fields:
.Bd -literal -offset indent
u_int cm_fromtype; /* element type to move from */
u_int cm_fromunit; /* logical unit of from element */
u_int cm_totype;   /* element type to move to */
u_int cm_tounit;   /* logical unit of to element */
u_int cm_flags;	   /* misc. flags */
.Ed
If the
.Dv CM_INVERT
in the
.Va cm_flags
field is set, the medium
changer is instructed to flip the medium while moving it.
.It Dv CHIOEXCHANGE
.Pq Vt "struct changer_exchange"
Move the medium located in the source element to the first destination
element, and move the medium that had been in the first destination
element to the second destination element.
In case of a simple
exchange, the source and second destination elements should be the
same.
The current picker is used to perform the operation.
The addresses of the affected elements is specified to the ioctl in a
.Vt changer_exchange
structure which includes at least the following
fields:
.Bd -literal -offset indent
u_int ce_srctype;	 /* element type of source */
u_int ce_srcunit;	 /* logical unit of source */
u_int ce_fdsttype; /* element type of first destination */
u_int ce_fdstunit; /* logical unit of first destination */
u_int ce_sdsttype; /* element type of second destination */
u_int ce_sdstunit; /* logical unit of second destination */
u_int ce_flags;	 /* misc. flags */
.Ed
In
.Va ce_flags ,
.Dv CM_INVERT1
and/or
.Dv CM_INVERT2
may be set
to flip the first or second medium during the exchange operation,
respectively.
.Pp
.Em This operation is untested .
.It Dv CHIOPOSITION
.Pq Vt "struct changer_position"
Position the current picker in front of the specified element.
The element is specified with a changer_position structure, which includes
at least the following elements:
.Bd -literal -offset indent
u_int cp_type;  /* element type */
u_int cp_unit;  /* logical unit of element */
u_int cp_flags; /* misc. flags */
.Ed
The
.Va cp_flags
field may be set to
.Dv CP_INVERT
to invert the picker during the operation.
.It Dv CHIOGPICKER
.Pq Vt int
Return the logical address of the current picker.
.It Dv CHIOSPICKER
.Pq Vt int
Select the picker specified by the given logical address.
.It Dv CHIOGPARAMS
.Pq Vt "struct changer_params"
Return the configuration parameters for the media changer.
This ioctl
fills the changer_params structure passed by the user with at least the
following fields:
.Bd -literal -offset indent
u_int cp_npickers; /* number of pickers */
u_int cp_nslots;   /* number of slots */
u_int cp_nportals; /* number of import/export portals */
u_int cp_ndrives;  /* number of drives */
.Ed
.Pp
This call can be used by applications to query the dimensions of
the jukebox before using the
.Dv CHIGSTATUS
ioctl to query the jukebox' status.
.It Dv CHIOIELEM
Perform the
.Sy INITIALIZE ELEMENT STATUS
call on the media changer device.
This forces the media changer to update its internal status
information with respect to loaded media.
It also scans any barcode labels provided that it has a label reader.
The
.Nm
driver's status is not affected by this call.
.It Dv CHIOGSTATUS
.Pq Vt "struct changer_element_status_request"
Perform the
.Sy READ ELEMENT STATUS
call on the media changer device.
This call reads the element status information of the media
changer and converts it to an array of
.Vt changer_element_status
structures.
.Pp
With each call to
.Dv CHIOGSTATUS ,
the status of one or more elements of one type may be queried.
.Pp
The application passes a
.Vt changer_element_status_request
structure to the
.Nm
driver which contains the following fields:
.Bd -literal -offset indent
u_int                          cesr_element_type;
u_int                          cesr_element_base;
u_int                          cesr_element_count;
u_int                          cesr_flags;
struct changer_element_status *cesr_element_status;
.Ed
.Pp
This structure is read by the driver to determine the type, logical
base address and number of elements for which information is to be
returned in the array of
.Vt changer_element_status
structures pointed to by the
.Va cesr_element_status field .
The application must allocate enough
memory for
.Va cesr_element_count
status structures (see below).
The
.Va cesr_flags
can optionally be set to
.Dv CESR_VOLTAGS
to indicate that volume tag (bar code) information is to be read from
the jukebox and returned.
.Pp
The
.Va cesr_element_base
and
.Va cesr_element_count
fields must be valid with respect to the physical configuration of the changer.
If they are not, the
.Dv CHIOGSTATUS
ioctl returns the
.Er EINVAL
error code.
.Pp
The information about the elements is returned in an array of
.Vt changer_element_status
structures.
This structure include at least the following fields:
.Bd -literal -offset indent
u_int            ces_addr;      /* element address in media changer */
u_char           ces_flags;     /* see CESTATUS definitions below */
u_char           ces_sensecode; /* additional sense code for element */
u_char           ces_sensequal; /* additional sense code qualifier */
u_char           ces_invert;    /* invert bit */
u_char           ces_svalid;    /* source address (ces_source) valid */
u_short          ces_source;    /* source address of medium */
changer_voltag_t ces_pvoltag;   /* primary volume tag */
changer_voltag_t ces_avoltag;   /* alternate volume tag */
u_char           ces_idvalid;   /* ces_scsi_id is valid */
u_char           ces_scsi_id;   /* SCSI id of element (if ces_idvalid is nonzero) */
u_char           ces_lunvalid;  /* ces_scsi_lun is valid */
u_char           ces_scsi_lun;  /* SCSI lun of element (if ces_lunvalid is nonzero) */
.Ed
.Pp
The
.Va ces_addr
field contains the address of the element in the
coordinate system of the media changer.
It is not used by the driver,
and should be used for diagnostic purposes only.
.Pp
The following flags are defined for the
.Va ces_flags
field:
.Bl -tag -width CESTATUS_IMPEXP
.It Dv CESTATUS_FULL
A medium is present.
.It Dv CESTATUS_IMPEXP
The medium has been deposited by the operator (and not by a picker).
.It Dv CESTATUS_EXCEPT
The element is in an exceptional state (e.g.\& invalid barcode label,
barcode not yet scanned).
.It Dv CESTATUS_ACCESS
The element is accessible by the picker.
.It Dv CESTATUS_EXENAB
The element supports medium export.
.It Dv CESTATUS_INENAB
The element supports medium import.
.El
.Pp
Note that not all flags are valid for all element types.
.El
.Sh NOTES
This version of the
.Nm
driver has been tested with a DEC TZ875 (5 slot, one DLT drive)
and a Breece Hill Q47 (60 slot, four DLT drives, barcode reader).
.Pp
Many of the features the
.Nm
driver supports are not thoroughly tested due to the fact that the
devices available for testing do not support the necessary commands.
This is true for alternate volume tags, media flipping, import/export
element handling, multiple picker operation and other things.
.Sh FILES
.Bl -tag -width /dev/ch[0-9] -compact
.It Pa /dev/ch[0-9]
device entries
.El
.Sh DIAGNOSTICS
If the media changer does not support features requested by the
.Nm
driver, it will produce both console error messages and failure return
codes to the ioctls described here.
.Sh SEE ALSO
.Xr chio 1 ,
.Xr cd 4 ,
.Xr da 4 ,
.Xr sa 4
.Sh HISTORY
The
.Nm
driver appeared in
.Bx 386 0.1 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written by
.An Jason R. Thorpe Aq thorpej@and.com
for And Communications,
.Pa http://www.and.com/ .
It was added to the system by
.An Stefan Grefen Aq grefen@goofy.zdv.uni-mainz.de
who apparently had such a device.
It was ported to CAM by
.An Kenneth Merry Aq ken@FreeBSD.org .
It was updated to support volume tags by
.An Hans Huebner Aq hans@artcom.de .
OpenPOWER on IntegriCloud