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