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