Home | History | Annotate | Line # | Download | only in dist 
      1 VMMouse
      2 -------
      3 
      4 The VMMouse driver enables support for the special VMMouse protocol
      5 that is provided by VMware virtual machines to give absolute pointer
      6 positioning. 
      7 
      8 Installing the driver will improve the user experience when using the 
      9 mouse to interact with the guest operating system. In particular, use of 
     10 the driver improves mouse "lag", provides mouse speed and acceleration 
     11 consistent with the user's host operating system, and enables the 
     12 auto-grab/ungrab feature in VMware products without requiring the VMware 
     13 toolbox application.
     14 
     15 Using the driver
     16 ----------------
     17 
     18 Assuming you have built and installed the driver in the standard way
     19 for autotools based packages (see INSTALL), or the driver was already
     20 installed by your distro, using it is simply a matter of changing the
     21 driver used for the mouse input device from "mouse" to "vmmouse".
     22 
     23 The vmmouse driver is capable of falling back to the standard "mouse"
     24 driver if a VMware virtual machine is not detected. This allows for
     25 dual-booting of an operating system from a virtual machine to real hardware
     26 without having to edit xorg.conf every time.
     27 
     28 Implementation
     29 --------------
     30 
     31 The following is not necessary reading for anyone who wants to use the
     32 driver, but should help anyone who wants to understand how it works or
     33 who wants to write a driver for a different target, whether it's another
     34 operating system, a linux kernel input driver or even gpm.
     35 
     36 The driver is composed of three different layers:
     37 
     38 1) 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 
     42 2) 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 
     48 3) 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 
     55 vmmouse_detect
     56 --------------
     57 
     58 A simple program to detect whether the vmmouse device is present.
     59 It is used by the HAL callout script to automatically detect a
     60 vmmouse device.
     61 
     62 Returns 0 if we are running in a virtual machine where the vmmouse
     63 device is present.
     64 
     65 Returns 1 otherwise (either we are not in a VM or the vmmouse device
     66 was disabled).
     67