share/man/man4/ch.4

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