1
2README for the SCSI media changer driver
3========================================
4
5This is a driver for SCSI Medium Changer devices, which are listed
6with "Type: Medium Changer" in /proc/scsi/scsi.
7
8This is for *real* Jukeboxes.  It is *not* supported to work with
9common small CD-ROM changers, neither one-lun-per-slot SCSI changers
10nor IDE drives.
11
12Userland tools available from here:
13	http://linux.bytesex.org/misc/changer.html
14
15
16General Information
17-------------------
18
19First some words about how changers work: A changer has 2 (possibly
20more) SCSI ID's. One for the changer device which controls the robot,
21and one for the device which actually reads and writes the data. The
22later may be anything, a MOD, a CD-ROM, a tape or whatever. For the
23changer device this is a "don't care", he *only* shuffles around the
24media, nothing else.
25
26
27The SCSI changer model is complex, compared to - for example - IDE-CD
28changers. But it allows to handle nearly all possible cases. It knows
294 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 accessible 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
41None of these is limited to one: A huge Jukebox could have slots for
42123 CD-ROM's, 5 CD-ROM readers (and therefore 6 SCSI ID's: the changer
43and each CD-ROM) and 2 transport arms. No problem to handle.
44
45
46How it is implemented
47---------------------
48
49I implemented the driver as character device driver with a NetBSD-like
50ioctl interface. Just grabbed NetBSD's header file and one of the
51other linux SCSI device drivers as starting point. The interface
52should be source code compatible with NetBSD. So if there is any
53software (anybody knows ???) which supports a BSDish changer driver,
54it should work with this driver too.
55
56Over time a few more ioctls where added, volume tag support for example
57wasn't covered by the NetBSD ioctl API.
58
59
60Current State
61-------------
62
63Support for more than one transport arm is not implemented yet (and
64nobody asked for it so far...).
65
66I test and use the driver myself with a 35 slot cdrom jukebox from
67Grundig.  I got some reports telling it works ok with tape autoloaders
68(Exabyte, HP and DEC).  Some People use this driver with amanda.  It
69works fine with small (11 slots) and a huge (4 MOs, 88 slots)
70magneto-optical Jukebox.  Probably with lots of other changers too, most
71(but not all :-) people mail me only if it does *not* work...
72
73I don't have any device lists, neither black-list nor white-list.  Thus
74it is quite useless to ask me whenever a specific device is supported or
75not.  In theory every changer device which supports the SCSI-2 media
76changer command set should work out-of-the-box with this driver.  If it
77doesn't, it is a bug.  Either within the driver or within the firmware
78of the changer device.
79
80
81Using it
82--------
83
84This 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
87If the module finds the changer, it prints some messages about the
88device [ 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
90device and ID ? / LUN 1 for the robot mechanism. But Linux does *not*
91look for LUNs other than 0 as default, because there are too many
92broken 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
100Trouble?
101--------
102
103If you insmod the driver with "insmod debug=1", it will be verbose and
104prints a lot of stuff to the syslog.  Compiling the kernel with
105CONFIG_SCSI_CONSTANTS=y improves the quality of the error messages a lot
106because the kernel will translate the error codes into human-readable
107strings then.
108
109You can display these messages with the dmesg command (or check the
110logfiles).  If you email me some question because of a problem with the
111driver, please include these messages.
112
113
114Insmod options
115--------------
116
117debug=0/1
118	Enable debug messages (see above, default: 0).
119
120verbose=0/1
121	Be verbose (default: 1).
122
123init=0/1
124	Send INITIALIZE ELEMENT STATUS command to the changer
125	at insmod time (default: 1).
126
127timeout_init=<seconds>
128	timeout for the INITIALIZE ELEMENT STATUS command
129	(default: 3600).
130
131timeout_move=<seconds>
132	timeout for all other commands (default: 120).
133
134dt_id=<id1>,<id2>,...
135dt_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
140vendor_firsts=
141vendor_counts=
142vendor_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
159Credits
160-------
161
162I wrote this driver using the famous mailing-patches-around-the-world
163method.  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
170Special thanks go to
171	Martin Kuehne <martin.kuehne@bnbt.de>
172for a old, second-hand (but full functional) cdrom jukebox which I use
173to develop/test driver and tools now.
174
175Have fun,
176
177   Gerd
178
179-- 
180Gerd Knorr <kraxel@bytesex.org>
181