Please forgive me if this doc is quite unordered, but I'm currently
quite busy with my PhD thesis -- damnit.

This release of kmouse supports busmice, though I can't test them.
Please report any problem to me.

====> note that busmice are managed differently form 0.10, and are
	more likely serial mice, now.

The patch against 1.3.60 supports the configuration as well. I sent it
to Linus too, just in case he wants this stuff in...

kmouse-0.20.tar.gz is available from the following places
	tsx-11.mit.edu:/pub/linux/ALPHA/kmouse (currently in incoming...)
	iride.unipv.it:/pub/linux   -- sloooow link
	ftp.systemy.it:/pub/develop -- should be faster

/alessandro -- Tue, Feb 11th 1996


The machinery
-------------

kmouse.c can only be compiled as a module. It is meant to steal mouse
packets from the mouse drivers and handle the information to the right
user process (or the internal selection mechanism). The mouse appears
to always belong to the foreground console.

Kmouse offers raw packets on one device, and client arbitration on
another device (see below). Selection is handled internally by
the module.

The current implementation is able to run selection, feed clients with
msc packets (e.g., I run X with kmouse) and support gpm clients linked
with libgpm-1.00 and later, but it only works if "mouse.c" is linked
in the running kernel. This issue is handled by the CONFIG_KMOUSE
kernel compilation option.

The package includes a patch agains 1.3.60

The following is the status of all gpm options:

-a <accel>    in the module
-b <baud>     in gpm
-B <buttons>  in the module
-d <delta>    in the module
-g <tap>      unsupported, yet
-i <interval> in the module
-k            in gpm
-l <charset>  in gpm
-L <charset>  in gpm
-m <device>   in gpm
-M            in gpm. The module is multiple-mouse in itself.
-o <lines>    in gpm
-p            in the module
-q            unsupported, yet
-r <respo>    in gpm
-t <proto>    in gpm, but autodetection if no option specified
-R            the module returns data if read by some process
-s <sample>   in gpm
-2            in the module
-3            in the module

gpm-1.07
--------

A patch to gpm-1.06 is included, it turns gpm to 1.07, which supports
a "-K" option, to load the kernel module and pass configuration
options to it.

I'll upload gpm-1.07 to sunsite as soon as I have time to update the docs.

To test kmouse out, you only have to invoke gpm in the usual way, with
the additional "-K" option. If all goes well, the mouse behaviour will
inherit any options you passed to gpm.

Without gpm-1.07
----------------

If you don't want to patch and recompile gpm, you won't have access to
user options, and won't be able to drive two mice concurrently in kernel
mode (say, a trackball + serial mouse on a laptop).

To enable kmouse with busmice, nothing special has to be done: just
load the module.

Running serial mice, however, is different: you have to use
"./mouseconfig" to set the line discipline on the serial line.

If you prefer running mouseconfig, you must keep your gpm alive, and
if you want to run gpm clients with kmouse, you have to remove
/var/run/gpmctl: libgpm will connect to /dev/gpmctl (kmouse) only if
/var/run/gpmctl is missing. You'll need to kill gpm (close the serial
port) before removing kmouse, because the line discipline is part of
the kmouse module, and keeps it busy (unremovable)

Actually, gpm isn't the only way to keep the port open ("sleep 100000
< /dev/mouse" will do as well), but you need a way to initialize the
device anyways. That's why I prefer running "gpm -K" instead.


The module
----------

Protocol status (indexed by gpm/selection "-t" names): 

	ms (without middle-button extension): supported and autodetected
	msc: supported and autodetected
	ps2: supported and autodetected, but untested
	bm: see "sun"
	mman: unsupported. It's a damned ugly protocol. I've to think 'bout it.
	logi: supported, not autodetected (I suppose)
	mm:  see "logi"
	sun: supported. Busmice are internally "sun", and are autodetected.
	ncr: unsupported
	

The workings (more theoretical part)
------------

	Serial mice

Stealing of serial data is performed through a new line discipline, called
N_MOUSE. The symbol "N_MOUSE" is already defined in the production kernels,
though nobody is using it, so I went for it.

Changing the line discipline of the serial device is the task of
gpm-1.07. Otherwise, you should invoke "mouseconfig" after loading the
module (see above). Busmouse owners won't need mouseconfig.

