diff options
Diffstat (limited to 'doc/sane-scsi.man')
| -rw-r--r-- | doc/sane-scsi.man | 328 |
1 files changed, 328 insertions, 0 deletions
diff --git a/doc/sane-scsi.man b/doc/sane-scsi.man new file mode 100644 index 0000000..c1032ee --- /dev/null +++ b/doc/sane-scsi.man @@ -0,0 +1,328 @@ +.TH sane\-scsi 5 "14 Jul 2008" "@PACKAGEVERSION@" "SANE Scanner Access Now Easy" +.IX sane\-scsi +.SH NAME +sane\-scsi \- SCSI adapter tips for scanners +.SH DESCRIPTION +This manual page contains various operating-system specific tips and +tricks on how to get scanners with a SCSI interface working. +.SH GENERAL INFO +For scanners with a SCSI interface, it may be necessary to edit the +appropriate backend configuration file before using SANE for the first +time. For most systems, the configuration file should list the name +of the generic SCSI device that the scanner is connected to (e.g., under +Linux, +.B /dev/sg4 +or +.B /dev/sge +is such a generic SCSI device). It is customary to create a symlink +from +.B /dev/scanner +to the generic SCSI device that the scanner is connected to. In this +case, the configuration file simply lists the line +.BR /dev/scanner . +For a detailed description of each backend's configuration file, +please refer to the relevant backend manual page (e.g., +.BR sane\-epson (5) +for Epson scanners, +.BR sane\-hp (5) +for HP scanners, etc.). +.PP +For some operating systems (e.g. Linux and OS/2), there is an alternate way of +specifying scanner devices. This alternate way allows to identify scanners by +the SCSI vendor and model string and/or by the SCSI device address (consisting +of bus number, channel number, id, and logical unit number). The syntax for +specifying a scanner in this way is: +.PP +.RS +scsi +.I VENDOR MODEL TYPE BUS CHANNEL ID LUN +.RE +.PP +where +.I VENDOR +is the SCSI vendor string, +.I MODEL +is the SCSI model string, +.I TYPE +is type SCSI device type string, +.I BUS +is the SCSI bus number (named "host" in /proc/scsi/scsi), +.I CHANNEL +is the SCSI channel number, +.I ID +is the SCSI id, and +.I LUN +is the logical unit number of the scanner device. The first two fields are +strings which must be enclosed in double-quotes if they contain any +whitespace. The remaining four fields are non-negative integer numbers. The +correct values for these fields can be found by using operating system +specific tools, e.g. for Linux by looking at the output of the command "cat +/proc/scsi/scsi". To simplify configuration, a field's value can be replaced +with an asterisk symbol (``*''). An asterisk has the effect that any value is +allowed for that particular field. This can have the effect that a single +scsi-line matches multiple devices. When this happens, each matching device +will be probed by the backend one by one and registered if the backend thinks +it is a compatible device. For example, the line +.PP +.RS +scsi MUSTEK MFS\-06000CX Scanner 0 00 03 00 +.RE +.PP +would attach the Mustek SCSI scanner with the following /proc/scsi/scsi entry: +.PP +.RS 2 +.ft CR +.nf +Host: scsi0 Channel: 00 Id: 03 Lun: 00 + Vendor: MUSTEK Model: MFS\-06000CX Rev: 4.04 + Type: Scanner ANSI SCSI revision: 0 +.fi +.ft R +.RE +.PP +Usually it's sufficient to use vendor and model strings only or even only the +vendor string. The following example +.PP +.RS +scsi MUSTEK * * * * * * +.RE +.PP +would have the effect that all SCSI devices in the system with a +vendor string of MUSTEK would be probed and recognized by the backend. +.PP +If the remainder of a scsi-string consists of asterisks only, the +asterisks can be omitted. For example, the following line is +equivalent to the one specified previously: +.PP +.RS +scsi MUSTEK +.RE +.PP +On some platforms (e.g., OpenStep), SANE device names take a special +form. This is explained below in the relevant platform-specific section. +.PP +When using a SCSI scanner, ensure that the access permission for the +generic SCSI device is set appropriately. We recommend to add a group +"scanner" to /etc/group which contains all users that should have +access to the scanner. The permission of the device should then be +set to allow group read and write access. For example, if the scanner +is at generic SCSI device +.BR /dev/sg0 , +then the following two commands would set the permission correctly: +.PP +.RS +$ chgrp scanner /dev/sg0 +.br +$ chmod 660 /dev/sg0 +.br +.RE +.PP +When your system uses the device filesystem (devfs), you have to edit +.BR /etc/devfs/perms. +There you should search the line +.PP +.RS +REGISTER ^sg[^/]* PERMISSIONS root.root 0600 +.RE +.PP +and add a new line (eg. for changing permissions of sg4): +.PP +.RS +REGISTER ^sg4 PERMISSIONS root.scanner 0660 +.RE +.PP +.SH FREEBSD INFO +Auto-configuration using the "scsi *" lines in the config files only works if +the user running the frontend has read/write access to /dev/xpt0. Instead, you +can also set a link +.I /dev/scanner +to the appropriate /dev/uk device. +.RS +.TP +Adaptec AHA1542CF +Reported to work fine under FreeBSD 2.2.2R with the +.B aha +driver. +.TP +Adaptec 2940 +Reported to work fine under FreeBSD 2.2.2. +.TP +Adaptec 1522 +The scanner probes ok but any attempt to +access it +.I hangs +the entire system. It looks like something is disabling interrupts and +then not re-enabling them, so it looks like a bug in the FreeBSD +.B aic +driver. +.TP +Adaptec 1505 +Works on FreeBSD 2.2.5R and 3.0 using the +.B aic +driver, provided that Plug-and-Play support is disabled on the card. +If there are no +.I uk +devices, just do a ``sh MAKEDEV uk0'' in the +.B /dev +directory. The scanner should then be accessible as +.B /dev/uk0 if it was probed +during boot. +.TP +Tekram DC390 +Reported to work fine under FreeBSD 2.2.2R with the +.B amd +driver. +.RE + +.SH LINUX INFO +First, make sure your kernel has SCSI generic support enabled. In +``make xconfig'', this shows up under ``SCSI support->SCSI generic +support''. +.PP + +To keep scanning times to a minimum, it is strongly recommended to use a large +buffer size for the generic SCSI driver. From SG driver version 2.0 on, the +maximum buffer size can be changed at program run time, and there is no restriction in size. This driver version is part of the Linux kernels from +version 2.2.7 on. If the new SG driver is available some backends +(e.g. sane\-umax, sane\-mustek, sane\-sharp) automatically request larger scsi +buffers. If a backend does not automatically request a larger scsi buffer, set +the environment variable +.B SANE_SG_BUFFERSIZE +to the desired buffer size in bytes. It is not recommended to use more +than 1 MB, because for large values the probability increases that the +SG driver cannot allocate the necessary buffer(s). For ISA cards, even +1 MB might be a too large value. For a detailed discussion of memory +issues of the SG driver, see http://www.torque.net/sg. +.PP +For Linux kernels before version 2.2.7 the size of the buffer is only 32KB. +This works, but for many cheaper scanners this causes scanning to be slower by +about a factor of four than when using a size of 127KB. Linux defines the +size of this buffer by macro +.B SG_BIG_BUFF +in header file +.IR /usr/include/scsi/sg.h . +Unless a system is seriously short on memory, it is recommended to increase +this value to the maximum legal value of 128*1024-512=130560 bytes. After +changing this value, it is necessary to recompile both the kernel (or the SCSI +generic module) and the SCSI backends. Keep in mind that this is only +necessary with older Linux kernels. + +.PP +A common issue with SCSI scanners is what to do when you booted +the system while the scanner was turned off? In such a case, the +scanner won't be recognized by the kernel and SANE won't be able +to access it. Fortunately, Linux provides a simple mechanism to +probe a SCSI device on demand. Suppose you have a scanner connected +to SCSI bus 2 and the scanner has a SCSI id of 5. When the system +is up and running and the scanner is turned on, you can issue +the command: +.PP +.RS +echo "scsi add\-single\-device 2 0 5 0" > /proc/scsi/scsi +.RE +.PP +and the kernel will probe and recognize your scanner (this needs to be +done as root). It's also possible to dynamically remove a SCSI device +by using the ``remove\-single\-device'' command. For details, please +refer to to the SCSI-2.4-HOWTO. +.PP +Scanners are known to work with the following SCSI adapters under Linux. This +list isn't complete, usually any SCSI adapter supported by Linux should work. +.PP +.RS +.TP +Acard/Advance SCSI adapters +Some old versions of the kernel driver (atp870u.c) cut the inquiry information. +Therefore the scanner couldn't be detected correctly. Use a current kernel. +.TP +Adaptec AHA-1505/AHA-1542/AHA-2940 +Reported to work fine with Linux since v2.0. If you encounter kernel freezes +or other unexpected behaviour get the latest Linux kernel (2.2.17 seems to +work) or reduce SCSI buffer size to 32 kB. +.TP +ASUS SC200 +Reported to work fine with Linux v2.0. +.TP +BusLogic BT958 +To configure the BusLogic card, you may need to follow +these instructions (contributed by Jeremy <jeremy@xxedgexx.com>): +During boot, when your BusLogic adapter is being initialized, press +Ctrl-B to enter your BusLogic adapter setup. Choose the address which +your BusLogic containing your scanner is located. Choose ``SCSI Device +Configuration''. Choose ``Scan SCSI Bus''. Choose whatever SCSI id +that contains your scanner and then choose ``View/Modify SCSI +configuration''. Change ``Negotiation'' to ``async'' and change +``Disconnect'' to ``off''. Press Esc, save, and Esc again until you +are asked to reboot. +.TP +NCR/Symbios 53c400/53c400a or Domex DTC3181E/L/LE (DTCT436/436P) ISA SCSI card +This card is supplied by Mustek (and other vendors). It's supported since +Linux 2.2. The SCSI cards are supported by the module g_NCR5380. It's +necessary to tell the kernel the io port and type of card. Example for a +53c400a: ``modprobe g_NCR5380 ncr_addr=0x280 ncr_53c400a=1''. Once the kernel +detects the card, it should work all right. However, while it should work, do +not expect good performance out of this card---it has no interrupt line and +therefore while a scan is in progress, the system becomes almost unusable. +You may change the values of the USLEEP macros in drivers/scsi/g_NCR5380.c. +Some documentation is in this file and NCR5380.c. +.TP +NCR/Symbios 810 +For some scanners it may be necessary to disable disconnect/reconnect. To +achieve this use the option ncr53c8xx="disc:n". Some people reported that +their scanner only worked with the 53c7,8xx driver, not the ncr53c8xx. Try +both if you have trouble. +.br +For Linux kernels before 2.0.33 it may be necessary to increase the SCSI +timeout. The default timeout for the Linux kernels before 2.0.33 is 10 +seconds, which is way too low when scanning large area. If you get messages +of the form ``restart (ncr dead ?)'' in your /var/log/messages file or on the +system console, it's an indication that the timeout is too short. In this +case, find the line ``if (np->latetime>10)'' in file ncr53c8xx.c (normally in +directory /usr/src/linux/drivers/scsi) and change the constant 10 to, say, 60 +(one minute). Then rebuild the kernel/module and try again. +.TP +Tekram DC315 +The driver can be downloaded from http://www.garloff.de/kurt/linux/dc395/. +For some older scanners it may be necessary to disable all the more advanced +features by using e.g. modprobe dc395x_trm dc395x_trm=7,5,1,32. +.TP +Tekram DC390 +Version 1.11 of the Tekram driver seems to work fine mostly, except +that the scan does not terminate properly (it causes a SCSI timeout +after 10 minutes). The generic AM53C974 also seems to work fine +and does not suffer from the timeout problems. + +.SH SOLARIS, OPENSTEP AND NEXTSTEP INFO +Under Solaris, OpenStep and NeXTStep, the generic SCSI device name +refers to a SCSI bus, not to an individual device. For example, +.B /dev/sg0 +refers to the first SCSI bus. To tell SANE which device to use, +append the character 'a'+target-id to the special device name. For +example, the SCSI device connected to the first SCSI controller +and with target-id 0 would be called +.BR /dev/sg0a , +and the device with target-id 1 on that same bus would be +called +.BR /dev/sg0b, +and so on. +.SH ENVIRONMENT +.TP +.B SANE_DEBUG_SANEI_SCSI +If the library was compiled with debug support enabled, this environment +variable controls the debug level for the generic SCSI I/O subsystem. E.g., a +value of 128 requests all debug output to be printed by the backend. A value +of 255 also prints kernel messages from the SCSI subsystem (where available). +Smaller levels reduce verbosity. +.TP +.B SANE_SCSICMD_TIMEOUT +sets the timeout value for SCSI commands in seconds. Overriding the default +value of 120 seconds should only be necessary for very slow scanners. + +.SH "SEE ALSO" +.BR sane (7), +.BR sane\-find\-scanner (1), +.BR sane\-"backendname" (5), +.BR sane\-usb (5) + +.SH AUTHOR +David Mosberger |