kmouse-0.48
-----------

This document is made up of different sections.  They are more or less
unordered.   Each section is  unrelated  to the  others. The theorical
concepts behind this  package, and an  introduction to the new pointer
protocol  is in  the  file MANIFESTO, which I    posted to the  kernel
mailing  list.  The protocol    is  completely decribed   in  the file
PROTOCOL,  while the advertisements about  kmouse features  are at the
end of this file.

/alessandro -- November 1996


Introduction
------------

Lines beginning  with "TODO" describe  features that will be available
in version 0.50. Lines beginning with "TEMP"  describe bugs that won't
be available in 0.50.

TODO | This release of the package supports  busmice, although I haven't been
TODO | able  to test them. The   busmouse being used  should  be the modified
TODO | version of the driver that is released with this module.

TEMP | Support for 2.1 kernels isn't there, yet. I plan to upgrade my kernel,
TEMP | and 0.50 will run on both 2.0 and 2.1.

The  2.0 kernels must  be patched to  support  kmouse, the patch is in
this distribution, as Linus didn't accept it.  The patch only modifies
misc.c: I have had in it my own kernels from  1.3.90 onward without it
interfering with any official upgrade of the system.

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

This version  of  kmouse doesn't need  gpm running.  The "mouseconfig"
program supplied  with the distribution  makes all  the job  and  then
exits.  Using "gpm -K" with this version of kmouse  is not expected to
work. The "-K" option will be missing from gpm-1.11.

Kmouse exists   as a kernel   thread, because the  selection mechanism
calls a  non-atomic kmalloc. Killing   the thread tells the  module to
detach  from the system  so it can be unloaded.  You  can't unload the
module before killing the thread.


What's new over 0.45
--------------------

0.45  has been the  first release with the  new features, so nobody is
interested any more in the previous versions.

0.46: * fixes serial initialization (setting the  baud rate). I forgot
	to include it in 0.45.

0.47: * adds an ``fd'' variable which was accidentally removed from
	mouseconfig.c when rushing to release 0.46 :(

      * changes the absolute coordinate range, (it's 30 bits now).

      * new file PROTOCOL: The protocol formal definition.

      * new flags: zed-is-pressure and special-packet

      * the magic number is local-endian

      * absolute pointer are tested: absolute data can be converted to
	relative data

      * the wacom tablet is supported (I`m able to read /dev/kmouse
	from X and writing in xpaint with the pen)

0.48: * absolute pointers behave better with text consoles.

      * bug fix in kmouse_enqueue (it oopsed when kmalloc failed)

      * /proc/kmouse holds more info when debugging (who cares but me?)

      * slightly reworked to avoid some overheads.

      * supports assigning range x/y from user space.

      * supports the sun/logi/ps2 protocols.

      * support ps2 mice (tested as well :)

      * root can open even w/out ctl tty (so mouseconfig can run from rc.d)

Compiling
---------

* Patch and  compile the kernel.  The option  "CONFIG_UMISC" should be
turned  on, in order  to export a few symbols  needed to run selection
from  the module. If   your kernel has  already been  patched to run a
previous kmouse version, this step is not needed.

* Edit the kmouse Makefile (replace the "-I"  option, and choose debug
or not), and "make". If you want "make install" as well.

* Copy mouse.conf  to /etc and edit  it to reflect your configuration.
If you need to run multiple mice, you only have to list them here.

* Kill gpm if you are running it.

* Load the module and invoke "mouseconfig" from the current directory
to configure the driver.

* Ignore the warnings about "tty->count(1) != #fd's(0) in
release_dev".  The module keeps the serial port open by using an owned
file structure, not registered in the global kernel file table.


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

/dev/gpmdata 
	Msc packets (3button serial mice) for mouse events received in
	the current console. This name is compatible with "gpm -R".

/dev/kmouse
	The same, but with a more appealing name.

/dev/gpmctl
	The gpm interface for client applications.

/dev/kpointer
	The   new pointer protocol.   Gives   the same information  as
	/dev/kmouse, but in a more powerful format.

/dev/rpointer
	Raw  kpointer. It is the same  as /dev/kpointer, but delta and
	accel  have not been applied, for  applications which do it by
	themselves (like X).

mknod /dev/gpmdata  c 10 63; chmod go+r  /dev/gpmdata
mknod /dev/kmouse   c 10 63; chmod go+r  /dev/kmouse
mknod /dev/gpmctl   c 10 62; chmod go+rw /dev/gpmctl
mknod /dev/kpointer c 10 61; chmod go+r  /dev/kpointer
mknod /dev/rpointer c 10 60; chmod go+r  /dev/rpointer

Writing  to  /dev/gpmctl is needed by  gpm  clients. Writing  to other
nodes  does nothing.  Ioctl()  can  only be invoked  by  root (usually
during system boot).

The current kmouse  uses  automatic minor assignment.    Dynamic minor
numbers grow from 63 downwards, so if another dynamic device is there,
the minors will be  different (lower). You  can specify at lpad time a
different  starting number for the  minors.  "insmod kmouse minor=50",
for instance will retrieve minors 50,49,48,47.


Using Kerneld
-------------

I have no problem with kerneld by inserting the following lines
in /etc/conf.modules (or modules.conf).

alias char-major-10-63 kmouse
alias char-major-10-62 kmouse
alias char-major-10-61 kmouse
alias char-major-10-60 kmouse


Adding new protocols
--------------------

TODO | Additional  pointing  devices can   be added either  as  compile  time
TODO | options    or as stacked  modules.

The file  "protocols.c" embeds the  necessary documentation to add new
protocols to kmouse.

There  is no support  to add new out-protocols:  msc, gpm and kpointer
should be sufficient.


Still to do
-----------

There   is  currently    no   support   for  multiple    /dev/kpointer
nodes. Sometimes one  wants to dedicate  a graphic tablet  to a single
application while using the mouse for general X workings.

There's no support for  GGI  as well. I  don't  have a supported  VGA,
currently.

TEMP | There's no support for 2.1 kernels, by now.


Bugs in 0.48
------------

Entries marked TEMP will go away before 0.50, I can't tell for the others

* ms+3rd-button is not decoded.

* Doesn't automatically change scale/scaley when screensize changes (TEMP)

* fasync is not correctly managed (TEMP)


The options of gpm
------------------

-a <accel>    set by mouseconfig ("accel")
-b <baud>     set by mouseconfig ("baudrate")
-B <buttons>  set by mouseconfig ("buttonsequence")
-d <delta>    set by mouseconfig ("delta")
-g <tap>      unsupported, yet
-i <interval> set by mouseconfig ("doubleclick")
-k            "mouseconfig -kill", or by hand (killall kmouse; rmmod kmouse)
-l <charset>  unsupported, yet (TEMP)
-m <device>   choose devices in mouseconfig ("device")
-M            kmouse is multi-mouse by its nature
-o <lines>    done by mouseconfig ("clear")
-p            set by mosueconfig ("ptrdrag")
-r <respo>    set by mouseconfig ("responsiveness")
-R            kmouse is repeating by default
-t <proto>    set by mouseconfig ("protocol"), or autodetected
-s <sample>   not supported, yet
-v            "mouseconfig -v" tells the version
-2            not supported, yet
-3            not supported, yet

-L, -q, -D, -T have no equivalent semntics when using kmouse in place
of gpm.


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, X is different, as the server's
process must decode events and draw the pointer).

Well, I've been able to bring the loadavg to 100, and still
have a responsive mouse on the text console.

morgana.root# uptime
  8:03pm  up 15 min,  0 users,  load average: 101.01, 55.35, 22.63

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 for the current console