The new line discipline will stay in effect till the port is
open. If you run gpm-1.07 things are managed by the daemon, which
puts itself to sleep after setting things up, and keeps the port open.
If you kill gpm-1.07, the mouse module will be removed.

	Busmice (This is different from 0.10)

The busmouse device must be kept open, for simmetry with serial mice,
and to simplify controlling them through gpm (single open is still there).
Moreover, this shortens the module, which still fits in 2 pages.

If the global kernel variable kmouse_stealing is non-null, busmice
call one of the stealing functions from within the interrupt handler.

User programs won't be able to read anything from the device, as data
is stolen right when it appears. Opening the device is needed to make
its interrupt handler work, so that the kmouse module can have its data.

When unloading, kmouse must be unloaded before the busmouse, otherwise
the busmouse will be busy, as kmouse keeps it open.

--> There's nothing here specifically related to kmouse, only a pointer
which signals someone is stealing data. Kmouse itself checks the pointer
before installing, to avoid collision with a (possible) different stealer.




The devices
-----------

/dev/gpmdata  msc packets (only for the controlling tty of the reading process)
/dev/kmouse   the same, but with a more appealing name.
/dev/gpmctl   the gpm interface for client applications.

mknod /dev/gpmdata c 10 64; chmod go+r  /dev/gpmdata
mknod /dev/kmouse  c 10 64; chmod go+r  /dev/kmouse
mknod /dev/gpmctl  c 10 65; chmod go+rw /dev/gpmctl

kmouse vs gpm
-------------

Mainly, kmouse is more performant: events can be clustered before
being fed to clients.  The daemon can only perform partial clustering,
with sensible overhead. The mouse/screen feedback shouldn't feature
any more delays (at least in text consoles).

Besides, "gpm -R" is a workaround -- it only senses the graphic mode: if
you're running libvga gpm will repeat packets, while noone will be
reading the fifo.... kmouse, on the contrary, won't send data unless
there is a reader.

Compiling
---------

Patch and compile the kernel. Edit the Makefile (replace the "-I" option,
and choose debug or not), and "make".

Run gpm-1.07 with your preferred options, plus "-K", from a place
where you can find the kmouse module (or you can install by hand kmouse.o).

You can tell if your selection is being run by gpm (daemon) or kmouse by
the starting position of the mouse cursor: gpm puts it in the middle of
the screen, while a fresh kmouse puts the cursor top-left. It will change,
but it's important to see who is getting mouse events.

Bugs
----

* mman, and ms+3rd-button are not decoded

* gpm-root (default handlers in general) is not managed

* doesn't change scale/scaley when screensize changes

* if some client is there, gpm -k won't remove the module

* must split between tq_timer and tq_scheduler -- potential problems

* ......

Main sources
------------

kmouse.c           -- the module (insmod kmouse.o)
gpm-1.06-07.patch  -- upgrades your gpm to support "-K"
fakemouse.c        -- a busmouse-like thing used by me to test the module


The patch against 1.3.60 (most files are in drivers/char)
------------------------

<linux/busmouse.h>   removes definition for minors (they're in mouse.h)
<linux/mouse.h>      defines the new minors, and the mouse_steal structure

console.c            con_get_fg_info: small new function

mouse.c              declare mouse_stealing, export symbols from selection.c, 
			export mouse_stealing, mouse_list and con_get_fg_info()
			declare watchdog_init to prevent a warning

busmouse.c           static kdev_t variable, use mouse_stealing, 
			use correct minor symbol (from mouse.h)
			reindent ala Linus,
msbusmouse.c         static kdev_t variable, use mouse_stealing
			use correct minor symbol (from mouse.h)
atixlmouse.c         static kdev_t variable, use mouse_stealing


selection.[ch]       set_selection(): one arg more telling if user or kernel,
selection.h          declare con_get_fg_info()
tty_io.c             pass the additional arg more to set_selection


Config.in            ask for kernel mouse support
Makefile             manage CONFIG_KMOUSE
mem.c                call mouse_init() if CONFIG_KMOUSE


What's missing
--------------

- Official device number registration
- Official ioctl number registration
- Dynamic assignment of mouse minors (for custom drivers: optical pens and
	such).

