1Information about USB scanners:
2================================
3
4With Linux 2.4.* you could either use the kernel scanner module or libusb to
5access USB scanners.  In Linux 2.6.4 the kernel scanner module was removed.
6Therefore with this and later kernels libusb must be used.
7
8Permissions:
9------------
10While SANE automatically uses libusb when the library and its header file were
11present during the build of sane-backends, setting permissions will require some
12attention. So if scanimage -L lists your scanner as root but not as normal user
13read on this text.
14
15Most distributions support setting permissions without much manual
16configuration. Usually you must just add the users that are allowed to access
17the scanner to group "scanner". To make that change active, the user must login
18again. For more details, see your distribution's documentation e.g. for Debian:
19README.debian.gz. If this doesn't work you you want to know more, read on.
20
21The device files used by libusb are located in /proc/bus/usb/
22(e.g. /proc/bus/usb/001/003) or in /dev/bus/usb/ (e.g. /dev/bus/usb/001/003), if
23you use udev.  The exact file name can be found out by running sane-find-scanner
24which would print "libusb:001:003" in this case.  While setting permissions with
25e.g. "chmod a+rw /proc/bus/usb/001/003" works, this change is not permanent.
26The permissions will be reset when the scanner is replugged or Linux is
27rebooted.
28
29One solution to set permissions on-the-fly is Linux udev which comes with
30current distributions. SANE comes with a udev rules file in the tools/udev
31directory which may be used by distributions or can be copied to
32/etc/udev/rules.d manually. The file format is explained on top of the file
33itself. Either you need libusb 0.1.12 or newer or USB_DEVFS_PATH=/dev/bus/usb
34must be exported as a system-wide environment variable.
35
36Older distributions may use the Linux hot-plug tools (or hotplug-ng). Your
37distribution should have set up the scripts to automatically change permissions
38correctly. Look for "libsane.usermap" and "libusbscanner" in /etc/hotplug/usb.
39If you build SANE from source you can use the hotplug script that comes with
40SANE. See the tools/hotplug/ directory in the source distribution. Please refer
41to the README in that directory for the details.
42
43Gentoo information:
44-------------------
45Gentoo users: If your USB scanner is not detected at all check that USE=usb is
46set when emerging.
47
48Information about SCSI scanners:
49================================
50
51Under Linux, your kernel must have generic SCSI support (sg) as well as a
52driver for your SCSI adapter. You may want to increase the SCSI buffer size
53to increase scan speed. Details on all of the above can be found in
54sane-scsi(5).
55
56If your SCSI and sg driver are build as moduls you will need to load them
57with modprobe:
58
59# modprobe your-driver-name
60# modprobe sg
61
62You may find error messages in /var/log/messages. Look at the documentation
63for your SCSI driver. Maybe you need to add options like the io port.
64
65Now the SCSI adapter and your scanner should be visible at /proc/scsi/scsi.
66Example:
67
68# cat /proc/scsi/scsi
69Host: scsi0 Channel: 00 Id: 06 Lun: 00
70  Vendor: SCANNER  Model:                  Rev: 2.02
71  Type:   Scanner                          ANSI SCSI revision: 01 CCS
72
73In this case the real vendor and scanner name are not shown (Mustek
74Scannexpress 12000SP) but SANE will detect it nevertheless.
75
76If your scanner is supported by SANE, scanimage -L will list it now:
77
78# scanimage -L
79device mustek:/dev/scanner' is a Mustek ScanExpress 12000SP flatbed scanner
80
81If this doesn't work you may have to add the right SCSI generic device name
82to the configuration file. This should be documented in the man page for
83your backend. To find out about the right SCSI device use sane-find-scanner:
84
85# sane-find-scanner
86found SCSI scanner "SCANNER  2.02" at /dev/scanner
87found SCSI scanner "SCANNER  2.02" at /dev/sg0
88found SCSI scanner "SCANNER  2.02" at /dev/sga
89
90It may help to set a symbolic link /dev/scanner to the respective device if
91automatic detection does not work.
92
93If you need more information on the Linux SCSI subsystem, look at
94http://www.torque.net/scsi/linux_scsi_24/index.html. Although this
95documentation is about the 2.4 kernels, large parts are also valid for
96older kernels. One important exception is the section on "Device Names
97in devfs".
98
99Adaptec 1542 SCSI adapter:
100  Using buffer sizes of more than 32768 bytes with the aha1542 driver can
101  lead to kernel panic with older kernels. To avoid this, run configure with
102  the option --enable-scsibuffersize or set the environment variable
103  SANE_SG_BUFFERSIZE to 32768 before running scanimage or another frontend,
104  or download and install the SG driver 2.1.37 or newer from
105  http://www.torque.net/sg.
106
107idescsi:
108  The Linux kernel "Emulation of a SCSI host adapter for IDE ATAPI
109  devices" (idescsi) is reported to cause problems in connection with
110  SANE. If your scanner isn't found or you encounter segmentation faults
111  try to disable idescsi.
112
113SCSI Direct IO: Recent versions of the Linux SG driver for the 2.4 kernels
114  support direct IO, i.e., the SCSI adapter's DMA chip copies data directly
115  to/from user memory. Direct IO reduces memory usage, but it can lead to
116  access conflicts, if a backend uses shared memory. SANE does not use
117  direct IO by default. If you want to use it, run
118
119	configure --enable-scsi-directio=yes
120
121Very old Linux distributions are missing the /usr/include/scsi directory.  In
122such a case, it is necessary to copy the relevant files from the kernel
123distribution.  Normally, the command:
124
125  cp -a /usr/src/linux/include/scsi /usr/include
126
127should fix this problem. Don't do this if you don't get compilation errors
128about missing SCSI headers.
129
130
131Other Information
132=================
133
134ld.so.conf configuration:
135  "/usr/local/lib/sane" or "/usr/lib/sane" MUST NOT be listed in
136  /etc/ld.so.conf. If your scanner is not detected or only Video for Linux
137  devices are found, check for one of the above lines in ld.so.conf.
138  A line "/usr/local/lib" or "/usr/lib" in ld.so.conf is ok, however.
139
140Excessive warnings "pointer of type `void *' used in arithmetic":
141  Some older versions of glibc generate these warnings not related to SANE
142  source code. To suppress these warnings do
143
144  export CFLAGS="-g -O2 -D__NO_STRING_INLINES"
145
146  and rerun configure.
147
148If you use DEC cc on Linux Alpha, you may need to set LDFLAGS="-N" to
149  be able to build sane-backends.
150
151The Intel C++ Compiler for IA32 and IA64 isn't supported yet. If you want
152  to try nevertheless, you will experience undefined references to inb
153  and outb functions. To avoid those replace #include <sys/io.h> with
154
155  #if defined(__ICC) && __ICC >= 700
156  # define __GNUC__ 2
157  #endif
158  #include <sys/io.h>
159  #if defined(__ICC) && __ICC >= 700
160  # undef __GNUC__
161  #elif defined(__ICC) && defined(HAVE_ASM_IO_H)
162  # include <asm/io.h>
163  #endif
164
165Have a lot of fun with the latest SANE backend.
166