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