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