share/man/man4/ch.4

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