Skip to content

RFC vfio: PCI device passthrough on Apple Silicon Macs

Scott J. Goldman qemu-devel 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 RFC Latest10 patches 14 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/10vfio/pci: Use the write side of EventNotifier for IRQ signalinghw/vfio/pci.c+25 -80 replies
2/10accel/hvf: avoid executable mappings for RAM-device memoryaccel/hvf/hvf-all.c+9 -11 reply
3/10vfio: Allow building on Darwin hostsKconfig.host backends/Kconfig hw/vfio/Kconfig +9 more+56 -130 replies
4/10vfio: Prepare existing code for Apple VFIO backendhw/vfio/device.c hw/vfio/pci.c hw/vfio/pci.h +2 more+29 -30 replies
5/10vfio: Add region_map and region_unmap callbacks to VFIODeviceIOOpshw/vfio-user/device.c hw/vfio/device.c hw/vfio/region.c +2 more+131 -360 replies
6/10vfio: Add device_reset callback to VFIODeviceIOOpshw/vfio/ap.c hw/vfio/ccw.c hw/vfio/device.c +3 more+29 -70 replies
7/10vfio/apple: Add DriverKit dext client libraryhw/vfio/apple-dext-client.c hw/vfio/apple-dext-client.h hw/vfio/meson.build+941 -00 replies
8/10vfio/apple: Add IOMMU container and PCI devicehw/vfio/apple-device.c hw/vfio/apple.h hw/vfio/container-apple.c +1 more+1264 -20 replies
9/10vfio/apple: Add apple-dma-pci companion devicedocs/specs/pci-ids.rst hw/vfio/apple-dma.c hw/vfio/meson.build +1 more+546 -30 replies
10/10docs: Add vfio-apple documentation and MAINTAINERS entryMAINTAINERS docs/system/device-emulation.rst docs/system/devices/vfio-apple.rst+172 -00 replies

Reviews trailers per patch

1 of 10 patches has a Reviewed-by or Acked-by.

PatchPhilippe Mathieu-Daudé
1/10
2/10R-b T-b
3/10
4/10
5/10
6/10
7/10
8/10
9/10
10/10

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v1 thread

Cover letter [RFC PATCH 00/10] vfio: PCI device passthrough on Apple Silicon Macs

This series adds VFIO PCI device passthrough support for Apple Silicon Macs running macOS, using a DriverKit extension (dext) as the host backend instead of the Linux VFIO kernel driver.

I'm sending this as an RFC because I'd like feedback before investing further in upstreaming. The code is functional. I've tested it with an NVIDIA RTX 5090 in a Thunderbolt dock on an M4 MacBook Air. GPU gaming works but is slow (~30 fps on high settings in Cyberpunk 2077 [1]), likely due to the BAR access penalty described below. AI inference workloads appear less affected. Ollama with Qwen 3.5 generates around 140 tok/sec on the same setup [2].

How it works:

On Linux, VFIO relies on kernel-managed IOMMU groups and /dev/vfio for device access and DMA mapping. On macOS, there is no equivalent kernel interface. Instead, a userspace DriverKit extension (VFIOUserPCIDriver) mediates access to the physical PCI device through IOKit's IOUserClient and PCIDriverKit APIs.

The series keeps the existing VFIOPCIDevice model and reuses QEMU's passthrough infrastructure. A few ioctl callsites are refactored into io_ops callbacks, the build system is extended for Darwin, and the Apple-specific backend plugs in behind those abstractions.

The guest sees two PCI devices: the passthrough device itself (vfio-apple-pci, which subclasses VFIOPCIDevice) and a companion DMA mapping device (apple-dma-pci). On the QEMU side, an AppleVFIOContainer implements the IOMMU backend, and a C client library wraps the IOUserClient calls to the dext for config space, BAR MMIO, interrupts, reset, and DMA.

DMA limitations:

This is the biggest platform constraint. Unlike a typical IOMMU mapping operation where the caller specifies the IOVA, the PCIDriverKit API (IODMACommand::PrepareForDMA) returns a system-assigned IOVA. There is no way to request a specific address. This means the guest's requested DMA addresses cannot be used directly. The guest kernel module must intercept DMA mapping calls and forward them through the companion device to get the actual hardware IOVA.

There are also hard platform limits: approximately 1.5 GB total mapped memory and roughly 64k concurrent mappings. Not all workloads will fit within these limits, though GPU gaming and LLM inference have worked in practice.

BAR access has performance issues as well. HVF does not expose controls to map device memory as cacheable in the guest, creating a significant performance penalty on BAR MMIO. Uncached mappings work correctly but slowly compared to what the hardware could do.

What works:
- PCI config space passthrough
- BAR MMIO via direct-mapped device memory
- MSI/MSI-X interrupts via async notification from the dext
- Device reset (FLR with hot-reset fallback)
- DMA mapping for guest device drivers

What doesn't work:
- Expansion ROM / VBIOS passthrough
- PCI BAR quirks
- VGA region passthrough
- Migration and dirty page tracking
- Hot-unplug

