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