diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/DocBook/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/scsidrivers.tmpl | 193 | ||||
| -rw-r--r-- | Documentation/scsi/scsi-changer.txt | 180 |
3 files changed, 181 insertions, 194 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index e69b3d2e7884..87da3478fada 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,7 +8,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ - procfs-guide.xml writing_usb_driver.xml scsidrivers.xml \ + procfs-guide.xml writing_usb_driver.xml \ sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml diff --git a/Documentation/DocBook/scsidrivers.tmpl b/Documentation/DocBook/scsidrivers.tmpl deleted file mode 100644 index d058e65daf19..000000000000 --- a/Documentation/DocBook/scsidrivers.tmpl +++ /dev/null @@ -1,193 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="scsidrivers"> - <bookinfo> - <title>SCSI Subsystem Interfaces</title> - - <authorgroup> - <author> - <firstname>Douglas</firstname> - <surname>Gilbert</surname> - <affiliation> - <address> - <email>dgilbert@interlog.com</email> - </address> - </affiliation> - </author> - </authorgroup> - <pubdate>2003-08-11</pubdate> - - <copyright> - <year>2002</year> - <year>2003</year> - <holder>Douglas Gilbert</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> -This document outlines the interface between the Linux scsi mid level -and lower level drivers. Lower level drivers are variously called HBA -(host bus adapter) drivers, host drivers (HD) or pseudo adapter drivers. -The latter alludes to the fact that a lower level driver may be a -bridge to another IO subsystem (and the "ide-scsi" driver is an example -of this). There can be many lower level drivers active in a running -system, but only one per hardware type. For example, the aic7xxx driver -controls adaptec controllers based on the 7xxx chip series. Most lower -level drivers can control one or more scsi hosts (a.k.a. scsi initiators). - </para> -<para> -This document can been found in an ASCII text file in the linux kernel -source: <filename>Documentation/scsi/scsi_mid_low_api.txt</filename> . -It currently hold a little more information than this document. The -<filename>drivers/scsi/hosts.h</filename> and <filename> -drivers/scsi/scsi.h</filename> headers contain descriptions of members -of important structures for the scsi subsystem. -</para> - </chapter> - - <chapter id="driver-struct"> - <title>Driver structure</title> - <para> -Traditionally a lower level driver for the scsi subsystem has been -at least two files in the drivers/scsi directory. For example, a -driver called "xyz" has a header file "xyz.h" and a source file -"xyz.c". [Actually there is no good reason why this couldn't all -be in one file.] Some drivers that have been ported to several operating -systems (e.g. aic7xxx which has separate files for generic and -OS-specific code) have more than two files. Such drivers tend to have -their own directory under the drivers/scsi directory. - </para> - <para> -scsi_module.c is normally included at the end of a lower -level driver. For it to work a declaration like this is needed before -it is included: -<programlisting> - static Scsi_Host_Template driver_template = DRIVER_TEMPLATE; - /* DRIVER_TEMPLATE should contain pointers to supported interface - functions. Scsi_Host_Template is defined hosts.h */ - #include "scsi_module.c" -</programlisting> - </para> - <para> -The scsi_module.c assumes the name "driver_template" is appropriately -defined. It contains 2 functions: -<orderedlist> -<listitem><para> - init_this_scsi_driver() called during builtin and module driver - initialization: invokes mid level's scsi_register_host() -</para></listitem> -<listitem><para> - exit_this_scsi_driver() called during closedown: invokes - mid level's scsi_unregister_host() -</para></listitem> -</orderedlist> - </para> -<para> -When a new, lower level driver is being added to Linux, the following -files (all found in the drivers/scsi directory) will need some attention: -Makefile, Config.help and Config.in . It is probably best to look at what -an existing lower level driver does in this regard. -</para> - </chapter> - - <chapter id="intfunctions"> - <title>Interface Functions</title> -!EDocumentation/scsi/scsi_mid_low_api.txt - </chapter> - - <chapter id="locks"> - <title>Locks</title> -<para> -Each Scsi_Host instance has a spin_lock called Scsi_Host::default_lock -which is initialized in scsi_register() [found in hosts.c]. Within the -same function the Scsi_Host::host_lock pointer is initialized to point -at default_lock with the scsi_assign_lock() function. Thereafter -lock and unlock operations performed by the mid level use the -Scsi_Host::host_lock pointer. -</para> -<para> -Lower level drivers can override the use of Scsi_Host::default_lock by -using scsi_assign_lock(). The earliest opportunity to do this would -be in the detect() function after it has invoked scsi_register(). It -could be replaced by a coarser grain lock (e.g. per driver) or a -lock of equal granularity (i.e. per host). Using finer grain locks -(e.g. per scsi device) may be possible by juggling locks in -queuecommand(). -</para> - </chapter> - - <chapter id="changes"> - <title>Changes since lk 2.4 series</title> -<para> -io_request_lock has been replaced by several finer grained locks. The lock -relevant to lower level drivers is Scsi_Host::host_lock and there is one -per scsi host. -</para> -<para> -The older error handling mechanism has been removed. This means the -lower level interface functions abort() and reset() have been removed. -</para> -<para> -In the 2.4 series the scsi subsystem configuration descriptions were -aggregated with the configuration descriptions from all other Linux -subsystems in the Documentation/Configure.help file. In the 2.5 series, -the scsi subsystem now has its own (much smaller) drivers/scsi/Config.help -file. -</para> - </chapter> - - <chapter id="credits"> - <title>Credits</title> -<para> -The following people have contributed to this document: -<orderedlist> -<listitem><para> -Mike Anderson <email>andmike@us.ibm.com</email> -</para></listitem> -<listitem><para> -James Bottomley <email>James.Bottomley@steeleye.com</email> -</para></listitem> -<listitem><para> -Patrick Mansfield <email>patmans@us.ibm.com</email> -</para></listitem> -</orderedlist> -</para> - </chapter> - -</book> diff --git a/Documentation/scsi/scsi-changer.txt b/Documentation/scsi/scsi-changer.txt new file mode 100644 index 000000000000..c132687b017a --- /dev/null +++ b/Documentation/scsi/scsi-changer.txt @@ -0,0 +1,180 @@ + +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 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) + + +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 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 +-------------- + +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=<seconds> + timeout for the INITIALIZE ELEMENT STATUS command + (default: 3600). + +timeout_move=<seconds> + timeout for all other commands (default: 120). + +dt_id=<id1>,<id2>,... +dt_lun=<lun1>,<lun2>,... + 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 <moehwald@hdg.de> + Dane Jasper <dane@sonic.net> + R. Scott Bailey <sbailey@dsddi.eds.com> + Jonathan Corbet <corbet@lwn.net> + +Special thanks go to + Martin Kuehne <martin.kuehne@bnbt.de> +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 <kraxel@bytesex.org> |
