Debian Codegraph @

upstream/debian-unstable/man5/sane-scsi.5

raw
1 .TH sane\-scsi 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy"
2 .IX sane\-scsi
3 .SH NAME
4 sane\-scsi \- SCSI adapter tips for scanners
5 .SH DESCRIPTION
6 This manual page contains various operating-system specific tips and
7 tricks on how to get scanners with a SCSI interface working.
8 .SH GENERAL INFO
9 For scanners with a SCSI interface, it may be necessary to edit the
10 appropriate backend configuration file before using SANE for the first
11 time. For most systems, the configuration file should list the name
12 of the generic SCSI device that the scanner is connected to (e.g., under
13 Linux,
14 .I /dev/sg4
15 or
16 .I /dev/sge
17 is such a generic SCSI device). It is customary to create a symlink
18 from
19 .I /dev/scanner
20 to the generic SCSI device that the scanner is connected to. In this
21 case, the configuration file simply lists the line
22 .IR /dev/scanner .
23 For a detailed description of each backend's configuration file,
24 please refer to the relevant backend manual page (e.g.,
25 .BR sane\-epson (5)
26 for Epson scanners,
27 .BR sane\-hp (5)
28 for HP scanners, etc.).
29 .PP
30 For some operating systems (e.g. Linux and OS/2), there is an alternate way of
31 specifying scanner devices. This alternate way allows one to identify scanners by
32 the SCSI vendor and model string and/or by the SCSI device address (consisting
33 of bus number, channel number, id, and logical unit number). The syntax for
34 specifying a scanner in this way is:
35 .PP
36 .RS
37 scsi
38 .I VENDOR MODEL TYPE BUS CHANNEL ID LUN
39 .RE
40 .PP
41 where
42 .I VENDOR
43 is the SCSI vendor string,
44 .I MODEL
45 is the SCSI model string,
46 .I TYPE
47 is the SCSI device type string,
48 .I BUS
49 is the SCSI bus number (named "host" in
50 .IR /proc/scsi/scsi ),
51 .I CHANNEL
52 is the SCSI channel number,
53 .I ID
54 is the SCSI id, and
55 .I LUN
56 is the logical unit number of the scanner device. The first two fields are
57 strings which must be enclosed in double-quotes if they contain any
58 whitespace. The remaining four fields are non-negative integer numbers. The
59 correct values for these fields can be found by using operating system
60 specific tools, e.g. for Linux by looking at the output of the command
61 .IR "cat /proc/scsi/scsi" .
62 To simplify configuration, a field's value can be replaced
63 with an asterisk symbol (``*''). An asterisk has the effect that any value is
64 allowed for that particular field. This can have the effect that a single
65 scsi-line matches multiple devices. When this happens, each matching device
66 will be probed by the backend one by one and registered if the backend thinks
67 it is a compatible device. For example, the line
68 .PP
69 .RS
70 scsi MUSTEK MFS\-06000CX Scanner 0 00 03 00
71 .RE
72 .PP
73 would attach the Mustek SCSI scanner with the following /proc/scsi/scsi entry:
74 .PP
75 .RS 2
76 .ft CR
77 .nf
78 Host: scsi0 Channel: 00 Id: 03 Lun: 00
79 Vendor: MUSTEK Model: MFS\-06000CX Rev: 4.04
80 Type: Scanner ANSI SCSI revision: 0
81 .fi
82 .ft R
83 .RE
84 .PP
85 Usually it's sufficient to use vendor and model strings only or even only the
86 vendor string. The following example
87 .PP
88 .RS
89 scsi MUSTEK * * * * * *
90 .RE
91 .PP
92 would have the effect that all SCSI devices in the system with a
93 vendor string of MUSTEK would be probed and recognized by the backend.
94 .PP
95 If the remainder of a scsi-string consists of asterisks only, the
96 asterisks can be omitted. For example, the following line is
97 equivalent to the one specified previously:
98 .PP
99 .RS
100 scsi MUSTEK
101 .RE
102 .PP
103 On some platforms (e.g., OpenStep), SANE device names take a special
104 form. This is explained below in the relevant platform-specific section.
105 .PP
106 When using a SCSI scanner, ensure that the access permission for the
107 generic SCSI device is set appropriately. We recommend to add a group
108 "scanner" to
109 .I /etc/group
110 which contains all users that should have
111 access to the scanner. The permission of the device should then be
112 set to allow group read and write access. For example, if the scanner
113 is at generic SCSI device
114 .IR /dev/sg0 ,
115 then the following two commands would set the permission correctly:
116 .PP
117 .RS
118 $ chgrp scanner /dev/sg0
119 .br
120 $ chmod 660 /dev/sg0
121 .br
122 .RE
123 .PP
124 When your system uses the device filesystem (devfs), you have to edit
125 .IR /etc/devfs/perms.
126 There you should search the line
127 .PP
128 .RS
129 REGISTER ^sg[^/]* PERMISSIONS root.root 0600
130 .RE
131 .PP
132 and add a new line (eg. for changing permissions of sg4):
133 .PP
134 .RS
135 REGISTER ^sg4 PERMISSIONS root.scanner 0660
136 .RE
137 .PP
138 .SH FREEBSD INFO
139 Auto-configuration using the "scsi *" lines in the config files only works if
140 the user running the frontend has read/write access to
141 .IR /dev/xpt0 .
142 Instead, you can also set a link
143 .I /dev/scanner
144 to the appropriate
145 .I /dev/uk
146 device.
147 .RS
148 .TP
149 Adaptec AHA1542CF
150 Reported to work fine under FreeBSD 2.2.2R with the
151 .B aha
152 driver.
153 .TP
154 Adaptec 2940
155 Reported to work fine under FreeBSD 2.2.2.
156 .TP
157 Adaptec 1522
158 The scanner probes ok but any attempt to
159 access it
160 .I hangs
161 the entire system. It looks like something is disabling interrupts and
162 then not re-enabling them, so it looks like a bug in the FreeBSD
163 .B aic
164 driver.
165 .TP
166 Adaptec 1505
167 Works on FreeBSD 2.2.5R and 3.0 using the
168 .B aic
169 driver, provided that Plug-and-Play support is disabled on the card.
170 If there are no
171 .I uk
172 devices, just do a
173 .I sh MAKEDEV uk0
174 in the
175 .I /dev
176 directory. The scanner should then be accessible as
177 .I /dev/uk0
178 if it was probed during boot.
179 .TP
180 Tekram DC390
181 Reported to work fine under FreeBSD 2.2.2R with the
182 .B amd
183 driver.
184 .RE
185
186 .SH LINUX INFO
187 First, make sure your kernel has SCSI generic support enabled. In
188 .IR "make xconfig" ,
189 this shows up under ``SCSI support->SCSI generic support''.
190 .PP
191
192 To keep scanning times to a minimum, it is strongly recommended to use a large
193 buffer size for the generic SCSI driver. From SG driver version 2.0 on, the
194 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
195 version 2.2.7 on. If the new SG driver is available some backends
196 (e.g.
197 .BR sane\-umax (5),
198 .BR sane\-mustek (5),
199 .BR sane\-sharp (5))
200 automatically request larger SCSI
201 buffers. If a backend does not automatically request a larger SCSI buffer, set
202 the environment variable
203 .B SANE_SG_BUFFERSIZE
204 to the desired buffer size in bytes. It is not recommended to use more
205 than 1 MB, because for large values the probability increases that the
206 SG driver cannot allocate the necessary buffer(s). For ISA cards, even
207 1 MB might be a too large value.
208 For a detailed discussion of the Linux SG SCSI driver see:
209 .IR https://tldp.org/HOWTO/SCSI-Generic-HOWTO .
210 .PP
211 For Linux kernels before version 2.2.7 the size of the buffer is only 32KB.
212 This works, but for many cheaper scanners this causes scanning to be slower by
213 about a factor of four than when using a size of 127KB. Linux defines the
214 size of this buffer by macro
215 .B SG_BIG_BUFF
216 in header file
217 .IR /usr/include/scsi/sg.h .
218 Unless a system is seriously short on memory, it is recommended to increase
219 this value to the maximum legal value of 128*1024-512=130560 bytes. After
220 changing this value, it is necessary to recompile both the kernel (or the SCSI
221 generic module) and the SCSI backends. Keep in mind that this is only
222 necessary with older Linux kernels.
223
224 .PP
225 A common issue with SCSI scanners is what to do when you booted
226 the system while the scanner was turned off. In such a case, the
227 scanner won't be recognized by the kernel and SANE won't be able
228 to access it. Fortunately, Linux provides a simple mechanism to
229 probe a SCSI device on demand. Suppose you have a scanner connected
230 to SCSI bus 2 and the scanner has a SCSI id of 5. When the system
231 is up and running and the scanner is turned on, you can issue
232 the command:
233 .PP
234 .RS
235 echo "scsi add\-single\-device 2 0 5 0" > /proc/scsi/scsi
236 .RE
237 .PP
238 and the kernel will probe and recognize your scanner (this needs to be
239 done as root). It's also possible to dynamically remove a SCSI device
240 by using the ``remove\-single\-device'' command. For details, please
241 refer to to the SCSI-2.4-HOWTO.
242 .PP
243 Scanners are known to work with the following SCSI adapters under Linux. This
244 list isn't complete, usually any SCSI adapter supported by Linux should work.
245 .PP
246 .RS
247 .TP
248 Acard/Advance SCSI adapters
249 Some old versions of the kernel driver
250 .RI ( atp870u.c )
251 cut the inquiry information.
252 Therefore the scanner couldn't be detected correctly. Use a current kernel.
253 .TP
254 Adaptec AHA-1505/AHA-1542/AHA-2940
255 Reported to work fine with Linux since v2.0. If you encounter kernel freezes
256 or other unexpected behaviour get the latest Linux kernel (2.2.17 seems to
257 work) or reduce SCSI buffer size to 32 kB.
258 .TP
259 ASUS SC200
260 Reported to work fine with Linux v2.0.
261 .TP
262 BusLogic BT958
263 To configure the BusLogic card, you may need to follow
264 these instructions (contributed by Jeremy <[email protected]>):
265 During boot, when your BusLogic adapter is being initialized, press
266 Ctrl-B to enter your BusLogic adapter setup. Choose the address which
267 your BusLogic containing your scanner is located. Choose ``SCSI Device
268 Configuration''. Choose ``Scan SCSI Bus''. Choose whatever SCSI id
269 that contains your scanner and then choose ``View/Modify SCSI
270 configuration''. Change ``Negotiation'' to ``async'' and change
271 ``Disconnect'' to ``off''. Press Esc, save, and Esc again until you
272 are asked to reboot.
273 .TP
274 NCR/Symbios 53c400/53c400a or Domex DTC3181E/L/LE (DTCT436/436P) ISA SCSI card
275 This card is supplied by Mustek (and other vendors). It's supported since
276 Linux 2.2. The SCSI cards are supported by the module g_NCR5380. It's
277 necessary to tell the kernel the io port and type of card. Example for a
278 53c400a:
279 .I "modprobe g_NCR5380 ncr_addr=0x280 ncr_53c400a=1" .
280 Once the kernel detects the card, it should work all right.
281 However, while it should work, do not expect good performance out of this
282 card---it has no interrupt line and therefore while a scan is in progress,
283 the system becomes almost unusable. You may change the values of the USLEEP
284 macros in
285 .IR drivers/scsi/g_NCR5380.c .
286 Some documentation is in this file and
287 .IR NCR5380.c .
288 .TP
289 NCR/Symbios 810
290 For some scanners it may be necessary to disable disconnect/reconnect. To
291 achieve this use the option ncr53c8xx="disc:n". Some people reported that
292 their scanner only worked with the 53c7,8xx driver, not the ncr53c8xx. Try
293 both if you have trouble.
294 .br
295 For Linux kernels before 2.0.33 it may be necessary to increase the SCSI
296 timeout. The default timeout for the Linux kernels before 2.0.33 is 10
297 seconds, which is way too low when scanning large area. If you get messages
298 of the form ``restart (ncr dead ?)'' in your
299 .I /var/log/messages
300 file or on the system console, it's an indication that the timeout is too short.
301 In this case, find the line ``if (np->latetime>10)'' in file
302 .I ncr53c8xx.c
303 (normally in directory
304 .IR /usr/src/linux/drivers/scsi )
305 and change the constant 10 to, say, 60 (one minute).
306 Then rebuild the kernel/module and try again.
307 .TP
308 Tekram DC315
309 The driver can be downloaded from
310 .IR http://www.garloff.de/kurt/linux/dc395/ .
311 For some older scanners it may be necessary to disable all the more advanced
312 features by using e.g.
313 .IR "modprobe dc395x_trm dc395x_trm=7,5,1,32" .
314 .TP
315 Tekram DC390
316 Version 1.11 of the Tekram driver seems to work fine mostly, except
317 that the scan does not terminate properly (it causes a SCSI timeout
318 after 10 minutes). The generic AM53C974 also seems to work fine
319 and does not suffer from the timeout problems.
320
321 .SH SOLARIS, OPENSTEP AND NEXTSTEP INFO
322 Under Solaris, OpenStep and NeXTStep, the generic SCSI device name
323 refers to a SCSI bus, not to an individual device. For example,
324 .I /dev/sg0
325 refers to the first SCSI bus. To tell SANE which device to use,
326 append the character 'a'+target-id to the special device name. For
327 example, the SCSI device connected to the first SCSI controller
328 and with target-id 0 would be called
329 .IR /dev/sg0a ,
330 and the device with target-id 1 on that same bus would be
331 called
332 .IR /dev/sg0b ,
333 and so on.
334
335 .SH ENVIRONMENT
336 .TP
337 .B SANE_DEBUG_SANEI_SCSI
338 If the library was compiled with debug support enabled, this environment
339 variable controls the debug level for the generic SCSI I/O subsystem. E.g., a
340 value of 128 requests all debug output to be printed by the backend. A value
341 of 255 also prints kernel messages from the SCSI subsystem (where available).
342 Smaller levels reduce verbosity.
343 .TP
344 .B SANE_SCSICMD_TIMEOUT
345 sets the timeout value for SCSI commands in seconds. Overriding the default
346 value of 120 seconds should only be necessary for very slow scanners.
347
348 .SH "SEE ALSO"
349 .BR sane (7),
350 .BR sane\-find\-scanner (1),
351 .BR sane\-"backendname" (5),
352 .BR sane\-usb (5)
353
354 .SH AUTHOR
355 David Mosberger