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