We've just launched. The site and the service are still being polished — we apologize in advance for any inaccuracies or rough edges. Spotted a mistake or something that doesn't work as expected? Tell us and we'll fix it quickly.

← All projects
EN
Beyond TAKT

qemu-thunderbolt

A QEMU branch that adds a Thunderbolt-flavoured PCIe hotplug layer. Devices behind it remain ordinary QEMU PCI devices; the layer controls whether the guest sees them connected and sends the hotplug notifications.

  • QEMU
  • Thunderbolt
  • PCIe
  • macOS
Repository on GitHub Related: escrow-box
Status
Experimental: five commits on top of QEMU master from July 2026, in the tb-bus branch. Validated with macOS guests: display detection and removal, NVMe hotplug and unplug, USB storage mount, write, eject and replug with the data intact.
License
GPL-2.0-or-later, as QEMU; thunderbolt-vga.c keeps the MIT license of the stdvga code it is derived from.
Platforms
QEMU qemu-system-x86_64 with the q35 machine; macOS guests.

What it solves

Some guests cannot use direct PCIe hotplug for a device. macOS is the main validation target: it sees the device through a guest-visible Thunderbolt layer, even when direct PCIe hotplug of the same endpoint is not usable. Real and virtual devices can then be added to and removed from a running guest.

Key features

  • thunderbolt-root-port: a PCIe root port with its own thunderbolt-bus; its connected property disconnects and reconnects the whole port.
  • thunderbolt-pcie-pci-bridge: a PCIe-to-PCI bridge for tunnelled PCI endpoints, with Thunderbolt-related ACPI properties.
  • thunderbolt-vga: a hotpluggable stdvga-compatible display; the regular VGA device is unchanged and stays non-hotpluggable.
  • Examples for a display, USB storage behind an xHCI controller and an NVMe drive, all from the QEMU monitor.
  • A qtest for display hotplug and documentation in docs/specs.

How it works

The guest starts on a q35 machine with its normal boot display and an empty thunderbolt-root-port. In the QEMU monitor, device_add puts an endpoint on the port’s bus and device_del removes it; qom-set … connected false and true unplug and replug the whole port. The root port supplies the ACPI description and the PCIe hotplug signalling the guest sees; the endpoint device models are not changed.

(qemu) device_add thunderbolt-vga,id=tbvga0,bus=tbrp0,addr=0x00
(qemu) device_del tbvga0
(qemu) qom-set /machine/peripheral/tbrp0 connected false

Requirements

  • QEMU built from the tb-bus branch of the repository.
  • The q35 machine type; the examples use qemu-system-x86_64.
  • The boot display stays a regular VGA; a Thunderbolt display is added after boot.

This page summarises the repository’s README and documentation as of October 2026. The repository itself is the authoritative source.

Repository on GitHub ← All projects