Investigating problems with mouse input in VirtualBox

This page gives a quick overview of the way (or ways) in which mouse input to virtual machines works in VirtualBox and some ways to get a closer look at what is happening in order to understand when things go wrong. Please feel free to suggest improvements!

General flow of mouse input

Like many things in VirtualBox, mouse input follows a chain which starts at the "front-end" - usually the VirtualBox application window which displays the virtual machine, or the built-in remote desktop server - and works its way through to the guest operating system which sees the input through virtual devices using native or VirtualBox guest drivers. If something is going wrong then getting as much information as possible about what is happening at each point in the chain is a good way of finding out more.

The front-end

Each front-end has its own way of getting at mouse input. The remote desktop server receives mouse events from the viewer application (rdesktop, Microsoft Remote Desktop Connection client) so the first place to look for problems is making sure that these are sending the right input. How to do this is something outside of our scope, but if problems are visible using remote desktop connections but not accessing a machine directly this is worth following up.

The standard VirtualBox application window gets its mouse input from the operating system. When VirtualBox is using the X11 windowing system (Linux, Solaris, FreeBSD) you can get a closer look at that input using the "xev" command line tool - "xev -id <window id>", where you can find the <window id> by running "xwininfo -tree", clicking on the window and trying out windows in the list with the right size. Ideas about how to do similar things for Windows and OS X are welcome! (This was written by a Linux developer.)

"Main"

"Main" is the equivalent of a telephone switchboard inside the VirtualBox application, where all the different components are connected to each other. The front-end picks up mouse input in its own way and passes it on to Main in a standard format. Main passes the information on to virtual devices inside the virtual machine (see below). You can get a look at the information flowing through Main by running VirtualBox with the environment variable "VBOX_RELEASE_LOG=+main.e.l3" set. This will add information about mouse events (and, be warned, potentially lots of other things, as Main is a very busy component) to the virtual machine log file.

Virtual devices

When a guest operating system is run in a VirtualBox virtual machine it sees that it is running on a machine with a number of devices present. This will usually include (simulated) input devices, and we are interested in the emulated PS/2 mouse, the emulated USB mouse and graphics tablet and the Guest Additions pointer device.

• The first of these is the most basic method of mouse input into the guest system and simulates a traditional pre-USB mouse. It can provide information about mouse movement to the left, right, up and down (no exact positions), up to five mouse buttons and horizontal and vertical wheel scrolling. The guest operating system has a standard driver which works with this device. To see what information Main is sending to this device, run VirtualBox with the environment variable "VBOX_RELEASE_LOG=+dev_kbd.e.l3.f" set and look in the virtual machine's log file.

• The second device is the virtual USB mouse. This can provide all the information that the PS/2 mouse can, and in addition, if the guest operating system understands this, it can provide the exact position of the mouse pointer. If the guest uses this information then the position of the mouse pointer in the guest window should always match the position of the host pointer. If the guest mis-understands this information there is likely to be a systematic difference between the two positions. Currently there is no way of getting as much information about information flowing through this device as there is for the PS/2 mouse.

• The third device of interest is the VirtualBox "guest" device which provides a number of services for integrating applications in a virtual machine with the desktop and services of the host machine running VirtualBox. We are interested in its "mouse integration" function which sends the position of the host mouse pointer to the guest. The guest operating system needs a special driver for the guest device, which usually comes with VirtualBox, to get this information. The guest device does not provide information about mouse button clicks - this is still sent to one of the other devices. You can take a look at information flowing through this device - which includes guest requests for mouse pointer information - by setting the environment variable "VBOX_RELEASE_LOG=+e.l2.f".

Guest operating systems

It is also worth using any tools available in guest operating systems to find out what mouse information they are seeing at the end of the chain. In guests running the X Window system (Linux, Solaris, FreeBSD), the "xev" command line tool is useful for this and the file "/var/log/Xorg.0.log" and its variants also provide useful inforamation. In many you can also get information through the "xinput" command line tool. On many Linux systems the "evtest" command line tool is also useful.

Suggestions for Windows guests are welcome!