Documentation/scsi/scsi-changer.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ========================================
   4 README for the SCSI media changer driver
   5 ========================================
   6
   7 This is a driver for SCSI Medium Changer devices, which are listed
   8 with "Type: Medium Changer" in /proc/scsi/scsi.
   9
  10 This is for *real* Jukeboxes.  It is *not* supported to work with
  11 common small CD-ROM changers, neither one-lun-per-slot SCSI changers
  12 nor IDE drives.
  13
  14 Userland tools available from here:
  15         http://linux.bytesex.org/misc/changer.html
  16
  17
  18 General Information
  19 -------------------
  20
  21 First some words about how changers work: A changer has 2 (possibly
  22 more) SCSI ID's. One for the changer device which controls the robot,
  23 and one for the device which actually reads and writes the data. The
  24 later may be anything, a MOD, a CD-ROM, a tape or whatever. For the
  25 changer device this is a "don't care", he *only* shuffles around the
  26 media, nothing else.
  27
  28
  29 The SCSI changer model is complex, compared to - for example - IDE-CD
  30 changers. But it allows to handle nearly all possible cases. It knows
  31 4 different types of changer elements:
  32
  33   ===============   ==================================================
  34   media transport   this one shuffles around the media, i.e. the
  35                     transport arm.  Also known as "picker".
  36   storage           a slot which can hold a media.
  37   import/export     the same as above, but is accessible from outside,
  38                     i.e. there the operator (you !) can use this to
  39                     fill in and remove media from the changer.
  40                     Sometimes named "mailslot".
  41   data transfer     this is the device which reads/writes, i.e. the
  42                     CD-ROM / Tape / whatever drive.
  43   ===============   ==================================================
  44
  45 None of these is limited to one: A huge Jukebox could have slots for
  46 123 CD-ROM's, 5 CD-ROM readers (and therefore 6 SCSI ID's: the changer
  47 and each CD-ROM) and 2 transport arms. No problem to handle.
  48
  49
  50 How it is implemented
  51 ---------------------
  52
  53 I implemented the driver as character device driver with a NetBSD-like
  54 ioctl interface. Just grabbed NetBSD's header file and one of the
  55 other linux SCSI device drivers as starting point. The interface
  56 should be source code compatible with NetBSD. So if there is any
  57 software (anybody knows ???) which supports a BSDish changer driver,
  58 it should work with this driver too.
  59
  60 Over time a few more ioctls where added, volume tag support for example
  61 wasn't covered by the NetBSD ioctl API.
  62
  63
  64 Current State
  65 -------------
  66
  67 Support for more than one transport arm is not implemented yet (and
  68 nobody asked for it so far...).
  69
  70 I test and use the driver myself with a 35 slot cdrom jukebox from
  71 Grundig.  I got some reports telling it works ok with tape autoloaders
  72 (Exabyte, HP and DEC).  Some People use this driver with amanda.  It
  73 works fine with small (11 slots) and a huge (4 MOs, 88 slots)
  74 magneto-optical Jukebox.  Probably with lots of other changers too, most
  75 (but not all :-) people mail me only if it does *not* work...
  76
  77 I don't have any device lists, neither black-list nor white-list.  Thus
  78 it is quite useless to ask me whenever a specific device is supported or
  79 not.  In theory every changer device which supports the SCSI-2 media
  80 changer command set should work out-of-the-box with this driver.  If it
  81 doesn't, it is a bug.  Either within the driver or within the firmware
  82 of the changer device.
  83
  84
  85 Using it
  86 --------
  87
  88 This is a character device with major number is 86, so use
  89 "mknod /dev/sch0 c 86 0" to create the special file for the driver.
  90
  91 If the module finds the changer, it prints some messages about the
  92 device [ try "dmesg" if you don't see anything ] and should show up in
  93 /proc/devices. If not....  some changers use ID ? / LUN 0 for the
  94 device and ID ? / LUN 1 for the robot mechanism. But Linux does *not*
  95 look for LUNs other than 0 as default, because there are too many
  96 broken devices. So you can try:
  97
  98   1) echo "scsi add-single-device 0 0 ID 1" > /proc/scsi/scsi
  99      (replace ID with the SCSI-ID of the device)
 100   2) boot the kernel with "max_scsi_luns=1" on the command line
 101      (append="max_scsi_luns=1" in lilo.conf should do the trick)
 102
 103
 104 Trouble?
 105 --------
 106
 107 If you insmod the driver with "insmod debug=1", it will be verbose and
 108 prints a lot of stuff to the syslog.  Compiling the kernel with
 109 CONFIG_SCSI_CONSTANTS=y improves the quality of the error messages a lot
 110 because the kernel will translate the error codes into human-readable
 111 strings then.
 112
 113 You can display these messages with the dmesg command (or check the
 114 logfiles).  If you email me some question because of a problem with the
 115 driver, please include these messages.
 116
 117
 118 Insmod options
 119 --------------
 120
 121 debug=0/1
 122         Enable debug messages (see above, default: 0).
 123
 124 verbose=0/1
 125         Be verbose (default: 1).
 126
 127 init=0/1
 128         Send INITIALIZE ELEMENT STATUS command to the changer
 129         at insmod time (default: 1).
 130
 131 timeout_init=<seconds>
 132         timeout for the INITIALIZE ELEMENT STATUS command
 133         (default: 3600).
 134
 135 timeout_move=<seconds>
 136         timeout for all other commands (default: 120).
 137
 138 dt_id=<id1>,<id2>,... / dt_lun=<lun1>,<lun2>,...
 139         These two allow to specify the SCSI ID and LUN for the data
 140         transfer elements.  You likely don't need this as the jukebox
 141         should provide this information.  But some devices don't ...
 142
 143 vendor_firsts=, vendor_counts=, vendor_labels=
 144         These insmod options can be used to tell the driver that there
 145         are some vendor-specific element types.  Grundig for example
 146         does this.  Some jukeboxes have a printer to label fresh burned
 147         CDs, which is addressed as element 0xc000 (type 5).  To tell the
 148         driver about this vendor-specific element, use this::
 149
 150                 $ insmod ch                     \
 151                         vendor_firsts=0xc000    \
 152                         vendor_counts=1         \
 153                         vendor_labels=printer
 154
 155         All three insmod options accept up to four comma-separated
 156         values, this way you can configure the element types 5-8.
 157         You likely need the SCSI specs for the device in question to
 158         find the correct values as they are not covered by the SCSI-2
 159         standard.
 160
 161
 162 Credits
 163 -------
 164
 165 I wrote this driver using the famous mailing-patches-around-the-world
 166 method.  With (more or less) help from:
 167
 168         - Daniel Moehwald <moehwald@hdg.de>
 169         - Dane Jasper <dane@sonic.net>
 170         - R. Scott Bailey <sbailey@dsddi.eds.com>
 171         - Jonathan Corbet <corbet@lwn.net>
 172
 173 Special thanks go to
 174
 175         - Martin Kuehne <martin.kuehne@bnbt.de>
 176
 177 for a old, second-hand (but full functional) cdrom jukebox which I use
 178 to develop/test driver and tools now.
 179
 180 Have fun,
 181
 182    Gerd
 183
 184 Gerd Knorr <kraxel@bytesex.org>