Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/1.2/patches/2219885/?format=api
{ "id": 2219885, "url": "http://patchwork.ozlabs.org/api/1.2/patches/2219885/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/patch/20260405072857.66484-11-scottjgo@gmail.com/", "project": { "id": 14, "url": "http://patchwork.ozlabs.org/api/1.2/projects/14/?format=api", "name": "QEMU Development", "link_name": "qemu-devel", "list_id": "qemu-devel.nongnu.org", "list_email": "qemu-devel@nongnu.org", "web_url": "", "scm_url": "", "webscm_url": "", "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<20260405072857.66484-11-scottjgo@gmail.com>", "list_archive_url": null, "date": "2026-04-05T07:28:54", "name": "[RFC,10/10] docs: Add vfio-apple documentation and MAINTAINERS entry", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "4d4e594e0886c81f03e57a52b92bf70595ea8f52", "submitter": { "id": 93060, "url": "http://patchwork.ozlabs.org/api/1.2/people/93060/?format=api", "name": "Scott J. Goldman", "email": "scottjgo@gmail.com" }, "delegate": null, "mbox": "http://patchwork.ozlabs.org/project/qemu-devel/patch/20260405072857.66484-11-scottjgo@gmail.com/mbox/", "series": [ { "id": 498765, "url": "http://patchwork.ozlabs.org/api/1.2/series/498765/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/list/?series=498765", "date": "2026-04-05T07:28:44", "name": "vfio: PCI device passthrough on Apple Silicon Macs", "version": 1, "mbox": "http://patchwork.ozlabs.org/series/498765/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/2219885/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/2219885/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>", "X-Original-To": "incoming@patchwork.ozlabs.org", "Delivered-To": "patchwork-incoming@legolas.ozlabs.org", "Authentication-Results": [ "legolas.ozlabs.org;\n\tdkim=pass (2048-bit key;\n unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256\n header.s=20251104 header.b=TbknRV7n;\n\tdkim-atps=neutral", "legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=patchwork.ozlabs.org)" ], "Received": [ "from lists.gnu.org (lists.gnu.org [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4fpPJc5j6Vz1y2d\n\tfor <incoming@patchwork.ozlabs.org>; Sun, 05 Apr 2026 17:30:56 +1000 (AEST)", "from localhost ([::1] helo=lists1p.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from <qemu-devel-bounces@nongnu.org>)\n\tid 1w9HvW-0003zm-AO; Sun, 05 Apr 2026 03:29:46 -0400", "from eggs.gnu.org ([2001:470:142:3::10])\n by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from <scottjgo@gmail.com>)\n id 1w9HvU-0003yu-Ni\n for qemu-devel@nongnu.org; Sun, 05 Apr 2026 03:29:44 -0400", "from mail-dy1-x132a.google.com ([2607:f8b0:4864:20::132a])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)\n (Exim 4.90_1) (envelope-from <scottjgo@gmail.com>)\n id 1w9HvS-0007QM-1W\n for qemu-devel@nongnu.org; Sun, 05 Apr 2026 03:29:44 -0400", "by mail-dy1-x132a.google.com with SMTP id\n 5a478bee46e88-2cea94c06e4so160414eec.1\n for <qemu-devel@nongnu.org>; Sun, 05 Apr 2026 00:29:41 -0700 (PDT)", "from localhost.localdomain ([2601:645:8200:47:41e4:ff2b:ff70:4d75])\n by smtp.gmail.com with ESMTPSA id\n 5a478bee46e88-2cb92ea0ef1sm7636502eec.21.2026.04.05.00.29.38\n (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256);\n Sun, 05 Apr 2026 00:29:39 -0700 (PDT)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=gmail.com; s=20251104; t=1775374180; x=1775978980; darn=nongnu.org;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:from:to:cc:subject:date\n :message-id:reply-to;\n bh=E5HDXr0HjZKWX3A8XRFgsqoTXAEWhIhEwLxgd+5/kSA=;\n b=TbknRV7n4h4VurYz7hTgPUgn/ZBB6fGxW0VhvXbRArLBEyBSbgSAz4XDvZTsttTN9p\n tW7aY02hXhqatv1+wT7xtkyHrJcYcV4m5oWLpJNdhaFTrzglaXXOeENdCOHR7DepNQi3\n GypUaL7dkEwnt3tknvs+ueyATLjytlQaPdOT5Z74LsKniqEsyI7JD+ElOLXkDV6ka9CL\n fapThuevFxZuzRECfbdMHlsTARm9F1boMPWCxncN82gTMW1HbEFMhAlai6bCVOuysK2Q\n 6coqLG8kcY4Pmrh4NPqa4z2xGZcIzN9Kor+Ezp/lYSMl7pjNHJwMpu1npMJ2y/iTVY7V\n /68A==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20251104; t=1775374180; x=1775978980;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from\n :to:cc:subject:date:message-id:reply-to;\n bh=E5HDXr0HjZKWX3A8XRFgsqoTXAEWhIhEwLxgd+5/kSA=;\n b=m06MIamkczz2M5loMJ/Vl8hUn1caGN5MJOXE4b0sAjoXMvS68bXw3qyUsxlwMdg2Kw\n 3QLOyLq/K7EKccvWPnpxfifunnWFpOpsEiLgmtlQoWgXjLD48qqUmTDBw3TJ19swZvkl\n OB12KQvmBaGuybr+h2/UcmE/n6QS8+QYJjbD1kRrvLPmyX8bMA9M2hly1Nb9AflEKrDu\n rgiJNxBIx2pTBmnT42Z0Bl3i+KiME7/k9BPg4M2JCQMTl6eGKa2IBaF2LzjPqB5czg75\n z08YWnIEaRmPLhZGv7UG3RJVAB72+FidbKG9fzzgYGzdfBZcqARJnNRmv1SJEPgs2S0Y\n 32NQ==", "X-Gm-Message-State": "AOJu0YzJXKFRB/RJ2I58j+nSxywDvxUWNW7yM8yPRs1yB+GCGEU/uPMd\n pHS7vBYbrQjPXYyAdvpfXRHO4muRIjYDBrPBzta30IEg5q2g4jZcFzwX0Rpq40AwmFs=", "X-Gm-Gg": "AeBDievtIJAJNVMHp53WA6A9VZOrW9B/R1PdvA6yyDE6orKr92Wegztz/xUacczAZ0J\n 0RhEhLWBCya9xTHWo6BZdoALKgixVDMy8P+RN+L5reDUl3TFOT3JOYhGjndcLPXb03heWRU/GRZ\n FzdhgQGvPcqOKrlUgsqCx/YENM4Ttq399sbxv4DLyGo1biNxRndzGJ514Sjk37b9nfLkT0yGdWL\n H1zAzram1nIcBbhR/cHLLHou2RNeio1AVHI9S9fbgxX9Ej45kXeyUaouW+rRpaDJTJnaffzgG2H\n Foch7wib9HTPh4SOSA8Dphe1DfCowweJE8TmKPsqgOuSTZpoAl3AvewsNnCZJqIhplAthTbiwI2\n Nx6hMlb8W3TD9CsG9mIhay/riATx+9zfgXKB4K403D2lwu3t2KWoYOeDhIWns7kCCfF1n2MSLop\n u3/+qcpeH2syht417svkCgK8oz+VL4vmlklB9FawbtTuLKIh2aq7sjBOFVzQEvpo/ANonsKeadE\n cBPWBROmBlxubdsiD6Mhsd6mwU=", "X-Received": "by 2002:a05:7301:3f09:b0:2c0:df3b:ec1e with SMTP id\n 5a478bee46e88-2cad7e3729fmr4300085eec.11.1775374180189;\n Sun, 05 Apr 2026 00:29:40 -0700 (PDT)", "From": "\"Scott J. Goldman\" <scottjgo@gmail.com>", "To": "qemu-devel@nongnu.org", "Cc": "alex@shazbot.org, clg@redhat.com, pbonzini@redhat.com, rbolshakov@ddn.com,\n phil@philjordan.eu, mst@redhat.com, john.levon@nutanix.com,\n thanos.makatos@nutanix.com, qemu-s390x@nongnu.org,\n \"Scott J. Goldman\" <scottjg@umich.edu>,\n \"Scott J. Goldman\" <scottjgo@gmail.com>", "Subject": "[RFC PATCH 10/10] docs: Add vfio-apple documentation and MAINTAINERS\n entry", "Date": "Sun, 5 Apr 2026 00:28:54 -0700", "Message-ID": "<20260405072857.66484-11-scottjgo@gmail.com>", "X-Mailer": "git-send-email 2.50.1", "In-Reply-To": "<20260405072857.66484-1-scottjgo@gmail.com>", "References": "<20260405072857.66484-1-scottjgo@gmail.com>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "Content-Transfer-Encoding": "8bit", "Received-SPF": "pass client-ip=2607:f8b0:4864:20::132a;\n envelope-from=scottjgo@gmail.com; helo=mail-dy1-x132a.google.com", "X-Spam_score_int": "-20", "X-Spam_score": "-2.1", "X-Spam_bar": "--", "X-Spam_report": "(-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,\n DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001,\n RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001,\n SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no", "X-Spam_action": "no action", "X-BeenThere": "qemu-devel@nongnu.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "qemu development <qemu-devel.nongnu.org>", "List-Unsubscribe": "<https://lists.nongnu.org/mailman/options/qemu-devel>,\n <mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>", "List-Archive": "<https://lists.nongnu.org/archive/html/qemu-devel>", "List-Post": "<mailto:qemu-devel@nongnu.org>", "List-Help": "<mailto:qemu-devel-request@nongnu.org?subject=help>", "List-Subscribe": "<https://lists.nongnu.org/mailman/listinfo/qemu-devel>,\n <mailto:qemu-devel-request@nongnu.org?subject=subscribe>", "Errors-To": "qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org", "Sender": "qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org" }, "content": "From: \"Scott J. Goldman\" <scottjg@umich.edu>\n\nAdd documentation for the Apple VFIO passthrough backend covering\nrequirements, usage, the DMA companion device protocol, and known\nlimitations. Register the vfio-apple files in MAINTAINERS.\n\nSigned-off-by: Scott J. Goldman <scottjgo@gmail.com>\n---\n MAINTAINERS | 11 ++\n docs/system/device-emulation.rst | 1 +\n docs/system/devices/vfio-apple.rst | 160 +++++++++++++++++++++++++++++\n 3 files changed, 172 insertions(+)\n create mode 100644 docs/system/devices/vfio-apple.rst", "diff": "diff --git a/MAINTAINERS b/MAINTAINERS\nindex ad215eced8..baed89cbf7 100644\n--- a/MAINTAINERS\n+++ b/MAINTAINERS\n@@ -2338,6 +2338,17 @@ F: qapi/vfio.json\n F: migration/vfio-stub.c\n F: tests/functional/aarch64/test_device_passthrough.py\n \n+vfio-apple\n+M: Scott J. Goldman <scottjgo@gmail.com>\n+S: Maintained\n+F: hw/vfio/apple-device.c\n+F: hw/vfio/apple-dext-client.c\n+F: hw/vfio/apple-dext-client.h\n+F: hw/vfio/apple-dma.c\n+F: hw/vfio/apple.h\n+F: hw/vfio/container-apple.c\n+F: include/compat/linux/\n+\n vfio-igd\n M: Alex Williamson <alex@shazbot.org>\n M: Cédric Le Goater <clg@redhat.com>\ndiff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst\nindex 40054bb7df..aa3dbfa1e0 100644\n--- a/docs/system/device-emulation.rst\n+++ b/docs/system/device-emulation.rst\n@@ -98,4 +98,5 @@ Emulated Devices\n devices/scsi/index.rst\n devices/usb-u2f.rst\n devices/usb.rst\n+ devices/vfio-apple.rst\n devices/vfio-user.rst\ndiff --git a/docs/system/devices/vfio-apple.rst b/docs/system/devices/vfio-apple.rst\nnew file mode 100644\nindex 0000000000..b0e92f3b96\n--- /dev/null\n+++ b/docs/system/devices/vfio-apple.rst\n@@ -0,0 +1,160 @@\n+.. SPDX-License-Identifier: GPL-2.0-or-later\n+.. _vfio-apple:\n+\n+======================\n+vfio-apple (macOS/ARM)\n+======================\n+\n+QEMU supports PCI device passthrough on Apple Silicon Macs using a macOS\n+DriverKit extension (dext) as the host backend. Unlike Linux VFIO, which\n+relies on kernel-managed IOMMU groups and ``/dev/vfio``, the Apple backend\n+communicates with a userspace driver extension through IOKit's\n+``IOUserClient`` interface.\n+\n+Requirements\n+============\n+\n+- Apple Silicon Mac running macOS\n+- A DriverKit extension (``VFIOUserPCIDriver``) installed and running for\n+ the target PCI device\n+- QEMU built with ``--enable-hvf`` on a Darwin host\n+- A guest kernel module that speaks the ``apple-dma-pci`` protocol (see\n+ below)\n+\n+Usage\n+=====\n+\n+Specify the host PCI device by its bus/device/function address:\n+\n+.. code-block:: console\n+\n+ -device vfio-apple-pci,host=01:00.0\n+\n+This creates a ``vfio-apple-pci`` device that connects to the dext instance\n+managing the given host PCI BDF. A companion ``apple-dma-pci`` device is\n+automatically created on the same bus.\n+\n+Architecture\n+============\n+\n+The implementation consists of several components:\n+\n+``vfio-apple-pci``\n+ A QOM subclass of ``vfio-pci`` that overrides realize/exit to set up the\n+ Apple-specific IOMMU container and interrupt delivery.\n+\n+``vfio-iommu-apple``\n+ An IOMMU container backend. DMA map/unmap through the container are\n+ no-ops because DMA is managed separately through the companion device\n+ (see below).\n+\n+``apple-dma-pci``\n+ A paravirtualized PCI device that provides batched DMA map/unmap\n+ operations between the guest and the dext. The guest driver writes a\n+ command page GPA to BAR0 registers, fills request/response buffers in\n+ RAM, then triggers processing with a single doorbell write (one VMEXIT\n+ per batch).\n+\n+``Dext communication``\n+ All host device access (config space, BAR MMIO, DMA registration,\n+ interrupt notification) goes through IOKit ``IOConnectCallMethod`` calls to\n+ the dext's ``IOUserClient``.\n+\n+DMA mapping\n+-----------\n+\n+On Linux, VFIO programs the hardware IOMMU directly via kernel ioctls.\n+QEMU chooses IOVAs and the kernel maps them through the IOMMU.\n+\n+On macOS, the DART (Apple's IOMMU) is managed entirely by the DriverKit\n+extension. QEMU cannot choose IOVAs — it can only request that a host\n+virtual address be mapped for DMA, and the platform assigns the resulting\n+IOVA. This means the guest cannot assume any particular IOVA layout;\n+the ``apple-dma-pci`` companion device returns the platform-assigned IOVA\n+and bus address in its response entries.\n+\n+Because of this architecture, a **guest kernel module** is required to\n+drive the ``apple-dma-pci`` device. The module discovers the companion\n+device, submits map/unmap batches, and translates between guest physical\n+addresses and the platform-assigned DMA addresses that the passthrough\n+device will use.\n+\n+Platform constraints\n+--------------------\n+\n+The macOS DART imposes limits that do not exist with Linux VFIO:\n+\n+- **No IOVA alignment guarantees**: the platform may return any address.\n+ Guest drivers that assume page-aligned or naturally-aligned DMA\n+ addresses must account for this.\n+- **Total DMA memory limit**: approximately 1.5 GB of guest memory can be\n+ registered for DMA at any time.\n+- **Mapping count limit**: approximately 64k concurrent DMA mappings.\n+\n+These limits are enforced by the DART hardware and DriverKit, not by QEMU.\n+Exceeding them will cause map requests to fail.\n+\n+``apple-dma-pci`` register interface\n+-------------------------------------\n+\n+.. list-table::\n+ :header-rows: 1\n+\n+ * - Offset\n+ - Name\n+ - Access\n+ - Description\n+ * - 0x00\n+ - VERSION\n+ - R\n+ - Protocol version\n+ * - 0x04\n+ - MANAGED_BDF\n+ - R\n+ - Guest BDF this device maps for\n+ * - 0x08\n+ - MAX_ENTRIES\n+ - R\n+ - Maximum entries per batch\n+ * - 0x0C\n+ - STATUS\n+ - R\n+ - Result of last doorbell\n+ * - 0x10\n+ - CMD_GPA_LO\n+ - W\n+ - Command page GPA [31:0]\n+ * - 0x14\n+ - CMD_GPA_HI\n+ - W\n+ - Command page GPA [63:32]\n+ * - 0x18\n+ - DOORBELL\n+ - W\n+ - Any write triggers batch processing\n+\n+Interrupts\n+----------\n+\n+The dext tracks pending hardware interrupts (MSI/MSI-X) in a bitfield\n+(one bit per vector, up to 256 vectors). When a hardware interrupt fires,\n+the dext sets the corresponding bit and completes an asynchronous\n+notification to QEMU via ``IOConnectCallAsyncMethod``. The notification\n+is dispatched through a GCD queue, which wakes the QEMU main loop via an\n+``EventNotifier`` pipe. QEMU then atomically reads and clears the pending\n+bits and delivers each flagged vector to the guest.\n+\n+Limitations\n+===========\n+\n+- **Guest kernel module required**: the ``apple-dma-pci`` protocol is not\n+ handled by standard guest drivers.\n+- **No migration support**: the Apple container does not support dirty page\n+ tracking.\n+- **Interrupt delivery**: interrupts are delivered asynchronously via IOKit\n+ rather than directly by the kernel, adding some overhead compared to\n+ Linux VFIO.\n+- **No hot-plug**: devices must be configured at VM startup.\n+- **DMA constraints**: see `Platform constraints`_ above.\n+- **Darwin only**: the base ``vfio-pci`` device type is not user-creatable\n+ on Darwin; use ``vfio-apple-pci`` instead.\n", "prefixes": [ "RFC", "10/10" ] }