==============================================================================
LOGITECH SCANMAN+ 400 dpi handheld scanner driver  version 0.0.3
==============================================================================
    Copyright (C) 1994  Andreas Beck <becka@hp.rz.uni-duesseldorf.de>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
==============================================================================

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 should be supported by this driver:

1. The old Logitech Scanman : A B&W-scanner fixed to 200dpi.
(Does anybody have this thing ? Can it do dithering ? At the moment this
 is treated like the Scanman32,but with fixed resolution.)

2. The (somewhat newer) Logitech Scanman32 (aka Scanman+) :
A B&W 100-400dpi scanner with 6x6 dithering (37 Colors at the expense of
1/6 resolution) available.

3. The Logitech Scanman256 :
A 100-400dpi Greyscale-Scanner with 1,4-,6- and 8-bit resolution without
dithering.
Be careful with this type of scanner - I've been told,that there are
several versions of it around (using different hardware).
I hope that this problem is fixed now,as somebody told me how to handle
this Rev-03-boards,but who knows what else is out there ...
So if the driver reports to find an "incompatible scanner-interface" you 
have another incompatible board or have the base-IO-address set wrong.In 
this case please send me your HHSCAND.SYS driver that should have been in-
cluded on your scanner software disk.

The driver will autodetect your scanner type when loading using insmod.

If the driver reports "Unknown",but works with your scanner (this will
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.

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.

I am already in contact with the authors of the M105 and A4-tech driver and 
we are trying to set up a "universal" set of ioctls for scanner-operation.
If you are interested in joining this effort (maybe you have some experience 
in such APIs) please read README.ioctl and just drop me (or Thomas or
Michael,see below) a line.

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.
	   (DMA 1 is likely to be used,if you have a SoundBlaster installed
	    ...)
	   Available IRQs are 2(9),3,4,5,7,9(2),11,12 and DMAs are 1 or 3.
	   With recent kernels (those with stacked modules support) and the
	   corresponding modutils it is possible to change these values (and 
	   the major device number,see 4) at module load-time.Please have a
	   look at "man insmod" on how to do this.The relevant variables are
	   found at the beginning of logi32.c or in the output of ksyms when
	   the driver is resident.

	3) Move scanner.h to some decent place - I suggest usr/local/include
	   Please make sure,that scanner.h is present in ONLY ONE VERSION
	   on your system.I've heard of lots of trouble when the driver was
	   compiled with another scanner.h than the scan-software.

	   If you want to compile in the PINT support (a comman UNIX scanner
	   Interface Copyright (C) 1994 Kenneth Stailey ken@spacenet.com)
	   enable the corresponding -D in the Makefile and move the
           <scanio.h> file to another decent place - please note that it
	   seems to reside in /usr/[local]/include/sys on other systems so
	   it would be a good idea to place it just there.


	   Type `make' to compile the driver.
           Type `insmod' logi32.o.

           If the loader complains about missing symbols,add them to
	   kernel/ksyms.c.
	   (Or better update your kernel as it is really out of date for
	   that driver ...)
	   
	   If kernel/ksyms.c had to be modified,you have to recompile your 
	   kernel and reboot to reflect the changes.

	4) create the device special file:
	   type `mknod -m 444 /dev/logiscan c 26 0'
	   type `ln -s /dev/logiscan /dev/scan'
	   to create a symlink to /dev/scan.

	   Recent versions of MAKEDEV should also be able to create the
	   proper device.Please note that logi32.o should be loaded BEFORE
	   using MAKEDEV,as MAKEDEV will use the information in /proc/devices
	   to detect the logitech scanner driver and to find the major it
	   resides on.For further information please read the corresponding
	   documentation.

	   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.

		 With the new kernels it is possible to have the major
		 assigned dynamically - if you want this set the define
		 to 0.Please note,that if you do this you might have to
		 re-create the device special file everytime you load the
		 driver,as the major might change.The major to be used will
		 be shown by the driver at load-time.

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

	6) try it out:

		If you have a working (s)vgalib,
		build gifscan in ./demo . If you have no svgalib,you
		lost,as the script scan.sh is no longer included with
		this package.You will have to be content with something
		like cat </dev/scan >file,until you find a nice guy who
		writes a little scanning program for you (or you'll have
		to remove all the vga stuff from gifscan to be able to
		"blind-scan" into a GIF-file).
		There is a new package out there called pbmscan that will
		scan directly into a pbm file.This needs no svgalib and is
		significantly faster than writing GIF ...
		I do not know what is out there for the PINT interface -
		please tell me of good applications using it and (if you
		can) if they work with my driver.


How to modify the parameters at load-time :
------------------------------------------------------------------------------

With the new modutils (with stacked module support) you can give the values
for the following parameters at load time,so you don't have to recompile the
driver if you want to change the settings :

Just load the driver using "insmod logi32.o LOGI_FOOBAR=%d" where %d is the
value to set the parameter to.Please refer to the insmod documentation for
more information about this feature.

Available parameters are:

LOGI_DEBUG	When compiled in debug-mode the driver will output debugging-
		info when this is set to non-zero.Otherwise this variable
		will not exist.

LOGI_MAJOR	The major number to use.0 means "let the kernel select a
		free one".

LOGI_IOBASE	The scanner base address.This has to be correct or the
		driver will fail to initialize and detect the board.

LOGI_IRQ	The IRQ the scanner uses.

LOGI_DMA	The DMA channel.


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).

For the supported ioctl functions please read README.ioctl - but be careful
the ioctl-interface is still under development and therefore likely to
change.


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.


Further help and information:
------------------------------------------------------------------------------

There is a mailing list for the driver and here is the latest info file:

>>>> info logiscan
[Last updated on: Wed Aug 10 10:41:58 1994]
                             LOGISCAN MILINGLIST
                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~
!!!IMPORTANT NOTE!!!
THIS MAILING LIST IS NOT AN OFFICIAL LOGITECH LIST!!!

.-----------------------------------------------------------------------------.
|                                                                             |
| This mailing list is set up to provide easy communication between the       |
| developers of the Logitech scanner driver for Linux (mainly Andreas Beck    |
| <becka@hp.rz.uni-duesseldorf.de>) and it's users. It may also be used to    |
| distribute new versions and patches for Andreas' or other Logitech scanner  |
| drivers for Linux.                                                          |
|                                                                             |
| If you have problems with you Logitech scanner working under a another      |
| operating system than Linux, please don't subscribe to this list. You won't |
| get any help here.                                                          |
|                                                                             |
`-----------------------------------------------------------------------------'

To subscribe to the list, send a mail to majordomo@venture.net with the
following line in the message-body:

             subscribe logiscan [return mail address, optional]

You then may send your submission to

                            logiscan@venture.net

To unsubscribe, send a mail to majordomo@venture.net with the folloing line
in the message-body:

                            unsubscribe logiscan

If you want to get this informational text, send a mail with the line

                                info logiscan

to majordomo@venture.net.

--------------------------------------------------------------------------

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.
**************************************************************************
and to
Michael Beck		beck@hp832.informatik.hu-berlin.de
who wrote the A4Tech-color-scanner-driver using the same ioctl-interface.
**************************************************************************
and to
Jan Willamowius		jan@janhh.sh.sub.de
who wrote the GS4500-scanner-driver using the same ioctl-interface.
**************************************************************************
