From 731fc16c2fdd42d638900a4cd28c7db4beea1893 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:16:00 +0100 Subject: scsi: docs: convert scsi-changer.txt to ReST Link: https://lore.kernel.org/r/433d073fa982174a19783c2e59412b724e2cf946.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/index.rst | 1 + Documentation/scsi/scsi-changer.rst | 184 ++++++++++++++++++++++++++++++++++++ Documentation/scsi/scsi-changer.txt | 180 ----------------------------------- drivers/scsi/Kconfig | 2 +- 4 files changed, 186 insertions(+), 181 deletions(-) create mode 100644 Documentation/scsi/scsi-changer.rst delete mode 100644 Documentation/scsi/scsi-changer.txt diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 29e211ee9145..635a3b3c5e90 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -31,5 +31,6 @@ Linux SCSI Subsystem NinjaSCSI ppa qlogicfas + scsi-changer scsi_transport_srp/figures diff --git a/Documentation/scsi/scsi-changer.rst b/Documentation/scsi/scsi-changer.rst new file mode 100644 index 000000000000..ab60e7e61a6c --- /dev/null +++ b/Documentation/scsi/scsi-changer.rst @@ -0,0 +1,184 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +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: + http://linux.bytesex.org/misc/changer.html + + +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 accessible 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 LUNs other than 0 as default, because there are too 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) + + +Trouble? +-------- + +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 a lot +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 because of a problem with the +driver, please include these messages. + + +Insmod options +-------------- + +debug=0/1 + Enable debug messages (see above, default: 0). + +verbose=0/1 + Be verbose (default: 1). + +init=0/1 + Send INITIALIZE ELEMENT STATUS command to the changer + at insmod time (default: 1). + +timeout_init= + timeout for the INITIALIZE ELEMENT STATUS command + (default: 3600). + +timeout_move= + timeout for all other commands (default: 120). + +dt_id=,,... / dt_lun=,,... + 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 ... + +vendor_firsts=, vendor_counts=, vendor_labels= + 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 \ + vendor_labels=printer + + 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 + standard. + + +Credits +------- + +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 + +Gerd Knorr diff --git a/Documentation/scsi/scsi-changer.txt b/Documentation/scsi/scsi-changer.txt deleted file mode 100644 index ade046ea7c17..000000000000 --- a/Documentation/scsi/scsi-changer.txt +++ /dev/null @@ -1,180 +0,0 @@ - -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: - http://linux.bytesex.org/misc/changer.html - - -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 accessible 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 LUNs other than 0 as default, because there are too 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) - - -Trouble? --------- - -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 a lot -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 because of a problem with the -driver, please include these messages. - - -Insmod options --------------- - -debug=0/1 - Enable debug messages (see above, default: 0). - -verbose=0/1 - Be verbose (default: 1). - -init=0/1 - Send INITIALIZE ELEMENT STATUS command to the changer - at insmod time (default: 1). - -timeout_init= - timeout for the INITIALIZE ELEMENT STATUS command - (default: 3600). - -timeout_move= - timeout for all other commands (default: 120). - -dt_id=,,... -dt_lun=,,... - 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 ... - -vendor_firsts= -vendor_counts= -vendor_labels= - 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 \ - vendor_labels=printer - 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 - standard. - - -Credits -------- - -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 - --- -Gerd Knorr diff --git a/drivers/scsi/Kconfig b/drivers/scsi/Kconfig index d34c682e94cf..6cb9abb0898d 100644 --- a/drivers/scsi/Kconfig +++ b/drivers/scsi/Kconfig @@ -149,7 +149,7 @@ config CHR_DEV_SCH 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 for details. + here. Check 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), -- cgit 1.4.1