[PATCH] USB scanner driver: updated documentation

This patch updates the documentation for the USB scanner driver. The
details:

Documentation/usb/scanner.txt:
  - Amended for linux-2.5.54
  - Added information about read_timeout
  - Added more details about /proc/bus/usb/devices
  - Added/updated links
  - Added pointers two "special" scanner drivers
  - Reordering, spell-checking, formatting
  - Used /dev/usb/scanner[0-15] instead of /dev/usbscanner[0-15]
  - Removed some basic USB configuration stuff
  - Added EHCI
  - Removed some more references to HP

Documentation/usb/scanner-hp-sane.txt:
  Removed completely. This was a very outdated text for some HP
  scanners. All of this is explained in the documentation of the
  user-space SANE tools. Links and a short explanation about SANE was
  added to scanner.txt instead.

This is the (slightly adapted) patch you already apllied for 2.4.

Documentation/usb/scanner-hp-sane.txt

-Copyright (C) 1999, 2000 David E. Nelson
-
-April 26, 2000
-
-CHANGES
-
-- Amended for Linux-2.3.99-pre6-3
-- Updated for multiple scanner support
-
-INTRODUCTION
-
-This document will hopefully provide enough info on how to get SANE
-working with a Hewlett Packard USB capable scanner using the USB
-interface.  The majority of HP Scanners support the Scanner Control
-Language (SCL) which is both published by HP and supported by SANE.
-The only HP Scanners that I'm aware of that do not support SCL are the
-4200C ,3300C, and the PhotoSmart S20.  All other HP scanners with USB
-interfaces should work (4100C, 5200C, 6200C, and 6300C) as do models
-that are derived from the models above. ie the 6350C which is a 6300C
-with a transparency adaptor included with the scanner at time of
-purchase.  Of course as HP releases new scanners this information may
-change.
-
-
-REQUIREMENTS
-
-In order to get this running you'll need USB support in your kernel in
-addition to USB Scanner support.  Please refer to scanner.txt for
-issues pertaining to Linux USB and USB Scanner support.
-
-An installed version of SANE which is available from
-http://www.mostang.com/sane/.  Testing has been performed using
-version SANE-1.0.1.  For instructions on building and installing SANE,
-refer to the various README files within the SANE distribution.
-
-The latest SANE HP backend is available from http://www.kirchgessner.net.
-At the time of this writing, version 0.83 was available.
-
-
-OK, I'VE INSTALLED SANE. SO WHAT DO I DO NOW?
-
-NOTE: $INSTALL_DIR is the location where SANE is installed.  It may be
-/usr/local, /usr, /opt or somewhere else.  If you don't know, ask your
-system administrator.
-
-1) Make sure that you have the libsane-hp.* libraries under the
-$INSTALL_DIR/lib/sane/ directory.  If you don't, then the HP backend
-was either not compiled or installed properly.
-
-2) Under the directory $INSTALL_DIR/etc/sane.d/ edit the following
-files: dll.conf, hp.conf.
-
-  dll.conf:  Make sure that the 'hp' entry is present and uncommented.
-
-  hp.conf: This should contain two lines:
-
-    /dev/usbscanner
-    option connect-device
-
-NOTE: If you are using multiple scanners, make sure to have the correct
-device, ie /dev/usbscanner0.  See scanner.txt for more info.
-
-3) You should now be able to use SANE (xscanimage or scanimage).
-
-Don't forget to read any relevant man pages regarding the usage of
-SANE.  If you have other entries uncommented in 'dll.conf', you may
-have to specify the device to (x)scanimage.  Again, `man` is your
-friend.  The xscanimage (1) man page has info on how to get 'The Gimp'
-to work with xscanimage.  Note that Gimp support must be compiled into
-SANE for it to work.  If you are dealing with a RedHat system, this
-means that you'll also need to install the gimp-devel rpm package
-prior to compiling SANE.
-
-NOTE: The issues regarding core dumping by (x)scanimage have (or seem
-to be thus far) been resolved with version 0.2+ of the USB scanner
-driver which should be available in linux-2.3.23.  If you notice
-otherwise, please contact me.
-
-David /\/elson
-dnelson@jump.net
-http://www.jump.net/~dnelson

