VIRTIO_GPU_QEMU(4) Kernel Interfaces Manual VIRTIO_GPU_QEMU(4) NAME virtio_gpu_qemu -- VirtIO GPU display driver for QEMU and UTM with frame- buffer mmap support SYNOPSIS To enable the driver, place the following line in loader.conf(5) and reboot: virtio_gpu_qemu_load="YES" DESCRIPTION The virtio_gpu_qemu driver supports the display adapter offered by QEMU and by UTM when the virtual machine is configured with virtio-gpu-pci. It replaces the VirtIO GPU driver built into FreeBSD, and adds one thing to it: the framebuffer is published as /dev/fb0 and can be mapped into memory with mmap(2). That is what an X server needs in order to drive the display through the scfb video driver, so with virtio_gpu_qemu in use, Xorg and Xlibre work inside a QEMU or UTM guest. The text console behaves as be- fore. The driver can also override the screen size advertised by the virtual ma- chine, which is useful when the host offers a resolution that is awkward to work with. Enabling the driver virtio_gpu_qemu must be loaded by loader(8), that is, from loader.conf(5). Loading it later with kldload(8), or from kld_list in rc.conf(5), has no effect: by then the driver built into the kernel has already claimed the display and taken over the console. To go back to the driver built into the kernel, either remove the virtio_gpu_qemu_load line or set hw.virtio_gpu_qemu.driver_enable to 0, then reboot. HARDWARE The virtio_gpu_qemu driver supports VirtIO GPU devices, as offered by QEMU with virtio-gpu-pci and by UTM. Only 2D output is supported. SYSCTL VARIABLES The following variables may be set in loader.conf(5). They take effect when the driver is loaded and are read-only afterwards. hw.virtio_gpu_qemu.driver_enable Set to 0 to leave the display to the driver built into the kernel, without having to remove the virtio_gpu_qemu_load line. The de- fault is 1. hw.virtio_gpu_qemu.width hw.virtio_gpu_qemu.height Screen size to use instead of the one advertised by the virtual ma- chine. Both have to be set for the override to apply. The default is 0, meaning the advertised size is used. hw.virtio_gpu_qemu.refresh_rate How often the screen is sent to the virtual machine, in frames per second, while an X server is running. Valid values are 1 to 120, and the default is 30. The following variable exists for each display and can be changed at any time: dev.vtgpu.%d.refresh_rate How often the screen is sent to the virtual machine, in frames per second, while an X server is running. Valid values are 1 to 120. Higher values make the display smoother but use more CPU time on the host. FILES /boot/modules/virtio_gpu_qemu.ko the driver itself /boot/loader.conf where the driver is enabled and configured /dev/fb0 framebuffer device used by the scfb X video driver /usr/local/share/X11/xorg.conf.d/20-virtio-gpu-qemu.conf X configuration selecting the scfb driver, installed by the port /usr/local/etc/X11/xorg.conf.d/ directory for local X configuration; it is read before /usr/local/share/X11/xorg.conf.d/, so a file of the same name placed here takes precedence EXAMPLES A loader.conf(5) for a guest with a 1536x864 screen: virtio_gpu_qemu_load="YES" hw.virtio_gpu_qemu.width="1536" hw.virtio_gpu_qemu.height="864" hw.virtio_gpu_qemu.refresh_rate="30" A matching QEMU invocation. Note that virtio-gpu-pci provides no keyboard or mouse, so those have to be added separately: qemu-system-aarch64 -machine virt,accel=hvf \ -device virtio-gpu-pci,xres=1536,yres=864 \ -device qemu-xhci -device usb-kbd -device usb-tablet \ ... To run an X server, install the scfb video driver and select it. The port installs the following as /usr/local/share/X11/xorg.conf.d/20-virtio-gpu-qemu.conf; when the driver was built by hand, create that file: Section "Device" Identifier "virtio-gpu-qemu" Driver "scfb" EndSection Making the display smoother while X is running: sysctl dev.vtgpu.0.refresh_rate=60 SEE ALSO vt(4), loader.conf(5), rc.conf(5), kldload(8), loader(8) HISTORY The virtio_gpu_qemu driver first appeared as an out-of-tree module in 2026. It is derived from the VirtIO GPU driver in FreeBSD 13.2, originally writ- ten for FreeBSD by Arm Ltd. AUTHORS The virtio_gpu_qemu driver was written by Tiago Gasiba <tiga@FreeBSD.org>, based on the VirtIO GPU driver in FreeBSD by Bryan Venteicher <bryanv@FreeBSD.org> and Arm Ltd. CAVEATS The driver cannot be unloaded once it is in use; kldunload(8) fails. Dis- abling it requires a reboot. The screen size is fixed while the system is running. Changing it means editing loader.conf(5) and rebooting. Resizing the window on the host does not change the screen size inside the guest either; the host merely scales the picture. Building the driver from source requires the kernel sources in /usr/src to match the running kernel. BUGS There is no 3D acceleration. Only one screen is supported. FreeBSD ports 15.quarterly July 27, 2026 VIRTIO_GPU_QEMU(4)
NAME | SYNOPSIS | DESCRIPTION | HARDWARE | SYSCTL VARIABLES | FILES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | CAVEATS | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=virtio_gpu_qemu&sektion=4&manpath=FreeBSD+Ports+15.1.quarterly>