1 .\" $FreeBSD: src/share/man/man4/ch.4,v 1.18.2.7 2001/08/17 13:08:37 ru Exp $
3 .\" Julian Elischer <julian@FreeBSD.org>. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd SCSI media-changer (juke box) driver
35 .Cd device ch1 target 4 unit 0
39 driver provides support for a
42 It allows many slots of media to be multiplexed between
43 a number of drives. The changer device may optionally be equipped
44 with a bar code reader, which reads label informationen attached to
47 A SCSI adapter must also be separately configured into the system
48 before a SCSI changer can be configured.
50 As the SCSI adapter is probed during boot, the
52 bus is scanned for devices.
53 Any devices found which answer as 'Changer'
54 type devices will be 'attached' to the
59 releases prior to 2.1, the first found will be attached as
64 Beginning in 2.1 it is possible to specify what ch unit a device should
65 come on line as; refer to
67 for details on kernel configuration.
68 .Sh KERNEL CONFIGURATION
69 In configuring, if an optional
71 is given in the specification, that number of SCSI media changers
72 are configured; Most storage for them is allocated only when found
73 so a large number of configured devices is cheap.
75 has included the driver).
77 User mode programs communicate with the changer driver through a
78 number of ioctls which are described below. Changer element addresses
79 used in the communcation between the kernel and the changer device are
80 mapped to zero-based logical addresses. Element types are specified
82 .Bl -tag -width CHET_MT
84 Medium transport element (picker).
86 Storage element (slot).
88 Import/export element (portal).
90 Data transfer element (drive).
95 calls apply to the changer.
100 .Bl -tag -width CHIOEXCHANGE
102 .Pq Li "struct changer_move"
103 Move a medium from one element to another (\fBMOVE MEDIUM\fR) using
104 the current picker. The source and destination elements are specified
105 in a changer_move structure, which includes at least the following
107 .Bd -literal -offset indent
108 u_int cm_fromtype; /* element type to move from */
109 u_int cm_fromunit; /* logical unit of from element */
110 u_int cm_totype; /* element type to move to */
111 u_int cm_tounit; /* logical unit of to element */
112 u_int cm_flags; /* misc. flags */
114 If the \fBCM_INVERT\fR in the \fBcm_flags\fR field is set, the medium
115 changer is instructed to flip the medium while moving it.
117 .Pq Li "struct changer_exchange"
118 Move the medium located in the source element to the first destination
119 element, and move the medium that had been in the first destination
120 element to the second destination element. In case of a simple
121 exchange, the source and second destination elements should be the
122 same. The current picker is used to perform the operation. The
123 addresses of the affected elements is specified to the ioctl in a
124 changer_exchange structure which includes at least the following
126 .Bd -literal -offset indent
127 u_int ce_srctype; /* element type of source */
128 u_int ce_srcunit; /* logical unit of source */
129 u_int ce_fdsttype; /* element type of first destination */
130 u_int ce_fdstunit; /* logical unit of first destination */
131 u_int ce_sdsttype; /* element type of second destination */
132 u_int ce_sdstunit; /* logical unit of second destination */
133 u_int ce_flags; /* misc. flags */
135 In \fBce_flags\fR, \fBCM_INVERT1\fR and/or \fBCM_INVERT2\fR may be set
136 to flip the first or second medium during the exchange operation,
139 \fIThis operation is untested.\fR
141 .Pq Li "struct changer_position"
142 Position the current picker in front of the specified element. The
143 element is specified with a changer_position structure, which includes
144 at least the following elements:
145 .Bd -literal -offset indent
146 u_int cp_type; /* element type */
147 u_int cp_unit; /* logical unit of element */
148 u_int cp_flags; /* misc. flags */
150 The \fBcp_flags\fR field may be set to \fBCP_INVERT\fR to invert the
151 picker during the operation.
154 Return the logical address of the current picker.
157 Select the picker specified by the given logical address.
159 .Pq Li "struct changer_params"
160 Return the configuration parameters for the media changer. This ioctl
161 fills the changer_params structure passed by the user with at least the
163 .Bd -literal -offset indent
164 u_int cp_npickers; /* number of pickers */
165 u_int cp_nslots; /* number of slots */
166 u_int cp_nportals; /* number of import/export portals */
167 u_int cp_ndrives; /* number of drives */
170 This call can be used by applications to query the dimensions of
171 the jukebox before using the \fBCHIGSTATUS\fR
172 ioctl to query the jukebox' status.
174 Perform the \fBINITIALIZE ELEMENT STATUS\fR call on the media changer
175 device. This forces the media changer to update its internal status
176 information with respect to loaded media. It also scans any barcode
177 labels provided that it has a label reader. The
179 driver's status is not affected by this call.
181 .Pq Li "struct changer_element_status_request"
182 Perform the \fBREAD ELEMENT STATUS\fR call on the media changer
183 device. This call reads the element status information of the media
184 changer and converts it to an array of \fBchanger_element_status\fR
189 the status of one or more elements of one type may be queried.
191 The application passes a changer_element_status_request structure to the
193 driver which contains the following fields:
194 .Bd -literal -offset indent
195 u_int cesr_element_type;
196 u_int cesr_element_base;
197 u_int cesr_element_count;
199 struct changer_element_status *cesr_element_status;
202 This structure is read by the driver to determine the type, logical
203 base address and number of elements for which information is to be
204 returned in the array of changer_element_status structures pointed to
205 by the cesr_element_status field. The application must allocate enough
206 memory for cesr_element_count status structures (see below).
207 The cesr_flags can optionally be set to
209 to indicate that volume tag (bar code) information is to be read from
210 the jukebox and returned.
212 The cesr_element_base and cesr_element_count fields must be valid with
213 respect to the physical configuration of the changer. If they are
220 The information about the elements is returned in an array of
221 changer_element_status structures. This structure include at least
222 the following fields:
223 .Bd -literal -offset indent
224 u_int ces_addr; /* element address in media changer */
225 u_char ces_flags; /* see CESTATUS definitions below */
226 u_char ces_sensecode; /* additional sense code for element */
227 u_char ces_sensequal; /* additional sense code qualifier */
228 u_char ces_invert; /* invert bit */
229 u_char ces_svalid; /* source address (ces_source) valid */
230 u_short ces_source; /* source address of medium */
231 changer_voltag_t ces_pvoltag; /* primary volume tag */
232 changer_voltag_t ces_avoltag; /* alternate volume tag */
233 u_char ces_idvalid; /* ces_scsi_id is valid */
234 u_char ces_scsi_id; /* SCSI id of element (if ces_idvalid is nonzero) */
235 u_char ces_lunvalid; /* ces_scsi_lun is valid */
236 u_char ces_scsi_lun; /* SCSI lun of elemtne (if ces_lunvalid is nonzero) */
239 The ces_addr field contains the address of the element in the
240 coordinate system of the media changer. It is not used by the driver,
241 and should be used for diagnostic purposes only.
243 The following flags are defined for the \fBces_flags\fR field:
244 .Bl -tag -width CESTATUS_IMPEXP
247 .It Dv CESTATUS_IMPEXP
248 The medium has been deposited by the operator (and not by a picker).
249 .It Dv CESTATUS_EXCEPT
250 The element is in an exceptional state (e.g. invalid barcode label,
251 barcode not yet scanned).
252 .It Dv CESTATUS_ACCESS
253 The element is accessible by the picker.
254 .It Dv CESTATUS_EXENAB
255 The element supports medium export.
256 .It Dv CESTATUS_INENAB
257 The element supports medium import.
260 Note that not all flags are valid for all element types.
265 driver has been tested with a DEC TZ875 (5 slot, one DLT drive) and a
266 and a Breece Hill Q47 (60 slot, four DLT drives, barcode reader).
268 Many of the features the
270 driver supports are not thouroghly tested due to the fact that the
271 devices available for testing do not support the necessary commands.
272 This is true for alternate volume tags, media flipping, import/export
273 element handling, multiple picker operation and other things.
278 driver was written by
279 .An Jason R. Thorpe Aq thorpej@and.com
280 for And Communications,
281 .Pa http://www.and.com/ .
282 It was added to the system by
283 .An Stefan Grefen Aq grefen@goofy.zdv.uni-mainz.de
284 who apparently had such a device.
285 It was ported to CAM by
286 .An Kenneth Merry Aq ken@FreeBSD.org .
287 It was updated to support volume tags by
288 .An Hans Huebner Aq hans@artcom.de .
290 .Bl -tag -width /dev/ch[0-9] -compact
295 If the media changer does not support features requested by the
297 driver, it will produce both console error messages and failure return
298 codes to the ioctls described here.