==============================================================================
M105 400 dpi handheld scanner driver  version 0.1.8
==============================================================================

Hi folks!

This is a driver for the Mustek M105 scanner driven thru its own interface
board equipped with a GI1904 chip. This scanner exists in at least two 
different versions: a grayscale version (with a real A/D converter) and the
halftone-only version (which lacks the ADC and thus represents gray steps in
one of some user-selectable rasters). Currently only the halftone-version is
supported, since that's all I have.
This driver is based on information gathered by disassembling the 
MS-LOSS *shiver* scan software 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 has been made loadable since this version (0.1.8),
	   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 m105.h.
	   Edit the defines to reflect your needs/hardware settings.
	   If you don't keep your kernel sources in /usr/src/linux, look at 
	   the top of the Makefile also. The only file of the kernel source
	   that gets modified is kernel/ksyms.S which contains a list of
	   kernel symbols accessible by loadable modules.

	3) Type `make' to compile the driver and add the missing symbol
	   entries to kernel/ksyms.S. Iff kernel/ksyms.S is modified,
	   you have to recompile your kernel and reboot to reflect the
	   changes, but the Makefile will tell you that if necessary.

	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 M105_SCANNER_MAJOR in `m105.h' accordingly.

	5) Copy `m105.o' to wherever you keep your kernel modules and 
	   load it by typing `insmod m105.o'.

	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 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 m105.h
for details). Since the scanner issues an interrupt every scanline, we don't
have to busy-wait for valid data. This surely doesn't go without saying
on a cheap scanner intended for use with a crippled single-user single-tasking
lousy-made completely-sucking interrupt handler package, so we're quite lucky.
The driver keeps an internal (dynamically allocated) buffer. The size of this
buffer defaults to 50 scanlines (see m105.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:

	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 gi1904_regs_struct*).
			  I don't know yet what they are 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,
look up the EIP value (without the leading `0010:') in your zSystem.map
and include the relevant part of your zSystem.map (namely, the lines with
function names starting with `m105_') as well as the message you got 
in your bug report. Please note that your bug report is worthless to me
if either one of these two pieces of information is missing.


Bye, Thomas.

--
Thomas Faehnle		Thomas.Faehnle@student.uni-ulm.de
Kellerhalde 15
89081 Ulm		
Germany

