README revision d075918c 
1VMMouse
2-------
3
4The VMMouse driver enables support for the special VMMouse protocol
5that is provided by VMware virtual machines to give absolute pointer
6positioning. 
7
8Installing the driver will improve the user experience when using the 
9mouse to interact with the guest operating system. In particular, use of 
10the driver improves mouse "lag", provides mouse speed and acceleration 
11consistent with the user's host operating system, and enables the 
12auto-grab/ungrab feature in VMware products without requiring the VMware 
13toolbox application.
14
15Using the driver
16----------------
17
18Assuming you have built and installed the driver in the standard way
19for autotools based packages (see INSTALL), or the driver was already
20installed by your distro, using it is simply a matter of changing the
21driver used for the mouse input device from "mouse" to "vmmouse".
22
23The vmmouse driver is capable of falling back to the standard "mouse"
24driver if a VMware virtual machine is not detected. This allows for
25dual-booting of an operating system from a virtual machine to real hardware
26without having to edit xorg.conf every time.
27
28Implementation
29--------------
30
31The following is not necessary reading for anyone who wants to use the
32driver, but should help anyone who wants to understand how it works or
33who wants to write a driver for a different target, whether it's another
34operating system, a linux kernel input driver or even gpm.
35
36The driver is composed of three different layers:
37
381) The vmmouse protocol layer (vmmouse_proto.[c|h])
39   - This provides the call to read and write the port over which 
40     the vmmouse packets are transfered.
41
422) The vmmouse client layer (vmmouse_client.[c|h])
43   - This builds on top of the protocol layer to provide higher
44     level calls for enabling/disabling the vmmouse mechanism
45     and for reading data.
46   - A new driver for a different target would use this interface.
47
483) The Xorg vmmouse driver (vmmouse.c)
49   - This is the actual Xorg specific part of the driver.
50   - Note that interrupts indicating the presence of mouse data
51     are still transmitted on the PS/2 port so it is necessary
52     to be set up to receive those interrupts like a standard
53     PS/2 driver, but the actual data on the PS/2 port is ignored.
54
55vmmouse_detect
56--------------
57
58A simple program to detect whether the vmmouse device is present.
59It is used by the HAL callout script to automatically detect a
60vmmouse device.
61
62Returns 0 if we are running in a virtual machine where the vmmouse
63device is present.
64
65Returns 1 otherwise (either we are not in a VM or the vmmouse device
66was disabled).
67