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