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