0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ========================================
0004 README for the SCSI media changer driver
0005 ========================================
0006
0007 This is a driver for SCSI Medium Changer devices, which are listed
0008 with "Type: Medium Changer" in /proc/scsi/scsi.
0009
0010 This is for *real* Jukeboxes. It is *not* supported to work with
0011 common small CD-ROM changers, neither one-lun-per-slot SCSI changers
0012 nor IDE drives.
0013
0014 Userland tools available from here:
0015 http://linux.bytesex.org/misc/changer.html
0016
0017
0018 General Information
0019 -------------------
0020
0021 First some words about how changers work: A changer has 2 (possibly
0022 more) SCSI ID's. One for the changer device which controls the robot,
0023 and one for the device which actually reads and writes the data. The
0024 later may be anything, a MOD, a CD-ROM, a tape or whatever. For the
0025 changer device this is a "don't care", he *only* shuffles around the
0026 media, nothing else.
0027
0028
0029 The SCSI changer model is complex, compared to - for example - IDE-CD
0030 changers. But it allows to handle nearly all possible cases. It knows
0031 4 different types of changer elements:
0032
0033 =============== ==================================================
0034 media transport this one shuffles around the media, i.e. the
0035 transport arm. Also known as "picker".
0036 storage a slot which can hold a media.
0037 import/export the same as above, but is accessible from outside,
0038 i.e. there the operator (you !) can use this to
0039 fill in and remove media from the changer.
0040 Sometimes named "mailslot".
0041 data transfer this is the device which reads/writes, i.e. the
0042 CD-ROM / Tape / whatever drive.
0043 =============== ==================================================
0044
0045 None of these is limited to one: A huge Jukebox could have slots for
0046 123 CD-ROM's, 5 CD-ROM readers (and therefore 6 SCSI ID's: the changer
0047 and each CD-ROM) and 2 transport arms. No problem to handle.
0048
0049
0050 How it is implemented
0051 ---------------------
0052
0053 I implemented the driver as character device driver with a NetBSD-like
0054 ioctl interface. Just grabbed NetBSD's header file and one of the
0055 other linux SCSI device drivers as starting point. The interface
0056 should be source code compatible with NetBSD. So if there is any
0057 software (anybody knows ???) which supports a BSDish changer driver,
0058 it should work with this driver too.
0059
0060 Over time a few more ioctls where added, volume tag support for example
0061 wasn't covered by the NetBSD ioctl API.
0062
0063
0064 Current State
0065 -------------
0066
0067 Support for more than one transport arm is not implemented yet (and
0068 nobody asked for it so far...).
0069
0070 I test and use the driver myself with a 35 slot cdrom jukebox from
0071 Grundig. I got some reports telling it works ok with tape autoloaders
0072 (Exabyte, HP and DEC). Some People use this driver with amanda. It
0073 works fine with small (11 slots) and a huge (4 MOs, 88 slots)
0074 magneto-optical Jukebox. Probably with lots of other changers too, most
0075 (but not all :-) people mail me only if it does *not* work...
0076
0077 I don't have any device lists, neither black-list nor white-list. Thus
0078 it is quite useless to ask me whenever a specific device is supported or
0079 not. In theory every changer device which supports the SCSI-2 media
0080 changer command set should work out-of-the-box with this driver. If it
0081 doesn't, it is a bug. Either within the driver or within the firmware
0082 of the changer device.
0083
0084
0085 Using it
0086 --------
0087
0088 This is a character device with major number is 86, so use
0089 "mknod /dev/sch0 c 86 0" to create the special file for the driver.
0090
0091 If the module finds the changer, it prints some messages about the
0092 device [ try "dmesg" if you don't see anything ] and should show up in
0093 /proc/devices. If not.... some changers use ID ? / LUN 0 for the
0094 device and ID ? / LUN 1 for the robot mechanism. But Linux does *not*
0095 look for LUNs other than 0 as default, because there are too many
0096 broken devices. So you can try:
0097
0098 1) echo "scsi add-single-device 0 0 ID 1" > /proc/scsi/scsi
0099 (replace ID with the SCSI-ID of the device)
0100 2) boot the kernel with "max_scsi_luns=1" on the command line
0101 (append="max_scsi_luns=1" in lilo.conf should do the trick)
0102
0103
0104 Trouble?
0105 --------
0106
0107 If you insmod the driver with "insmod debug=1", it will be verbose and
0108 prints a lot of stuff to the syslog. Compiling the kernel with
0109 CONFIG_SCSI_CONSTANTS=y improves the quality of the error messages a lot
0110 because the kernel will translate the error codes into human-readable
0111 strings then.
0112
0113 You can display these messages with the dmesg command (or check the
0114 logfiles). If you email me some question because of a problem with the
0115 driver, please include these messages.
0116
0117
0118 Insmod options
0119 --------------
0120
0121 debug=0/1
0122 Enable debug messages (see above, default: 0).
0123
0124 verbose=0/1
0125 Be verbose (default: 1).
0126
0127 init=0/1
0128 Send INITIALIZE ELEMENT STATUS command to the changer
0129 at insmod time (default: 1).
0130
0131 timeout_init=<seconds>
0132 timeout for the INITIALIZE ELEMENT STATUS command
0133 (default: 3600).
0134
0135 timeout_move=<seconds>
0136 timeout for all other commands (default: 120).
0137
0138 dt_id=<id1>,<id2>,... / dt_lun=<lun1>,<lun2>,...
0139 These two allow to specify the SCSI ID and LUN for the data
0140 transfer elements. You likely don't need this as the jukebox
0141 should provide this information. But some devices don't ...
0142
0143 vendor_firsts=, vendor_counts=, vendor_labels=
0144 These insmod options can be used to tell the driver that there
0145 are some vendor-specific element types. Grundig for example
0146 does this. Some jukeboxes have a printer to label fresh burned
0147 CDs, which is addressed as element 0xc000 (type 5). To tell the
0148 driver about this vendor-specific element, use this::
0149
0150 $ insmod ch \
0151 vendor_firsts=0xc000 \
0152 vendor_counts=1 \
0153 vendor_labels=printer
0154
0155 All three insmod options accept up to four comma-separated
0156 values, this way you can configure the element types 5-8.
0157 You likely need the SCSI specs for the device in question to
0158 find the correct values as they are not covered by the SCSI-2
0159 standard.
0160
0161
0162 Credits
0163 -------
0164
0165 I wrote this driver using the famous mailing-patches-around-the-world
0166 method. With (more or less) help from:
0167
0168 - Daniel Moehwald <moehwald@hdg.de>
0169 - Dane Jasper <dane@sonic.net>
0170 - R. Scott Bailey <sbailey@dsddi.eds.com>
0171 - Jonathan Corbet <corbet@lwn.net>
0172
0173 Special thanks go to
0174
0175 - Martin Kuehne <martin.kuehne@bnbt.de>
0176
0177 for a old, second-hand (but full functional) cdrom jukebox which I use
0178 to develop/test driver and tools now.
0179
0180 Have fun,
0181
0182 Gerd
0183
0184 Gerd Knorr <kraxel@bytesex.org>
