Fix typos in Documentation/: 'N'-'P'
[linux-3.10.git] / Documentation / scsi / scsi-changer.txt
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 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
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>