Troubleshooting Wrong Mouse Movements when Virtualizing FreeBSD on Windows 11 with qemu-kvm

Fix incorrect mouse movements in FreeBSD on Windows 11 QEMU by ensuring the usb-tablet device is correctly added to your VM configuration and that the guest OS properly loads the ums (USB Mouse) driver. This issue typically stems from missing absolute coordinate reporting or improper driver initialization, which can be resolved through specific command-line flags and kernel module adjustments.

Understanding the Root Cause

When virtualizing FreeBSD using QEMU-KVM, the default mouse emulation often relies on relative coordinate movement. This works well for simple pointer tracking but fails when applications expect absolute positioning, leading to jerky, inverted, or overly sensitive cursor behavior. The core problem is usually that the virtual machine does not receive absolute mouse coordinates from the host system. QEMU provides a specialized device called usb-tablet designed specifically to solve this. Unlike standard PS/2 mice which send relative deltas, an USB tablet device reports the exact X and Y coordinates of the cursor within the window. Without this device, FreeBSD falls back to less accurate emulation methods. Additionally, modern FreeBSD versions have deprecated older input drivers, making it crucial to use the correct kernel modules.

Configuring QEMU for Absolute Positioning

The most effective fix involves modifying the QEMU launch command or your virtualization manager’s XML definition to include the USB tablet device. This ensures the hypervisor sends precise coordinate data to the guest operating system. If you are launching QEMU directly from the command line, add the following argument to your startup script:

-device usb-tablet

This flag tells QEMU to create a virtual USB tablet device attached to the virtual USB bus. It should be placed alongside other device definitions such as -device virtio-net-pci or -drive file=freebsd.img,format=qcow2. For example, a typical corrected command might look like this:

qemu-system-x86_64 \
    -enable-kvm \
    -m 4096 \
    -cpu host \
    -drive file=freebsd.qcow2,format=qcow2 \
    -device usb-tablet \
    -netdev user,id=net0 \
    -device virtio-net-pci,netdev=net0

If you are using libvirt (virsh), you must edit the domain XML. Locate the <devices> section and ensure there is a <input type="tablet" bus="usb"/> element. If it is missing, add it. Do not remove existing input devices unless you are certain they are conflicting; simply adding the tablet is usually sufficient. For users managing multiple VMs, consistency is key. Ensure every FreeBSD guest has this device enabled. You can verify the current configuration by checking the running state of the VM or inspecting the XML definition with virsh dumpxml <vm-name>.

Why Not Remove Existing Mouse Devices?

A common mistake is attempting to remove the default PS/2 mouse to "force" the use of the USB tablet. This approach is risky because some older FreeBSD installations or specific console environments may rely on the PS/2 interface for basic functionality. Removing it without ensuring the USB stack is fully initialized can lead to a frozen input subsystem. Instead, keep the default mouse and add the tablet. The FreeBSD kernel will prioritize the tablet for absolute positioning tasks while keeping the PS/2 mouse as a fallback for compatibility.

FreeBSD Guest Configuration

Once the host side is configured, you must ensure the FreeBSD guest recognizes and utilizes the USB tablet. Modern FreeBSD releases handle this largely automatically, but manual verification ensures stability. First, check if the ums (USB Mouse) module is loaded. You can do this by running:

kldload ums

If the module is already loaded, you can verify its status with kldstat | grep ums. The presence of ums indicates that the system is ready to process USB mouse events. Note that older guides might suggest loading psm (PS/2 Mouse) or using obsolete packages like xf86-input-synaptics. These are incorrect for this context. The psm module handles PS/2 interfaces, which do not provide absolute coordinates. The xf86-input-synaptics package is for touchpad drivers in Xorg and is irrelevant for a virtual USB tablet. To make the ums module load at boot, add the following line to /etc/rc.conf:

kld_list="ums"

This ensures that every time the system starts, the USB mouse driver is active before the desktop environment initializes. After updating rc.conf, restart the VM or manually load the module to apply changes immediately.

Verifying the Fix

After applying these changes, restart the FreeBSD VM. Upon login, test the mouse movement in different applications. The cursor should now move smoothly and accurately reflect your physical mouse movements, especially in full-screen mode or when using applications that require precise targeting. If issues persist, check the QEMU logs for any USB-related errors. You can also try switching the USB controller type in your VM settings from ich9-ehci1 to qemu-xhci if available, as newer controllers sometimes offer better compatibility with USB tablets. For related networking issues that might accompany virtualization setup, see our guide on Troubleshooting: No Internet on QEMU VM despite Connection Present. Similarly, if you encounter display artifacts after fixing the mouse, consult Prevent Mouse Hidden in Ubuntu while Running KVM/QEMU Guest for broader input troubleshooting techniques.

Frequently Asked Questions

Does removing the default PS/2 mouse improve performance?

No, removing the PS/2 mouse does not improve performance and may break basic input functionality. The usb-tablet device works best when added alongside existing input devices rather than replacing them. Keeping both ensures maximum compatibility across different FreeBSD versions and applications.

What if my FreeBSD version is very old?

Older FreeBSD versions may not support the ums module by default. In such cases, you may need to compile custom kernel options or upgrade the guest OS. However, for most modern systems, the ums module is built-in and requires only loading via rc.conf.

Can I use a different USB controller instead of the tablet?

While you can change the USB controller type (e.g., to xHCI), this does not replace the need for the usb-tablet device. The controller manages hardware communication, while the tablet device defines the input protocol. Both are necessary for optimal accuracy.

Why does the mouse still feel jittery after adding the tablet?

Jitteriness can result from high polling rates or conflicting software filters. Try disabling mouse acceleration in the FreeBSD desktop environment settings. Additionally, ensure no other virtualization software is capturing the mouse cursor simultaneously on the host system.

Is this fix applicable to Linux guests as well?

Yes, the usb-tablet device is standard for KVM/QEMU guests across all major operating systems, including Linux and Windows. The guest-side configuration differs slightly, but the host-side QEMU flag remains the same universal solution for absolute positioning.