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