summaryrefslogtreecommitdiff
path: root/README.linux
diff options
context:
space:
mode:
Diffstat (limited to 'README.linux')
-rw-r--r--README.linux287
1 files changed, 287 insertions, 0 deletions
diff --git a/README.linux b/README.linux
new file mode 100644
index 0000000..d650d48
--- /dev/null
+++ b/README.linux
@@ -0,0 +1,287 @@
+Information about USB scanners:
+================================
+
+With Linux 2.4.* you could either use the kernel scanner module or libusb to
+access USB scanners. In Linux 2.6.4 the kernel scanner module was removed.
+Therefore with this and later kernels libusb must be used.
+
+Permissions:
+------------
+While SANE automatically uses libusb when the library and its header file were
+present during the build of sane-backends, setting permissions will require some
+attention. So if scanimage -L lists your scanner as root but not as normal user
+read on this text.
+
+Most distributions support setting permissions without much manual
+configuration. Usually you must just add the users that are allowed to access
+the scanner to group "scanner". To make that change active, the user must login
+again. For more details, see your distribution's documentation e.g. for Debian:
+README.debian.gz. If this doesn't work you you want to know more, read on.
+
+The device files used by libusb are located in /proc/bus/usb/
+(e.g. /proc/bus/usb/001/003) or in /dev/bus/usb/ (e.g. /dev/bus/usb/001/003), if
+you use udev. The exact file name can be found out by running sane-find-scanner
+which would print "libusb:001:003" in this case. While setting permissions with
+e.g. "chmod a+rw /proc/bus/usb/001/003" works, this change is not permanent.
+The permissions will be reset when the scanner is replugged or Linux is
+rebooted.
+
+One solution to set permissions on-the-fly is Linux udev which comes with
+current distributions. SANE comes with a udev rules file in the tools/udev
+directory which may be used by distributions or can be copied to
+/etc/udev/rules.d manually. The file format is explained on top of the file
+itself. Either you need libusb 0.1.12 or newer or USB_DEVFS_PATH=/dev/bus/usb
+must be exported as a system-wide environment variable.
+
+Older distributions may use the Linux hot-plug tools (or hotplug-ng). Your
+distribution should have set up the scripts to automatically change permissions
+correctly. Look for "libsane.usermap" and "libusbscanner" in /etc/hotplug/usb.
+If you build SANE from source you can use the hotplug script that comes with
+SANE. See the tools/hotplug/ directory in the source distribution. Please refer
+to the README in that directory for the details.
+
+Gentoo information:
+-------------------
+Gentoo users: If your USB scanner is not detected at all check that USE=usb is
+set when emerging.
+
+Quick install:
+--------------
+
+$ ./configure
+$ make
+$ make install
+
+Step by step install on Linux 2.6.* and 3.*, both with udev:
+------------------------------------------------------------
+
+1. Install missing development packages with your prefered package manager:
+ - libusb-dev or libusb-devel or libusb-1_0-devel
+
+2. Get the latest SANE backend from git:
+ You can download "daily git snapshot" from here:
+
+ http://www.sane-project.org/snapshots/
+
+ If you prefer to use git, you can fetch a read-only copy of the git tree
+ with this command:
+
+ $ git clone git://git.debian.org/sane/sane-backends.git
+
+ If you already are using a self compiled SANE backend and just fetched a
+ new copy of the git tree or if you patched some source files, there is no
+ need to follow the installation procedure again. You only need to make and
+ install libsane:
+
+ $ make && sudo make install
+
+3. Configure, make and install latest SANE backend:
+ We install a new SANE dynamically linked shared object library in
+ /usr/local/lib beside your system's SANE library.
+
+ $ ./configure
+ $ make && sudo make install
+
+3.1. SANE library:
+ Register new installed SANE dynamically linked shared object library.
+
+ $ sudo ldconfig -v | grep libsane
+ libsane.so.1 -> libsane.so.1.0.24
+ libsane.so.1 -> libsane.so.1.0.22
+
+ This example shows that the system first find version 1.0.24 and then 1.0.22.
+ This is the correct order.
+
+ If your system first find the old version and then the new installed one,
+ then you must change the order for library paths in /etc/ld.so.conf or you
+ must create the new configuration file /etc/ld.so.conf.d/1-sane.conf.
+
+ $ echo "/usr/local/lib" | sudo tee -a /etc/ld.so.conf.d/1-sane.conf
+
+ Then you must repeat this step.
+
+3.2. Localization file:
+
+ $ cd /usr/share/locale/<language>/LC_MESSAGES
+ $ sudo ln -sf /usr/local/share/locale/<language>/LC_MESSAGES/sane-backends.mo .
+ $ cd -
+
+3.3. udev rules file:
+
+ $ sudo cp tools/udev/libsane.rules /etc/udev/rules.d
+
+ Reconnect your scanner to the USB bus to activate the new rules file.
+
+3.4. Use the scanner with normal user rights:
+
+ Your user must be a member of the group scanner.
+
+ $ cat /etc/group | grep scanner
+ scanner:x:107:<user>
+
+ Create a new group scanner, if it doesn't exist.
+
+ $ sudo addgroup scanner
+
+ Add an existing user to group scanner.
+
+ $ sudo adduser <username> scanner
+
+ After this you must logoff and login again.
+
+4. Test your scanner:
+
+4.1. Check the used backend version:
+
+ The programs must use the installed SANE backend version, e.g. 1.0.24.
+
+ $ scanimage -V
+ scanimage (sane-backends) 1.0.24git; backend version 1.0.24
+
+ This example shows that backend and scanimage are version 1.0.24.
+
+ $ /usr/bin/scanimage -V
+ scanimage (sane-backends) 1.0.20; backend version 1.0.24
+
+ This example shows that an old scanimage (1.0.20) uses the backend 1.0.24.
+
+ If you want to use xsane, start xsane and check the used version with
+ CTRL - i.
+
+4.2. Access scanner with normal user rights:
+
+ $ scanimage -L
+
+ If your scanner isn't recognised here, try this:
+
+ $ sudo scanimage -L
+
+ If this works, your user doesn't have the rights to access the scanner.
+
+ However, please check and redo the installation described above.
+ If this doesn't help, you can ask the mailing list
+ <sane-devel@lists.alioth.debian.org> for further support.
+
+4.3. Testscan:
+
+ $ cd ~
+ $ scanimage > test.pnm
+
+Information about SCSI scanners:
+================================
+
+Under Linux, your kernel must have generic SCSI support (sg) as well as a
+driver for your SCSI adapter. You may want to increase the SCSI buffer size
+to increase scan speed. Details on all of the above can be found in
+sane-scsi(5).
+
+If your SCSI and sg driver are build as moduls you will need to load them
+with modprobe:
+
+# modprobe your-driver-name
+# modprobe sg
+
+You may find error messages in /var/log/messages. Look at the documentation
+for your SCSI driver. Maybe you need to add options like the io port.
+
+Now the SCSI adapter and your scanner should be visible at /proc/scsi/scsi.
+Example:
+
+# cat /proc/scsi/scsi
+Host: scsi0 Channel: 00 Id: 06 Lun: 00
+ Vendor: SCANNER Model: Rev: 2.02
+ Type: Scanner ANSI SCSI revision: 01 CCS
+
+In this case the real vendor and scanner name are not shown (Mustek
+Scannexpress 12000SP) but SANE will detect it nevertheless.
+
+If your scanner is supported by SANE, scanimage -L will list it now:
+
+# scanimage -L
+device mustek:/dev/scanner' is a Mustek ScanExpress 12000SP flatbed scanner
+
+If this doesn't work you may have to add the right SCSI generic device name
+to the configuration file. This should be documented in the man page for
+your backend. To find out about the right SCSI device use sane-find-scanner:
+
+# sane-find-scanner
+found SCSI scanner "SCANNER 2.02" at /dev/scanner
+found SCSI scanner "SCANNER 2.02" at /dev/sg0
+found SCSI scanner "SCANNER 2.02" at /dev/sga
+
+It may help to set a symbolic link /dev/scanner to the respective device if
+automatic detection does not work.
+
+If you need more information on the Linux SCSI subsystem, look at
+http://www.torque.net/scsi/linux_scsi_24/index.html. Although this
+documentation is about the 2.4 kernels, large parts are also valid for
+older kernels. One important exception is the section on "Device Names
+in devfs".
+
+Adaptec 1542 SCSI adapter:
+ Using buffer sizes of more than 32768 bytes with the aha1542 driver can
+ lead to kernel panic with older kernels. To avoid this, run configure with
+ the option --enable-scsibuffersize or set the environment variable
+ SANE_SG_BUFFERSIZE to 32768 before running scanimage or another frontend,
+ or download and install the SG driver 2.1.37 or newer from
+ http://www.torque.net/sg.
+
+idescsi:
+ The Linux kernel "Emulation of a SCSI host adapter for IDE ATAPI
+ devices" (idescsi) is reported to cause problems in connection with
+ SANE. If your scanner isn't found or you encounter segmentation faults
+ try to disable idescsi.
+
+SCSI Direct IO: Recent versions of the Linux SG driver for the 2.4 kernels
+ support direct IO, i.e., the SCSI adapter's DMA chip copies data directly
+ to/from user memory. Direct IO reduces memory usage, but it can lead to
+ access conflicts, if a backend uses shared memory. SANE does not use
+ direct IO by default. If you want to use it, run
+
+ configure --enable-scsi-directio=yes
+
+Very old Linux distributions are missing the /usr/include/scsi directory. In
+such a case, it is necessary to copy the relevant files from the kernel
+distribution. Normally, the command:
+
+ cp -a /usr/src/linux/include/scsi /usr/include
+
+should fix this problem. Don't do this if you don't get compilation errors
+about missing SCSI headers.
+
+
+Other Information
+=================
+
+ld.so.conf configuration:
+ "/usr/local/lib/sane" or "/usr/lib/sane" MUST NOT be listed in
+ /etc/ld.so.conf. If your scanner is not detected or only Video for Linux
+ devices are found, check for one of the above lines in ld.so.conf.
+ A line "/usr/local/lib" or "/usr/lib" in ld.so.conf is ok, however.
+
+Excessive warnings "pointer of type `void *' used in arithmetic":
+ Some older versions of glibc generate these warnings not related to SANE
+ source code. To suppress these warnings do
+
+ export CFLAGS="-g -O2 -D__NO_STRING_INLINES"
+
+ and rerun configure.
+
+If you use DEC cc on Linux Alpha, you may need to set LDFLAGS="-N" to
+ be able to build sane-backends.
+
+The Intel C++ Compiler for IA32 and IA64 isn't supported yet. If you want
+ to try nevertheless, you will experience undefined references to inb
+ and outb functions. To avoid those replace #include <sys/io.h> with
+
+ #if defined(__ICC) && __ICC >= 700
+ # define __GNUC__ 2
+ #endif
+ #include <sys/io.h>
+ #if defined(__ICC) && __ICC >= 700
+ # undef __GNUC__
+ #elif defined(__ICC) && defined(HAVE_ASM_IO_H)
+ # include <asm/io.h>
+ #endif
+
+Have a lot of fun with the latest SANE backend.