Documentation/usb/scanner.txt

 Copyright (C) 1999, 2000 David E. Nelson <dnelson@jump.net>
+Updated 2003 by Henning Meier-Geinitz <henning@meier-geinitz.de>
 
-April 26, 2000
-
-CHANGES
-
-- Amended for linux-2.4.12
-- Updated devfs support
-- Amended for linux-2.3.99-pre6-3
-- Appended hp_scan.c to end of this README
-- Removed most references to HP
-- Updated uhci/ohci host controller info
-- Updated support for multiple scanner support
-- Updated supported scanners list
-- Updated usbdevfs info
-- Spellcheck
 
 OVERVIEW
 
-This README addresses issues regarding how to configure the kernel
-to access a USB scanner.  Although the driver was originally conceived
-for USB HP scanners, it's general enough so that it can be used with
-other scanners.  Also, one can now pass the USB Vendor and Product
-ID's using module parameters for unknown scanners.  Refer to the
-document scanner-hp-sane.txt for guidance on how to configure SANE to
-use a USB HP Scanner.
+This README addresses issues regarding how to configure the kernel to access a
+USB scanner.  Although the driver was originally conceived for USB HP
+scanners, it's general enough so that it can be used with most other USB
+scanners.  Also, one can pass the USB Vendor and Product IDs using module
+parameters for unknown scanners.
 
+There are two drivers for SCSI-over-USB scanners: 
+* The "hpusbscsi" module for Hewlett-Packard 53xx series, Hewlett-Packard 7400,
+  Minolta Scan Dual II, Minolta Elite II
+* The "microtek" module for the Microtek Scanmaker X6
 
-ADDITIONAL INFORMATION
-
-http://www.linux-usb.org/
-
-
-REQUIREMENTS
+In addition to the kernel driver, user-space tools like SANE are necessary to
+actually use the scanner.  SANE ("Scanner Access Now Easy") provides drivers
+for a variety of USB scanners.  See the appropriate SANE man page for details,
+e.g. man sane-usb and man sane-hp (for HP scanners).
 
-A host with a USB port.  Ideally, either a UHCI (Intel) or OHCI
-(Compaq and others) hardware port should work.  At the time of this
-writing, there are two UHCI drivers and one OHCI.
+NOTE: Just because a product is detected by this driver does not mean that
+applications exist that support the product.  It's in the hopes that this will
+allow developers a means to produce applications that will support the listed
+USB products.
 
-A Linux kernel with USB support enabled or a backported version to
-linux-2.2.x.  See http://www.linux-usb.org for more information on
-accomplishing this.
 
-'lspci' which is only needed to determine the type of USB hardware
-available/installed in your machine.
-
-CONFIGURATION
-
-Using `lspci -v`, determine the type of USB hardware available/installed.
-
-  If you see something like:
-
-    USB Controller: ......
-    Flags: .....
-    I/O ports at ....
-
-  Then you have a UHCI based controller.
-
-  If you see something like:
-
-     USB Controller: .....
-     Flags: ....
-     Memory at .....
-
-  Then you have a OHCI based controller.
-
-Using `make menuconfig` or your preferred method for configuring the
-kernel, select 'Support for USB', 'OHCI/UHCI' depending on your
-hardware (determined from the steps above), 'USB Scanner support', and
-'Preliminary USB device filesystem'.  Compile and install the modules
-(you may need to execute `depmod -a` to update the module
-dependencies). If any of the USB sections were compiled into the
-kernel, a reboot is necessary. NOTE: Updating the boot disk with
-'lilo' may also be required. Testing was performed only as modules,
-YMMV.
-
-Beginning with version 0.4 of the driver, up to 16 scanners can be
-connected/used simultaneously.  For devfs support, see next section.
-If you intend to use more than one scanner at a time w/o devfs support:
-
-   Add a device for the USB scanner:
-	`mknod /dev/usbscanner0 c 180 48`
-	`mknod /dev/usbscanner1 c 180 49`
-                      . 
-                      .
-	`mknod /dev/usbscanner15 c 180 63`
+ADDITIONAL INFORMATION
 
