Commit daa6eda6 authored by Gerd Knorr 's avatar Gerd Knorr Committed by James Bottomley
Browse files

[SCSI] add scsi changer driver

This patch adds a device driver for scsi media changer devices.
Signed-off-by: default avatarGerd Knorr <>
Signed-off-by: default avatarJames Bottomley <>
parent 5cbf5eae
README for the SCSI media changer driver
This is a driver for SCSI Medium Changer devices, which are listed
with "Type: Medium Changer" in /proc/scsi/scsi.
This is for *real* Jukeboxes. It is *not* supported to work with
common small CD-ROM changers, neither one-lun-per-slot SCSI changers
nor IDE drives.
Userland tools available from here:
General Information
First some words about how changers work: A changer has 2 (possibly
more) SCSI ID's. One for the changer device which controls the robot,
and one for the device which actually reads and writes the data. The
later may be anything, a MOD, a CD-ROM, a tape or whatever. For the
changer device this is a "don't care", he *only* shuffles around the
media, nothing else.
The SCSI changer model is complex, compared to - for example - IDE-CD
changers. But it allows to handle nearly all possible cases. It knows
4 different types of changer elements:
media transport - this one shuffles around the media, i.e. the
transport arm. Also known as "picker".
storage - a slot which can hold a media.
import/export - the same as above, but is accessable from outside,
i.e. there the operator (you !) can use this to
fill in and remove media from the changer.
Sometimes named "mailslot".
data transfer - this is the device which reads/writes, i.e. the
CD-ROM / Tape / whatever drive.
None of these is limited to one: A huge Jukebox could have slots for
123 CD-ROM's, 5 CD-ROM readers (and therefore 6 SCSI ID's: the changer
and each CD-ROM) and 2 transport arms. No problem to handle.
How it is implemented
I implemented the driver as character device driver with a NetBSD-like
ioctl interface. Just grabbed NetBSD's header file and one of the
other linux SCSI device drivers as starting point. The interface
should be source code compatible with NetBSD. So if there is any
software (anybody knows ???) which supports a BSDish changer driver,
it should work with this driver too.
Over time a few more ioctls where added, volume tag support for example
wasn't covered by the NetBSD ioctl API.
Current State
Support for more than one transport arm is not implemented yet (and
nobody asked for it so far...).
I test and use the driver myself with a 35 slot cdrom jukebox from
Grundig. I got some reports telling it works ok with tape autoloaders
(Exabyte, HP and DEC). Some People use this driver with amanda. It
works fine with small (11 slots) and a huge (4 MOs, 88 slots)
magneto-optical Jukebox. Probably with lots of other changers too, most
(but not all :-) people mail me only if it does *not* work...
I don't have any device lists, neither black-list nor white-list. Thus
it is quite useless to ask me whenever a specific device is supported or
not. In theory every changer device which supports the SCSI-2 media
changer command set should work out-of-the-box with this driver. If it
doesn't, it is a bug. Either within the driver or within the firmware
of the changer device.
Using it
This is a character device with major number is 86, so use
"mknod /dev/sch0 c 86 0" to create the special file for the driver.
If the module finds the changer, it prints some messages about the
device [ try "dmesg" if you don't see anything ] and should show up in
/proc/devices. If not.... some changers use ID ? / LUN 0 for the
device and ID ? / LUN 1 for the robot mechanism. But Linux does *not*
look for LUN's other than 0 as default, becauce there are to many
broken devices. So you can try:
1) echo "scsi add-single-device 0 0 ID 1" > /proc/scsi/scsi
(replace ID with the SCSI-ID of the device)
2) boot the kernel with "max_scsi_luns=1" on the command line
(append="max_scsi_luns=1" in lilo.conf should do the trick)
If you insmod the driver with "insmod debug=1", it will be verbose and
prints a lot of stuff to the syslog. Compiling the kernel with
CONFIG_SCSI_CONSTANTS=y improves the quality of the error messages alot
because the kernel will translate the error codes into human-readable
strings then.
You can display these messages with the dmesg command (or check the
logfiles). If you email me some question becauce of a problem with the
driver, please include these messages.
Insmod options
Enable debug messages (see above, default: 0).
Be verbose (default: 1).
Send INITIALIZE ELEMENT STATUS command to the changer
at insmod time (default: 1).
timeout for the INITIALIZE ELEMENT STATUS command
(default: 3600).
timeout for all other commands (default: 120).
These two allow to specify the SCSI ID and LUN for the data
transfer elements. You likely don't need this as the jukebox
should provide this information. But some devices don't ...
These insmod options can be used to tell the driver that there
are some vendor-specific element types. Grundig for example
does this. Some jukeboxes have a printer to label fresh burned
CDs, which is addressed as element 0xc000 (type 5). To tell the
driver about this vendor-specific element, use this:
$ insmod ch \
vendor_firsts=0xc000 \
vendor_counts=1 \
All three insmod options accept up to four comma-separated
values, this way you can configure the element types 5-8.
You likely need the SCSI specs for the device in question to
find the correct values as they are not covered by the SCSI-2
I wrote this driver using the famous mailing-patches-around-the-world
method. With (more or less) help from:
Daniel Moehwald <>
Dane Jasper <>
R. Scott Bailey <>
Jonathan Corbet <>
Special thanks go to
Martin Kuehne <>
for a old, second-hand (but full functional) cdrom jukebox which I use
to develop/test driver and tools now.
Have fun,
Gerd Knorr <>
......@@ -137,6 +137,24 @@ config CHR_DEV_SG
If unsure, say N.
config CHR_DEV_SCH
tristate "SCSI media changer support"
depends on SCSI
This is a driver for SCSI media changers. Most common devices are
tape libraries and MOD/CDROM jukeboxes. *Real* jukeboxes, you
don't need this for those tiny 6-slot cdrom changers. Media
changers are listed as "Type: Medium Changer" in /proc/scsi/scsi.
If you have such hardware and want to use it with linux, say Y
here. Check <file:Documentation/scsi-changer.txt> for details.
If you want to compile this as a module ( = code which can be
inserted in and removed from the running kernel whenever you want),
say M here and read <file:Documentation/modules.txt> and
<file:Documentation/scsi.txt>. The module will be called ch.o.
If unsure, say N.
comment "Some SCSI devices (e.g. CD jukebox) support multiple LUNs"
depends on SCSI
......@@ -140,6 +140,7 @@ obj-$(CONFIG_CHR_DEV_OSST) += osst.o
obj-$(CONFIG_BLK_DEV_SD) += sd_mod.o
obj-$(CONFIG_BLK_DEV_SR) += sr_mod.o
obj-$(CONFIG_CHR_DEV_SG) += sg.o
obj-$(CONFIG_CHR_DEV_SCH) += ch.o
scsi_mod-y += scsi.o hosts.o scsi_ioctl.o constants.o \
scsicam.o scsi_error.o scsi_lib.o \
This diff is collapsed.
* ioctl interface for the scsi media changer driver
/* changer element types */
#define CHET_MT 0 /* media transport element (robot) */
#define CHET_ST 1 /* storage element (media slots) */
#define CHET_IE 2 /* import/export element */
#define CHET_DT 3 /* data transfer element (tape/cdrom/whatever) */
#define CHET_V1 4 /* vendor specific #1 */
#define CHET_V2 5 /* vendor specific #2 */
#define CHET_V3 6 /* vendor specific #3 */
#define CHET_V4 7 /* vendor specific #4 */
* query changer properties
* query vendor-specific element types
* accessing elements works by specifing type and unit of the element.
* for eample, storage elements are addressed with type = CHET_ST and
* unit = 0 .. cp_nslots-1
struct changer_params {
int cp_curpicker; /* current transport element */
int cp_npickers; /* number of transport elements (CHET_MT) */
int cp_nslots; /* number of storage elements (CHET_ST) */
int cp_nportals; /* number of import/export elements (CHET_IE) */
int cp_ndrives; /* number of data transfer elements (CHET_DT) */
struct changer_vendor_params {
int cvp_n1; /* number of vendor specific elems (CHET_V1) */
char cvp_label1[16];
int cvp_n2; /* number of vendor specific elems (CHET_V2) */
char cvp_label2[16];
int cvp_n3; /* number of vendor specific elems (CHET_V3) */
char cvp_label3[16];
int cvp_n4; /* number of vendor specific elems (CHET_V4) */
char cvp_label4[16];
int reserved[8];
* move a medium from one element to another
struct changer_move {
int cm_fromtype; /* type/unit of source element */
int cm_fromunit;
int cm_totype; /* type/unit of destination element */
int cm_tounit;
int cm_flags;
#define CM_INVERT 1 /* flag: rotate media (for double-sided like MOD) */
* move one medium from element #1 to element #2,
* and another one from element #2 to element #3.
* element #1 and #3 are allowed to be identical.
struct changer_exchange {
int ce_srctype; /* type/unit of element #1 */
int ce_srcunit;
int ce_fdsttype; /* type/unit of element #2 */
int ce_fdstunit;
int ce_sdsttype; /* type/unit of element #3 */
int ce_sdstunit;
int ce_flags;
#define CE_INVERT1 1
#define CE_INVERT2 2
* move the transport element (robot arm) to a specific element.
struct changer_position {
int cp_type;
int cp_unit;
int cp_flags;
#define CP_INVERT 1
* get element status for all elements of a specific type
struct changer_element_status {
int ces_type;
unsigned char *ces_data;
#define CESTATUS_FULL 0x01 /* full */
#define CESTATUS_IMPEXP 0x02 /* media was imported (inserted by sysop) */
#define CESTATUS_EXCEPT 0x04 /* error condition */
#define CESTATUS_ACCESS 0x08 /* access allowed */
#define CESTATUS_EXENAB 0x10 /* element can export media */
#define CESTATUS_INENAB 0x20 /* element can import media */
* get more detailed status informtion for a single element
struct changer_get_element {
int cge_type; /* type/unit */
int cge_unit;
int cge_status; /* status */
int cge_errno; /* errno */
int cge_srctype; /* source element of the last move/exchange */
int cge_srcunit;
int cge_id; /* scsi id (for data transfer elements) */
int cge_lun; /* scsi lun (for data transfer elements) */
char cge_pvoltag[36]; /* primary volume tag */
char cge_avoltag[36]; /* alternate volume tag */
int cge_flags;
/* flags */
#define CGE_ERRNO 0x01 /* errno available */
#define CGE_INVERT 0x02 /* media inverted */
#define CGE_SRC 0x04 /* media src available */
#define CGE_IDLUN 0x08 /* ID+LUN available */
#define CGE_PVOLTAG 0x10 /* primary volume tag available */
#define CGE_AVOLTAG 0x20 /* alternate volume tag available */
* set volume tag
struct changer_set_voltag {
int csv_type; /* type/unit */
int csv_unit;
char csv_voltag[36]; /* volume tag */
int csv_flags;
#define CSV_PVOLTAG 0x01 /* primary volume tag */
#define CSV_AVOLTAG 0x02 /* alternate volume tag */
#define CSV_CLEARTAG 0x04 /* clear volume tag */
/* ioctls */
#define CHIOMOVE _IOW('c', 1,struct changer_move)
#define CHIOEXCHANGE _IOW('c', 2,struct changer_exchange)
#define CHIOPOSITION _IOW('c', 3,struct changer_position)
#define CHIOGPICKER _IOR('c', 4,int) /* not impl. */
#define CHIOSPICKER _IOW('c', 5,int) /* not impl. */
#define CHIOGPARAMS _IOR('c', 6,struct changer_params)
#define CHIOGSTATUS _IOW('c', 8,struct changer_element_status)
#define CHIOGELEM _IOW('c',16,struct changer_get_element)
#define CHIOINITELEM _IO('c',17)
#define CHIOSVOLTAG _IOW('c',18,struct changer_set_voltag)
#define CHIOGVPARAMS _IOR('c',19,struct changer_vendor_params)
/* ---------------------------------------------------------------------- */
* Local variables:
* c-basic-offset: 8
* End:
......@@ -100,6 +100,7 @@
#define I2O_MAJOR 80 /* 80->87 */
#define SHMIQ_MAJOR 85 /* Linux/mips, SGI /dev/shmiq */
#define IDE6_MAJOR 88
#define IDE7_MAJOR 89
......@@ -41,6 +41,7 @@ extern const char *const scsi_device_types[MAX_SCSI_DEVICE_CODE];
#define FORMAT_UNIT 0x04
#define READ_BLOCK_LIMITS 0x05
#define REASSIGN_BLOCKS 0x07
#define READ_6 0x08
#define WRITE_6 0x0a
#define SEEK_6 0x0b
......@@ -65,6 +66,7 @@ extern const char *const scsi_device_types[MAX_SCSI_DEVICE_CODE];
#define READ_10 0x28
#define WRITE_10 0x2a
#define SEEK_10 0x2b
#define WRITE_VERIFY 0x2e
#define VERIFY 0x2f
#define SEARCH_HIGH 0x30
......@@ -97,6 +99,7 @@ extern const char *const scsi_device_types[MAX_SCSI_DEVICE_CODE];
#define REPORT_LUNS 0xa0
#define MOVE_MEDIUM 0xa5
#define EXCHANGE_MEDIUM 0xa6
#define READ_12 0xa8
#define WRITE_12 0xaa
#define WRITE_VERIFY_12 0xae
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment