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