+http://www.linux-usb.org/           (General information, mailing lists, links)
+http://www.mostang.com/sane/        (SANE user-space tools)
+http://www.meier-geinitz.de/kernel/ (USB scanner driver information and patches)
 
-If you foresee using only one scanner it is best to:
-	`mknod /dev/usbscanner0 c 180 48`
-	`ln -s /dev/usbscanner0 /dev/usbscanner`
 
+REQUIREMENTS
 
-Set appropriate permissions for /dev/usbscanner[0-15] (don't forget
+A host with a USB port.  Ideally, either a UHCI (Intel), OHCI (Compaq and
+others) or EHCI hardware should work.  
+
+Using "make menuconfig" or your preferred method for configuring the kernel,
+select "Support for USB", "OHCI HCD/UHCI HCD/EHCI HCD" depending on your
+hardware, "USB Scanner support", and "USB device filesystem".  Compile and
+install the modules (you may need to execute "depmod -a" to update the module
+dependencies).  If any of the USB sections were compiled into the kernel, a
+reboot is necessary.  NOTE: Updating the boot disk with "lilo" may also be
+required.  Testing was performed only as modules, YMMV.
+
+Up to 16 scanners can be connected/used simultaneously.  If devfs support is
+enabled, see next section.  Otherwise, the device files must be created
+manually if they don't exist yet, either by MAKEDEV or mknod.
+
+MAKEDEV method:
+  cd /dev
+  MAKEDEV usb
+  Check that the device files "/dev/usb/scanner0" - "/dev/usb/scanner15" have
+  been created.
+
+mknod method:
+  mknod /dev/usb/scanner0 c 180 48
+  mknod /dev/usb/scanner1 c 180 49
+                  . 
+                  .
+  mknod /dev/usb/scanner15 c 180 63
+
+Set appropriate permissions for /dev/usb/scanner[0-15] (don't forget
 about group and world permissions).  Both read and write permissions
-are required for proper operation. For example:
-	`chmod 666 /dev/usbscanner0`
+are required for proper operation.  For example:
+  chmod 666 /dev/usb/scanner0
 
 Load the appropriate modules (if compiled as modules):
 
-  OHCI:
-    modprobe usb-ohci
-    modprobe scanner
+  modprobe ohci-hcd (or uhci-hcd, ehci-hcd)
+  modprobe scanner
 
-  UHCI:
-    modprobe usb-uhci
-    modprobe scanner
 
 DEVFS
 
 The later versions of the Linux kernel (2.4.8'ish) included a dynamic
-device filesystem call 'devfs'.  With devfs, there is no need to
+device filesystem call "devfs".  With devfs, there is no need to
 create the device files as explained above; instead, they are
 dynamically created for you.  For USB Scanner, the device is created
 in /dev/usb/scannerX where X can range from 0 to 15 depending on the
 number of scanners connected to the system.
 
-To see if you have devfs, issue the command `cat /proc/filesytems`.
-If devfs is listed you should be ready to go.  You sould also have a
-process running called 'devfsd'.  In order to make sure, issue the
-command `ps aux | grep '[d]evfsd'`.
+To see if you have devfs, issue the command "cat /proc/filesytems".
+If devfs is listed you should be ready to go.  You should also have a
+process running called "devfsd".  In order to make sure, issue the
+command "ps aux | grep '[d]evfsd'".
 
-If you would like to maintain /dev/usbscanner0 in order to maintain
-compatibility with applications, then add the following to
-/etc/devfsd.conf:
 
-REGISTER ^usb/scanner0$ CFUNCTION GLOBAL symlink usb/scanner0 usbscanner0
-UNREGISTER ^usb/scanner0$ CFUNCTION GLOBAL unlink usbscanner0
+CONCLUSION
 
-Then reset the scanner (reseat the USB connector or power cycle). This
-will create the necessary symlinks in /dev to /dev/usb.
+That's it.  SANE should now be able to access the device.  To make sure the
+device was detected, use "cat /proc/bus/usb/devices".  Your scanner should be
+listed and the line starting with "I:" should look similar to this example:
 
-CONCLUSION
+  I:  If#= 0 Alt= 0 #EPs= 2 Cls=ff(vend.) Sub=ff Prot=ff Driver=usbscanner
 
-That's it.  SANE should now be able to access the device.  
+The important part is "Driver=usbscanner".  If it reads "Driver=(none)", the
+USB scanner driver didn't recognize the scanner.  Have a look at the MODULE
+PARAMETERS section for what to do in this case.
+
+For more details on the format of "/proc/bus/usb/devices" see
+Documentation/usb/proc_usb_info.txt.
 
-There is a small test program (hp_scan.c -- appended below) that can
-be used to test the scanner device if it's an HP scanner that supports
-SCL (Scanner Control Language).  Known HP scanner that support SCL are
-the 4100, 5200, 6200, the 6300 -- note that the 4200 is *not*
-supported since it does not understand SCL; it's also strongly
-suspected that the 3300 and the PhotoSmart S20 are not SCL compliant.
-Hp_scan.c's purpose is to test the driver without having to
-retrieve/configure SANE.  Hp_scan.c will scan the entire bed and put
-the output into a file called 'out.dat' in the current directory.  The
-data in the file is raw data so it's not very useful for imaging.
 
 MESSAGES
 
 usb_control/bulk_msg: timeout -- On occasions this message will appear
-in '/var/adm/messages', on the console, or both depending on how
+in "/var/adm/messages", on the console, or both depending on how
 your system is configured.  This is a side effect that scanners are
 sometimes very slow at warming up and/or initializing.  In most cases,
 however, only several of these messages should appear and is generally
@@ -165,122 +125,91 @@ this driver doesn't account for.
 
 probe_scanner: Endpoint determination failed -- This means that the
 driver is unable to detect a supported configuration for means to
-communicate with the scanner.  See also 'probe_scanner: Undetected
-endpoint'.
+communicate with the scanner.  See also "probe_scanner: Undetected
+endpoint".
 
 funky result -- Most of the time the data flow between the computer
 and the scanner goes smoothly.  However, due to whatever reason,
 whether it be solar flares or stray neutrons, sometimes the
 communications don't work as expected.  The driver tries to handle
 most types of errors but not all.  When this message is seen,
-something weird happened.  Please contact the maintaner listed at the
-top of this file.
-
-SUPPORTED SCANNERS
-
-NOTE: Just because a product is listed here does not mean that
-applications exist that support the product.  It's in the hopes that
-this will allow developers a means to produce applications that will
-support the listed USB products.
-
-At the time of this writing, the following scanners were supported by
-scanner.c:
-
- Acer
-	 Prisa Acerscan 620U & 640U (!)
-	 Prisa AcerScan 620U (!)
- Agfa
-	 SnapScan 1212U
-	 Another SnapScan 1212U (?)
-	 SnapScan Touch
- Colorado -- See Primax/Colorado below
- Epson -- See Seiko/Epson below
- Genius
-         ColorPage-Vivid Pro
- Hewlett Packard
-	 3300C
-	 4100C
-	 4200C
-	 PhotoSmart S20
-	 5200C
-	 6200C
-	 6300C
- Microtek
-	 ScanMaker X6 - X6U
-	 Phantom 336CX - C3
-	 Phantom 336CX - C3 #2
-	 Phantom C6
-	 ScanMaker V6USL
-	 ScanMaker V6USL #2
-	 ScanMaker V6UL - SpicyU
- Mustek
-	 1200 CU
- Primax/Colorado
-	 G2-300 #1
-	 G2-600 #1
-	 G2E-300 #1
-	 ReadyScan 636i
-	 G2-300 #2
-	 G2-600 #2
-	 G2E-300 #2
-	 G2E-600
-	 Colorado USB 9600
-	 Colorado USB 19200
-	 Colorado 600u
-	 Colorado 1200u
- Seiko/Epson Corp.
-	 Perfection 636U and 636Photo
-	 Perfection 610
-	 Perfection 1200U and 1200Photo
- Umax
-	 Astra 1220U
-	 Astra 1236U
-	 Astra 2000U
-	 Astra 2200U
- Visioneer
-	 OneTouch 5300
-	 OneTouch 7600 duplicate ID (!)
-	 6100
+something weird happened.  Please contact the mailing list (see
+CONTACT section for details).
 
 
 MODULE PARAMETERS
 
 If you have a device that you wish to experiment with or try using
-this driver with, but the Vendor and Product ID's are not coded in,
+this driver with, but the Vendor and Product IDs are not coded in,
 don't despair.  If the driver was compiled as a module, you can pass
 options to the driver.  Simply add 
 
   options scanner vendor=0x#### product=0x****
 
 to the /etc/modules.conf file replacing the #'s and the *'s with the
-correct ID's.  The ID's can be retrieved from the messages file or
-using `cat /proc/bus/usb/devices`. Note that USB /proc support must be
-enabled during kernel configuration.  If the 'scanner' module is
-already loaded into memory, it must be reloaded for the module
-parameters to take effect.  In essence, `rmmod scanner; modprobe
-scanner` must be performed.
+correct IDs.  The IDs can be retrieved from the messages file or
+using "cat /proc/bus/usb/devices".
+
+If the default timeout is too low, i.e. there are frequent "timeout" messages,
+you may want to increase the timeout manually by using the parameter
+"read_timeout".  The time is given in seconds.  This is an example for
+modules.conf with a timeout of 60 seconds:
 
-**NOTE**: In later kernels (2.3.38+), a new filesystem was introduced,
-usbdevfs.  To mount the filesystem, issue the command (as root):
+  options scanner read_timeout=60
+ 
+If the "scanner" module is already loaded into memory, it must be reloaded for
+the module parameters to take effect.  In essence, "rmmod scanner; modprobe
+scanner" must be performed.
 
-  mount -t usbdevfs /proc/bus/usb /proc/bus/usb
 
-An alternative and more permanent method would be to add
+BUGS
 
-  none  /proc/bus/usb  usbdevfs  defaults  0  0
+Just look at the list of fixes in the source files. 
 
-to /etc/fstab.  This will mount usbdevfs at each reboot.  You can then
-issue `cat /proc/bus/usb/devices` to extract USB device information.
 
+CONTACT
 
-BUGS
+For asking about problems and fixes, use the linux-usb-users mailing list. For
+patches, linux-usb-devel should be used. Information on both lists can be
+found on http://www.linux-usb.org/.
 
-Just look at the list of fixes in the source files.  So, if you
-encounter any problems feel free to drop me an email.
 
-David /\/elson
-dnelson@jump.net
-http://www.jump.net/~dnelson
+CHANGES
+
+- Amended for linux-2.5.54
+- Added information about read_timeout
+- Added more details about /proc/bus/usb/devices
+- Added/updated links
+- Added pointers two "special" scanner drivers
+- Reordering, spell-checking, formatting
+- Used /dev/usb/scanner[0-15] instead of /dev/usbscanner[0-15]
+- Removed some basic USB configuration stuff
+- Added EHCI
+- Removed some more references to HP
+- Amended for linux-2.4.12
+- Updated devfs support
+- Amended for linux-2.3.99-pre6-3
+- Appended hp_scan.c to end of this README
+- Removed most references to HP
+- Updated uhci/ohci host controller info
+- Updated support for multiple scanner support
+- Updated supported scanners list
+- Updated usbdevfs info
+- Spellcheck
+
+
+HP TEST PROGRAM
+
+There is a small test program (hp_scan.c -- appended below) that can
+be used to test the scanner device if it's an HP scanner that supports
+SCL (Scanner Control Language).  Known HP scanner that support SCL are
+the 4100, 5200, 6200, the 6300 -- note that the 4200 is *not*
+supported since it does not understand SCL; it's also strongly
+suspected that the 3300 and the PhotoSmart S20 are not SCL compliant.
+Hp_scan.c's purpose is to test the driver without having to
+retrieve/configure SANE.  Hp_scan.c will scan the entire bed and put
+the output into a file called "out.dat" in the current directory.  The
+data in the file is raw data so it's not very useful for imaging.
 
 --------------- snip -- hp_scan.c -- snip ---------------
 /*
@@ -347,7 +276,7 @@ main(void) {
 		exit (1);
 	}
 	
-	if((fp=open("/dev/usbscanner", O_RDWR)) < 0) {
+	if((fp=open("/dev/usb/scanner0", O_RDWR)) < 0) {
 		perror("Unable to open scanner device");
 		exit (1);
 	}