MFC:
[dragonfly.git] / share / man / man4 / ch.4
blob5bc29ba51a81d7da301cc35b69a6e3b089f75d3f
1 .\" $FreeBSD: src/share/man/man4/ch.4,v 1.18.2.7 2001/08/17 13:08:37 ru Exp $
2 .\" $DragonFly: src/share/man/man4/ch.4,v 1.12 2008/05/02 02:05:05 swildner Exp $
3 .\" Copyright (c) 1996
4 .\"     Julian Elischer <julian@FreeBSD.org>.  All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\"
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .Dd May 14, 1998
29 .Dt CH 4
30 .Os
31 .Sh NAME
32 .Nm ch
33 .Nd SCSI media-changer (juke box) driver
34 .Sh SYNOPSIS
35 .Cd device ch
36 .Cd device ch1 target 4 unit 0
37 .Sh DESCRIPTION
38 The
39 .Nm
40 driver provides support for a
41 .Em SCSI
42 media changer.
43 It allows many slots of media to be multiplexed between
44 a number of drives.  The changer device may optionally be equipped
45 with a bar code reader, which reads label informationen attached to
46 the media.
47 .Pp
48 A SCSI adapter must also be separately configured into the system
49 before a SCSI changer can be configured.
50 .Pp
51 As the SCSI adapter is probed during boot, the
52 .Em SCSI
53 bus is scanned for devices.
54 Any devices found which answer as 'Changer'
55 type devices will be 'attached' to the
56 .Nm
57 driver.
58 It is possible to specify what
59 .Nm
60 unit a device should
61 come on line as; refer to
62 .Xr scsi 4
63 for details on kernel configuration.
64 .Sh KERNEL CONFIGURATION
65 In configuring, if an optional
66 .Ar count
67 is given in the specification, that number of SCSI media changers
68 are configured; Most storage for them is allocated only when found
69 so a large number of configured devices is cheap.
70 (once the first
71 has included the driver).
72 .Sh IOCTLS
73 User mode programs communicate with the changer driver through a
74 number of ioctls which are described below.
75 Changer element addresses
76 used in the communication between the kernel and the changer device are
77 mapped to zero-based logical addresses.
78 Element types are specified as follows:
79 .Bl -tag -width CHET_MT
80 .It Dv CHET_MT
81 Medium transport element (picker).
82 .It Dv CHET_ST
83 Storage element (slot).
84 .It Dv CHET_IE
85 Import/export element (portal).
86 .It Dv CHET_DT
87 Data transfer element (drive).
88 .El
89 .Pp
90 The following
91 .Xr ioctl 2
92 calls apply to the changer.
93 They are defined
94 in the header file
95 .In sys/chio.h .
96 .Bl -tag -width ".Dv CHIOEXCHANGE"
97 .It Dv CHIOMOVE
98 .Pq Vt "struct changer_move"
99 Move a medium from one element to another
100 .Pq Sy "MOVE MEDIUM"
101 using the current picker.
102 The source and destination elements are specified
103 in a changer_move structure, which includes at least the following
104 fields:
105 .Bd -literal -offset indent
106 u_int cm_fromtype; /* element type to move from */
107 u_int cm_fromunit; /* logical unit of from element */
108 u_int cm_totype;   /* element type to move to */
109 u_int cm_tounit;   /* logical unit of to element */
110 u_int cm_flags;    /* misc. flags */
112 If the
113 .Dv CM_INVERT
114 in the
115 .Va cm_flags
116 field is set, the medium
117 changer is instructed to flip the medium while moving it.
118 .It Dv CHIOEXCHANGE
119 .Pq Vt "struct changer_exchange"
120 Move the medium located in the source element to the first destination
121 element, and move the medium that had been in the first destination
122 element to the second destination element.
123 In case of a simple
124 exchange, the source and second destination elements should be the
125 same.
126 The current picker is used to perform the operation.
127 The addresses of the affected elements is specified to the ioctl in a
128 .Vt changer_exchange
129 structure which includes at least the following
130 fields:
131 .Bd -literal -offset indent
132 u_int ce_srctype;        /* element type of source */
133 u_int ce_srcunit;        /* logical unit of source */
134 u_int ce_fdsttype; /* element type of first destination */
135 u_int ce_fdstunit; /* logical unit of first destination */
136 u_int ce_sdsttype; /* element type of second destination */
137 u_int ce_sdstunit; /* logical unit of second destination */
138 u_int ce_flags;  /* misc. flags */
141 .Va ce_flags ,
142 .Dv CE_INVERT1
143 and/or
144 .Dv CE_INVERT2
145 may be set
146 to flip the first or second medium during the exchange operation,
147 respectively.
149 .Em This operation is untested .
150 .It Dv CHIOPOSITION
151 .Pq Vt "struct changer_position"
152 Position the current picker in front of the specified element.
153 The element is specified with a changer_position structure, which includes
154 at least the following elements:
155 .Bd -literal -offset indent
156 u_int cp_type;  /* element type */
157 u_int cp_unit;  /* logical unit of element */
158 u_int cp_flags; /* misc. flags */
161 .Va cp_flags
162 field may be set to
163 .Dv CP_INVERT
164 to invert the picker during the operation.
165 .It Dv CHIOGPICKER
166 .Pq Vt int
167 Return the logical address of the current picker.
168 .It Dv CHIOSPICKER
169 .Pq Vt int
170 Select the picker specified by the given logical address.
171 .It Dv CHIOGPARAMS
172 .Pq Vt "struct changer_params"
173 Return the configuration parameters for the media changer.
174 This ioctl
175 fills the changer_params structure passed by the user with at least the
176 following fields:
177 .Bd -literal -offset indent
178 u_int cp_npickers; /* number of pickers */
179 u_int cp_nslots;   /* number of slots */
180 u_int cp_nportals; /* number of import/export portals */
181 u_int cp_ndrives;  /* number of drives */
184 This call can be used by applications to query the dimensions of
185 the jukebox before using the
186 .Dv CHIOGSTATUS
187 ioctl to query the jukebox' status.
188 .It Dv CHIOIELEM
189 Perform the
190 .Sy INITIALIZE ELEMENT STATUS
191 call on the media changer device.
192 This forces the media changer to update its internal status
193 information with respect to loaded media.
194 It also scans any barcode labels provided that it has a label reader.
197 driver's status is not affected by this call.
198 .It Dv CHIOGSTATUS
199 .Pq Vt "struct changer_element_status_request"
200 Perform the
201 .Sy READ ELEMENT STATUS
202 call on the media changer device.
203 This call reads the element status information of the media
204 changer and converts it to an array of
205 .Vt changer_element_status
206 structures.
208 With each call to
209 .Dv CHIOGSTATUS ,
210 the status of one or more elements of one type may be queried.
212 The application passes a
213 .Vt changer_element_status_request
214 structure to the
216 driver which contains the following fields:
217 .Bd -literal -offset indent
218 u_int                          cesr_element_type;
219 u_int                          cesr_element_base;
220 u_int                          cesr_element_count;
221 u_int                          cesr_flags;
222 struct changer_element_status *cesr_element_status;
225 This structure is read by the driver to determine the type, logical
226 base address and number of elements for which information is to be
227 returned in the array of
228 .Vt changer_element_status
229 structures pointed to by the
230 .Va cesr_element_status field .
231 The application must allocate enough
232 memory for
233 .Va cesr_element_count
234 status structures (see below).
236 .Va cesr_flags
237 can optionally be set to
238 .Dv CESR_VOLTAGS
239 to indicate that volume tag (bar code) information is to be read from
240 the jukebox and returned.
243 .Va cesr_element_base
245 .Va cesr_element_count
246 fields must be valid with respect to the physical configuration of the changer.
247 If they are not, the
248 .Dv CHIOGSTATUS
249 ioctl returns the
250 .Er EINVAL
251 error code.
253 The information about the elements is returned in an array of
254 .Vt changer_element_status
255 structures.
256 This structure include at least the following fields:
257 .Bd -literal -offset indent
258 u_int            ces_addr;      /* element address in media changer */
259 u_char           ces_flags;     /* see CESTATUS definitions below */
260 u_char           ces_sensecode; /* additional sense code for element */
261 u_char           ces_sensequal; /* additional sense code qualifier */
262 u_char           ces_invert;    /* invert bit */
263 u_char           ces_svalid;    /* source address (ces_source) valid */
264 u_short          ces_source;    /* source address of medium */
265 changer_voltag_t ces_pvoltag;   /* primary volume tag */
266 changer_voltag_t ces_avoltag;   /* alternate volume tag */
267 u_char           ces_idvalid;   /* ces_scsi_id is valid */
268 u_char           ces_scsi_id;   /* SCSI id of element (if ces_idvalid is nonzero) */
269 u_char           ces_lunvalid;  /* ces_scsi_lun is valid */
270 u_char           ces_scsi_lun;  /* SCSI lun of elemtne (if ces_lunvalid is nonzero) */
274 .Va ces_addr
275 field contains the address of the element in the
276 coordinate system of the media changer.
277 It is not used by the driver,
278 and should be used for diagnostic purposes only.
280 The following flags are defined for the
281 .Va ces_flags
282 field:
283 .Bl -tag -width CES_STATUS_IMPEXP
284 .It Dv CES_STATUS_FULL
285 A medium is present.
286 .It Dv CES_STATUS_IMPEXP
287 The medium has been deposited by the operator (and not by a picker).
288 .It Dv CES_STATUS_EXCEPT
289 The element is in an exceptional state (e.g. invalid barcode label,
290 barcode not yet scanned).
291 .It Dv CES_STATUS_ACCESS
292 The element is accessible by the picker.
293 .It Dv CES_STATUS_EXENAB
294 The element supports medium export.
295 .It Dv CES_STATUS_INENAB
296 The element supports medium import.
299 Note that not all flags are valid for all element types.
301 .Sh NOTES
302 This version of the
304 driver has been tested with a DEC TZ875 (5 slot, one DLT drive) and a
305 and a Breece Hill Q47 (60 slot, four DLT drives, barcode reader).
307 Many of the features the
309 driver supports are not thoroughly tested due to the fact that the
310 devices available for testing do not support the necessary commands.
311 This is true for alternate volume tags, media flipping, import/export
312 element handling, multiple picker operation and other things.
313 .Sh FILES
314 .Bl -tag -width /dev/ch[0-9] -compact
315 .It Pa /dev/ch[0-9]
316 device entries
318 .Sh DIAGNOSTICS
319 If the media changer does not support features requested by the
321 driver, it will produce both console error messages and failure return
322 codes to the ioctls described here.
323 .Sh SEE ALSO
324 .Xr chio 1 ,
325 .Xr cd 4 ,
326 .Xr da 4 ,
327 .Xr sa 4
328 .Sh HISTORY
331 driver appeared in
332 .Bx 386 0.1 .
333 .Sh AUTHORS
334 .An -nosplit
337 driver was written by
338 .An Jason R. Thorpe Aq thorpej@and.com
339 for And Communications,
340 .Pa http://www.and.com/ .
341 It was added to the system by
342 .An Stefan Grefen Aq grefen@goofy.zdv.uni-mainz.de
343 who apparently had such a device.
344 It was ported to CAM by
345 .An Kenneth Merry Aq ken@FreeBSD.org .
346 It was updated to support volume tags by
347 .An Hans Huebner Aq hans@artcom.de .