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