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