==============================================================================
LOGITECH SCANMAN+ 400 dpi handheld scanner driver  version 0.0.1
==============================================================================

Hi folks!

This is a driver for the LOGITECH SCANMAN+ scanner driven thru its own 
interface board. There are several Versions of this scanner around,but
at least some of them (the older SCANMAN) should be supported by this
driver,too.It will autodetect your scanner type when loading using insmod.
If the driver reports "Unknown",but works with your scanner (this might
need some code-tweaking ...) - please try to find out how to detect your
hardware and tell me what modifications are needed - I will try to include
your patch in later releases. Please DO NOT send me patches that change the
whole thing - i.e. I will not support scanners that are handled really 
different from the ones included now.
If the autodetect says "NCRSCAN" - please tell me what works and what
doesn't. I assume,that this is the grayscale-version an this is NOT
fully supported up to now - but maybe I will support it,if I find an
ALPHA tester with this scanner ...

This driver is based on information gathered by disassembling the MS-LOSS 
scanner driver supplied with the scanner. If you have any additional 
information, wishes, suggestions or bug-reports please feel free to tell 
me (see note on bug-reports below). I'm especially interested in getting 
some feedback from other scanner device driver writers.
Maybe we can agree on one interface that should be provided by all scanner
drivers in Linux, so that the colorful, X-based scan programs many people 
will write :-) will work with any scanner supported. If you've written a 
nice scanning program, please drop me a line also.


How to install:
------------------------------------------------------------------------------
	
	1) The driver is a kernel loadable module,so obviously the first 
           step in getting this thing to work is to obtain and install 
           the `modutils' package if you don't have it already.
	
	2) Now go to the src directory and have a look at the top of logi32.h.
	   Edit the defines to reflect your needs/hardware settings.
	   Please note,that only IOBASE must reflect your dip-switch-set-
           tings,IRQ and DMA will be software-selected.
	   Please use IRQs and DMA-channels not used by any other hardware.
	   Available IRQs are 2(9),3,4,5,7,9(2),11,12 and DMAs are 1 or 3.

	3) Type `make' to compile the driver.
           Type `insmod' logi32.o.
           If the loader complains about missing symbols,add them to
	   kernel/ksyms.c.Iff kernel/ksyms.c was modified,you have to 
           recompile your kernel and reboot to reflect the changes.
	   There is a patch provided with this package against Linux 1.1.9.
	   If you have another Version of Linux,you will possibly have to 
           apply it by hand.

	4) create the device special file:
	   type `mknod -m 444 /dev/scan c 26 0'

	   Note: the `26' above is the major device number.
	   	 If that one is already used on your machine
		 (the driver complains "cannot register major number" when
		 attempting to load it)
		 pick another free one and change the definition
		 of LOGI32_SCANNER_MAJOR in `logi32.h' accordingly.

	5) Copy `logi32.o' to wherever you keep your kernel modules.

	6) Copy `scanner.h' to some include directory according to your
	   taste. I suggest `/usr/local/include'.

	7) try it out:

		If you have a working (s)vgalib,
		build scandemo in ./demo or
		use the script scan.sh (NOT recommended,since the script
                cannot detect the real geometry and will therefore work
                with other drivers,too,but with unpredictable results) to 
                create raw pbm files
		and enjoy!



Some notes for programmers:
------------------------------------------------------------------------------

The driver uses DMA transfers and an IRQ to communicate with the scanner.
Both channels are settable thru software (see logi32.h for details). Since
the scanner issues an interrupt every scanline, we don't have to busy-wait
for valid data .
The driver keeps an internal (dynamically allocated) buffer . The size of this
buffer defaults to 50 scanlines (see logi32.h) but is adjustable thru an ioctl
call (see below). Note that data transfers from the scanner stay enabled until
the buffer is full, no matter whether the process using /dev/scan is currently
running or not. That means that no data gets dropped , as long as there's some
buffer space, even if your process is stopped or currently swapped out.

The driver allows you to read an arbitrary number of bytes within a single 
read(2) call, but note that the internal buffer doesn't benefit you anything
anymore if you request more bytes than fit into the buffer with a single
read(2). Normally you would read one scanline at a time when scanning in
b/w mode and maybe some few scanlines when in halftone mode. If the read(2)
call is interrupted by a signal, read(2) returns the number of bytes read
so far. I know that this differs from the `standard' behaviour of returning
-EINTR, but with a scanner it makes more sense this way (you would lose some
data already in the internal buffer otherwise). If you select(2) on the
scanner device, the device is recognized as `ready' if at least one scanline
is available in the buffer, but this can be changed also (see below).

These are the supported ioctl functions:

	HSIOCGSCT	- get scanner type (manufacturer and model)

	HSIOCGMOD	- get modeinfo struct (defined in <sys/scanner.h>)
			  the current resolution is read from the scanner
			  (this is also done when the device is opened)

	HSIOCSMOD	- set modeinfo struct by hand
			  this is only there for experimental purposes and not
			  normally used by regular apps

	HSIOCGREG
	HSIOCSREG	- allows me to play with the interface registers,
			  argument is (struct registers_struct*).
			  I don't know yet what this might be good for. May
			  disappear in the future.

	HSIOCGBUF
	HSIOCSBUF	- get/set current buffer size (in scanlines).
			  Argument is (long*). Note that the current buffer
			  content gets lost when using this function.
			  An argument of zero means release all buffer 
			  memory. If you do that, the default buffer size
			  is allocated on a subsequent read(2) call.
			  
	HSIOCSSTH
	HSIOCGSTH	- get/set current select(2) threshold (in scanlines),
			  lets you adjust how many scanlines must be in the
			  buffer before the device gets available for reading.



Some notes on bug-reports:
------------------------------------------------------------------------------

If you experience a bug, please let me know. Your bug report should include
a recipe on how to reproduce it, or at least an exact description of the
circumstances that led to it. If the bug results in a message like

	general protection: xxxx
	EIP:    0010:xxxxxxxx
	EFLAGS: xxxxxxxx
	eax: xxxxxxxx   ebx: xxxxxxxx   ecx: xxxxxxxx   edx: xxxxxxxx
	esi: xxxxxxxx   edi: xxxxxxxx   ebp: xxxxxxxx
	ds: xxxx  es: xxxx  fs: xxxx  gs: xxxx
	Pid: xx, process nr: xx
	xx xx xx xx xx xx xx xx xx xx

on your screen and/or in your system log, please duplicate it exactly,
and see,if it is in the range of the scanner-driver by comparing it to the
location where it is loaded.This is shown when doing insmod :

module `Logi32' (2 pages @ 0x0080c000) created
			   ^^^^^^^^^^ that's what I need ...

If it is NOT in that range (somewhere else in the kernel),please look up the 
EIP value (without the leading `0010:') in your zSystem.map and include the 
relevant part of your zSystem.map.
If it is,please create a map of the driver using the command 
'nm -n logi32.o >logi32.map' and include this in your report.
Please note that your bug report is worthless to me if either one of these 
two pieces of information is missing.


Bye, Andreas.

--
Andreas Beck		becka@hp.rz.uni-duesseldorf.de
Germany

**************************************************************************
Many thanks go to
Thomas Faehnle		Thomas.Faehnle@student.uni-ulm.de
who wrote the M105-scanner-driver on which this one is heavily based.
**************************************************************************
