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