Hypervisor Abstraction and Guest Support

What is it?

When Impossible OS runs inside VirtualBox, QEMU or Hyper-V, guest support lets it cooperate with the host: an absolute mouse pointer, a display that follows the window size, shared folders and a shared clipboard. Impossible OS detects which hypervisor it is running under and supports two absolute pointers, VirtualBox's and VirtIO's tablet. The rest of the guest additions, and the single backend interface the roadmap plans for them, do not exist yet. None of the roadmap's twelve sections is complete.

How does it work?

Detection. platform_detect() in cpuid_platform.c checks the CPUID hypervisor bit, then reads the vendor string at leaf 0x40000000. It classifies the machine as one of the platform_id_t values in cpuid_platform.h: bare metal, Hyper-V, VMware, VirtualBox, QEMU with KVM, QEMU with TCG, or an unknown hypervisor. On Hyper-V and KVM it also records whether the hypervisor publishes the APIC timer frequency, which the timer calibration uses to skip measurement. The result is cached and logged, for example Detected: VirtualBox (CPUID 0x40000000).

VirtualBox pointer. vbox_mouse.c finds the VirtualBox guest device (PCI 80EE:CAFE), speaks the VMMDev request protocol and reports absolute pointer positions, logging VBox absolute mouse enabled. It handles only the mouse: no display change events, HGCM, shared folders or clipboard.

VirtIO tablet. input.c drives a VirtIO input device in tablet mode on top of the shared VirtIO queue code in virtio.h. There is no VirtIO GPU, 9P or entropy device.

Hyper-V. Only detection and the APIC frequency shortcut exist. Every IDT vector has a stub because Hyper-V Generation 2 delivers a VMBus interrupt on vector 0xF6 whether or not a driver listens, but there is no VMBus, synthetic storage, keyboard or video driver.

No abstraction yet. Callers choose the backend by hand: the compositor in compositor.c asks whether the VirtIO tablet is available and otherwise the VirtualBox mouse. The roadmap replaces that chain with one hv_ops_t table, with a null backend on bare metal so every call is safe there.

flowchart TD
    C[CPUID leaf 0x40000000] --> D{platform_detect}
    D -->|VirtualBox| V[vbox_mouse]
    D -->|QEMU| Q[virtio input tablet]
    D -->|Hyper-V| H[APIC frequency only]
    D -->|bare metal| B[no guest support]
    V --> K[Compositor pointer]
    Q --> K

What are its interfaces?

Interface	Purpose
`platform_detect()`, `platform_get()`, `platform_name()`, `platform_is_tcg()`	Hypervisor identity (`cpuid_platform.h`)
`vbox_mouse_init()`, `vbox_mouse_available()`, `vbox_mouse_get_state()`	VirtualBox absolute pointer (`vbox_mouse.c`)
`virtio_input_init()`, `virtio_input_available()`, `virtio_input_get_state()`	VirtIO tablet (`input.c`)
`hv.h`, `hv_ops_t`	Planned, not present

How do I use it?

Run the image under VirtualBox or QEMU as described in Running in VirtualBox and Running in QEMU; when the guest pointer device is present, the pointer reports absolute positions and the boot log names the driver that took it. The detection checks run in the x86 category (test_cpu_security.c):

bash scripts/test.sh SUITE=x86

What is not implemented yet?

The roadmap's detection API and PCI fallback. Detection ships as platform_detect() above (Hypervisor Detection).
The hv.h backend table (Unified hv.h Interface + Backend Dispatch) and its bare-metal null backend (Bare-Metal Null Backend).
VirtualBox guest additions: display resize (VBox Display Auto-Resize), HGCM (VBox HGCM Client), shared folders (VBox Shared Folders) and clipboard (VBox Shared Clipboard).
VirtIO GPU (VirtIO GPU Display Resize + Page Flip), 9P shared folders (VirtIO 9P Shared Folders) and VirtIO RNG (VirtIO RNG Guest Entropy).
Hyper-V synthetic devices, which need a VMBus driver first (Hyper-V Synthetic HID, Hyper-V Synthetic Video).

How does it compare with Windows 11 and Linux?

Windows 11 runs a separate set of guest drivers per hypervisor (VirtualBox Guest Additions, VirtIO drivers, Hyper-V integration services). Linux ships vboxguest, vboxsf, virtio-gpu, 9P and the Hyper-V hv_* drivers in-tree, detected through CPUID. Neither has one interface across hypervisors. Impossible OS detects every major hypervisor and supports two absolute pointers; the roadmap's addition is a single backend table with a bare-metal null backend.