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.Pp 100.Bl -tag -width CHIOEXCHANGE 101.It Dv CHIOMOVE 102.Pq Vt "struct changer_move" 103Move a medium from one element to another 104.Pq Sy "MOVE MEDIUM" 105using the current picker. 106The source and destination elements are specified 107in a changer_move structure, which includes at least the following 108fields: 109.Bd -literal -offset indent 110u_int cm_fromtype; /* element type to move from */ 111u_int cm_fromunit; /* logical unit of from element */ 112u_int cm_totype; /* element type to move to */ 113u_int cm_tounit; /* logical unit of to element */ 114u_int cm_flags; /* misc. flags */ 115.Ed 116If the 117.Dv CM_INVERT 118in the 119.Va cm_flags 120field is set, the medium 121changer is instructed to flip the medium while moving it. 122.It Dv CHIOEXCHANGE 123.Pq Vt "struct changer_exchange" 124Move the medium located in the source element to the first destination 125element, and move the medium that had been in the first destination 126element to the second destination element. 127In case of a simple 128exchange, the source and second destination elements should be the 129same. 130The current picker is used to perform the operation. 131The addresses of the affected elements is specified to the ioctl in a 132.Vt changer_exchange 133structure which includes at least the following 134fields: 135.Bd -literal -offset indent 136u_int ce_srctype; /* element type of source */ 137u_int ce_srcunit; /* logical unit of source */ 138u_int ce_fdsttype; /* element type of first destination */ 139u_int ce_fdstunit; /* logical unit of first destination */ 140u_int ce_sdsttype; /* element type of second destination */ 141u_int ce_sdstunit; /* logical unit of second destination */ 142u_int ce_flags; /* misc. flags */ 143.Ed 144In 145.Va ce_flags , 146.Dv CM_INVERT1 147and/or 148.Dv CM_INVERT2 149may be set 150to flip the first or second medium during the exchange operation, 151respectively. 152.Pp 153.Em This operation is untested . 154.It Dv CHIOPOSITION 155.Pq Vt "struct changer_position" 156Position the current picker in front of the specified element. 157The element is specified with a changer_position structure, which includes 158at least the following elements: 159.Bd -literal -offset indent 160u_int cp_type; /* element type */ 161u_int cp_unit; /* logical unit of element */ 162u_int cp_flags; /* misc. flags */ 163.Ed 164The 165.Va cp_flags 166field may be set to 167.Dv CP_INVERT 168to invert the picker during the operation. 169.It Dv CHIOGPICKER 170.Pq Vt int 171Return the logical address of the current picker. 172.It Dv CHIOSPICKER 173.Pq Vt int 174Select the picker specified by the given logical address. 175.It Dv CHIOGPARAMS 176.Pq Vt "struct changer_params" 177Return the configuration parameters for the media changer. 178This ioctl 179fills the changer_params structure passed by the user with at least the 180following fields: 181.Bd -literal -offset indent 182u_int cp_npickers; /* number of pickers */ 183u_int cp_nslots; /* number of slots */ 184u_int cp_nportals; /* number of import/export portals */ 185u_int cp_ndrives; /* number of drives */ 186.Ed 187.Pp 188This call can be used by applications to query the dimensions of 189the jukebox before using the 190.Dv CHIGSTATUS 191ioctl to query the jukebox' status. 192.It Dv CHIOIELEM 193Perform the 194.Sy INITIALIZE ELEMENT STATUS 195call on the media changer device. 196This forces the media changer to update its internal status 197information with respect to loaded media. 198It also scans any barcode labels provided that it has a label reader. 199The 200.Nm 201driver's status is not affected by this call. 202.It Dv CHIOGSTATUS 203.Pq Vt "struct changer_element_status_request" 204Perform the 205.Sy READ ELEMENT STATUS 206call on the media changer device. 207This call reads the element status information of the media 208changer and converts it to an array of 209.Vt changer_element_status 210structures. 211.Pp 212With each call to 213.Dv CHIOGSTATUS , 214the status of one or more elements of one type may be queried. 215.Pp 216The application passes a 217.Vt changer_element_status_request 218structure to the 219.Nm 220driver which contains the following fields: 221.Bd -literal -offset indent 222u_int cesr_element_type; 223u_int cesr_element_base; 224u_int cesr_element_count; 225u_int cesr_flags; 226struct changer_element_status *cesr_element_status; 227.Ed 228.Pp 229This structure is read by the driver to determine the type, logical 230base address and number of elements for which information is to be 231returned in the array of 232.Vt changer_element_status 233structures pointed to by the 234.Va cesr_element_status field . 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 chio 1 , 329.Xr cd 4 , 330.Xr da 4 , 331.Xr sa 4 332.Sh HISTORY 333The 334.Nm 335driver appeared in 336.Bx 386 0.1 . 337.Sh AUTHORS 338.An -nosplit 339The 340.Nm 341driver was written by 342.An Jason R. Thorpe Aq thorpej@and.com 343for And Communications, 344.Pa http://www.and.com/ . 345It was added to the system by 346.An Stefan Grefen Aq grefen@goofy.zdv.uni-mainz.de 347who apparently had such a device. 348It was ported to CAM by 349.An Kenneth Merry Aq ken@FreeBSD.org . 350It was updated to support volume tags by 351.An Hans Huebner Aq hans@artcom.de . 352