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