Questions for reviewers:

1. Is this something the VFIO maintainers would consider carrying upstream? The refactoring patches (3-6) are benign, but the Apple backend is a new platform with real limitations. That said, if Apple lifts some of the DART/HVF restrictions in a future macOS release, the code changes to take advantage would likely be minor. I'd like to understand whether this is in scope before doing the work to address review feedback on the full series.

2. The apple-dma-pci companion device: should this be a virtio device instead? I went with a simple custom PCI device because the virtio infrastructure didn't buy much for what is essentially a {map, unmap} register interface, but if virtio is preferred, what is the process for allocating a device ID? If a custom PCI device is the right approach, I've tentatively allocated 1b36:0015. Is there a process for reserving a device ID under the Red Hat PCI vendor, or is claiming it in pci-ids.rst sufficient? The guest-side kernel module hooks all DMA mapping functions for passed-through devices, which is unusual enough that I'm not sure it's upstreamable in the Linux kernel. I can maintain it out of tree if needed.

3. Should the macOS host-side DriverKit extension live in the QEMU tree? It's not included in this series and requires Apple code signing. I'm happy to keep it out of tree if that's preferred, or include the source if reviewers want it co-located.

4. The existing VFIO code includes <linux/vfio.h> from the linux-headers/ tree, which is intended to track upstream Linux UAPI headers. To make this compile on macOS, I added minimal stub headers (include/compat/linux/types.h and linux/ioctl.h) so the existing vfio.h parses on macOS without modification. An alternative would be to move an approximation of vfio.h into standard-headers/, but that felt against the spirit of tracking the latest upstream headers, and the standard-headers import process strips ioctls which the VFIO code relies on. I felt the stub approach was the least invasive, but I'm open to changing it if there's a preferred way to handle this.

[1] https://imgur.com/a/xoRS9kT
[2] https://imgur.com/a/ui4pYF0

Scott J. Goldman (10):
vfio/pci: Use the write side of EventNotifier for IRQ signaling accel/hvf: avoid executable mappings for RAM-device memory
vfio: Allow building on Darwin hosts
vfio: Prepare existing code for Apple VFIO backend
vfio: Add region_map and region_unmap callbacks to VFIODeviceIOOps
vfio: Add device_reset callback to VFIODeviceIOOps vfio/apple: Add DriverKit dext client library vfio/apple: Add IOMMU container and PCI device vfio/apple: Add apple-dma-pci companion device
docs: Add vfio-apple documentation and MAINTAINERS entry

 Kconfig.host                       |   3 +
 MAINTAINERS                        |  11 +
 accel/hvf/hvf-all.c                |  10 +-
 backends/Kconfig                   |   2 +-
 docs/specs/pci-ids.rst             |   3 +
 docs/system/device-emulation.rst   |   1 +
 docs/system/devices/vfio-apple.rst | 160 +++++
 hw/vfio-user/device.c              |  16 +-
 hw/vfio/Kconfig                    |   4 +-
 hw/vfio/ap.c                       |   4 +-
 hw/vfio/apple-device.c             | 945 +++++++++++++++++++++++++++++
 hw/vfio/apple-dext-client.c        | 681 +++++++++++++++++++++
 hw/vfio/apple-dext-client.h        | 253 ++++++++
 hw/vfio/apple-dma.c                | 540 +++++++++++++++++
 hw/vfio/apple.h                    |  74 +++
 hw/vfio/ccw.c                      |   2 +-
 hw/vfio/container-apple.c          | 241 ++++++++
 hw/vfio/device.c                   |  42 ++
 hw/vfio/meson.build                |  12 +-
 hw/vfio/migration.c                |   5 +-
 hw/vfio/pci.c                      |  50 +-
 hw/vfio/pci.h                      |   1 +
 hw/vfio/region.c                   | 108 ++--
 hw/vfio/types.h                    |   2 +
 hw/vfio/vfio-helpers.h             |   2 +-
 hw/vfio/vfio-migration-internal.h  |   4 +-
 hw/vfio/vfio-region.h              |   4 +
 include/compat/linux/ioctl.h       |   2 +
 include/compat/linux/types.h       |  26 +
 include/hw/pci/pci.h               |   1 +
 include/hw/vfio/vfio-container.h   |   1 +
 include/hw/vfio/vfio-device.h      |  40 +-
 meson.build                        |  10 +-
 util/event_notifier-posix.c        |   5 +-
 34 files changed, 3197 insertions(+), 68 deletions(-)
 create mode 100644 docs/system/devices/vfio-apple.rst
 create mode 100644 hw/vfio/apple-device.c
 create mode 100644 hw/vfio/apple-dext-client.c
 create mode 100644 hw/vfio/apple-dext-client.h
 create mode 100644 hw/vfio/apple-dma.c
 create mode 100644 hw/vfio/apple.h
 create mode 100644 hw/vfio/container-apple.c
 create mode 100644 include/compat/linux/ioctl.h
 create mode 100644 include/compat/linux/types.h
Signature · 1 line
2.50.1 (Apple Git-155)