Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/1.0/patches/2197507/?format=api
{ "id": 2197507, "url": "http://patchwork.ozlabs.org/api/1.0/patches/2197507/?format=api", "project": { "id": 14, "url": "http://patchwork.ozlabs.org/api/1.0/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": "" }, "msgid": "<20260218015151.4052-11-graf@amazon.com>", "date": "2026-02-18T01:51:50", "name": "[10/10] docs: Add Nitro Enclaves documentation", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "1bef60ba3f175e603c2046154b617313fa59c73d", "submitter": { "id": 76572, "url": "http://patchwork.ozlabs.org/api/1.0/people/76572/?format=api", "name": "Alexander Graf", "email": "graf@amazon.com" }, "delegate": null, "mbox": "http://patchwork.ozlabs.org/project/qemu-devel/patch/20260218015151.4052-11-graf@amazon.com/mbox/", "series": [ { "id": 492503, "url": "http://patchwork.ozlabs.org/api/1.0/series/492503/?format=api", "date": "2026-02-18T01:51:40", "name": "Native Nitro Enclaves support", "version": 1, "mbox": "http://patchwork.ozlabs.org/series/492503/mbox/" } ], "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/2197507/checks/", "tags": {}, "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=amazon.com header.i=@amazon.com header.a=rsa-sha256\n header.s=amazoncorp2 header.b=b8pikC+6;\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 4fG00z22ktz1xwr\n\tfor <incoming@patchwork.ozlabs.org>; Wed, 18 Feb 2026 12:53:55 +1100 (AEDT)", "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 1vsWkw-0000a2-Lu; Tue, 17 Feb 2026 20:53:34 -0500", "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 <prvs=502105d20=graf@amazon.de>)\n id 1vsWkv-0000YJ-Cg; Tue, 17 Feb 2026 20:53:33 -0500", "from pdx-out-014.esa.us-west-2.outbound.mail-perimeter.amazon.com\n ([35.83.148.184])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from <prvs=502105d20=graf@amazon.de>)\n id 1vsWkt-0005hY-BT; Tue, 17 Feb 2026 20:53:33 -0500", "from ip-10-5-6-203.us-west-2.compute.internal (HELO\n smtpout.naws.us-west-2.prod.farcaster.email.amazon.dev) ([10.5.6.203])\n by internal-pdx-out-014.esa.us-west-2.outbound.mail-perimeter.amazon.com with\n ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 18 Feb 2026 01:53:26 +0000", "from EX19MTAUWB002.ant.amazon.com [205.251.233.48:7051]\n by smtpin.naws.us-west-2.prod.farcaster.email.amazon.dev [10.0.11.41:2525]\n with esmtp (Farcaster)\n id 38446c7a-17e8-442f-be23-a47edb0fb50d;\n Wed, 18 Feb 2026 01:53:26 +0000 (UTC)", "from EX19D020UWC004.ant.amazon.com (10.13.138.149) by\n EX19MTAUWB002.ant.amazon.com (10.250.64.231) with Microsoft SMTP Server\n (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA) id 15.2.2562.35;\n Wed, 18 Feb 2026 01:53:26 +0000", "from ip-10-253-83-51.amazon.com (172.19.99.218) by\n EX19D020UWC004.ant.amazon.com (10.13.138.149) with Microsoft SMTP Server\n (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA) id 15.2.2562.35;\n Wed, 18 Feb 2026 01:53:23 +0000" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=amazon.com; i=@amazon.com; q=dns/txt; s=amazoncorp2;\n t=1771379611; x=1802915611;\n h=from:to:cc:subject:date:message-id:in-reply-to:\n references:mime-version:content-transfer-encoding;\n bh=3hLOH/1PH9KgMpnJK/l9v0L+U9NxjDuT0ZDVOs230+4=;\n b=b8pikC+6cFajKK4rpfUDa5OfTGHbW/BzeDSBQXrQUhHaHpcjiIDw0HdZ\n 887aGuywIwItqBJf3uCGmzXkQ1Dp/neIEQ+ucnUtawM15aPm2Mt2ta+rG\n fcZA3ifgct6WwLzQyTuVbZjcUHo1abGl5Ps/mbZ4paQrqKlkTClsUpUUJ\n C9iVWOGCyzvZOKJtazYXjfWXEOaueo2dF3p+WdD94S3mIRbD2H7VJImmQ\n vgULR9iu3eclXudxpWx1yMX6OF0R4yDy3rBSpXu0u107xsyCMukx8Bl7B\n tXyMJnPciAUAscyqffPb0gSzO5e61hI2qG4shxqSvWpppfckrZctMc9Lb A==;", "X-CSE-ConnectionGUID": "ziCxB2d/SJaHTzwBHvIBww==", "X-CSE-MsgGUID": "9r57eOH5Rtqe9eS9qu958w==", "X-IronPort-AV": "E=Sophos;i=\"6.21,297,1763424000\"; d=\"scan'208\";a=\"13037692\"", "X-Farcaster-Flow-ID": "38446c7a-17e8-442f-be23-a47edb0fb50d", "From": "Alexander Graf <graf@amazon.com>", "To": "<qemu-devel@nongnu.org>", "CC": "<qemu-arm@nongnu.org>, Peter Maydell <peter.maydell@linaro.org>, \"Thomas\n Huth\" <thuth@redhat.com>, <alex.bennee@linaro.org>, <philmd@linaro.org>,\n <berrange@redhat.com>, <marcandre.lureau@redhat.com>, Cornelia Huck\n <cohuck@redhat.com>, <mst@redhat.com>, Dorjoy Chowdhury\n <dorjoychy111@gmail.com>, Pierrick Bouvier <pierrick.bouvier@linaro.org>,\n Paolo Bonzini <pbonzini@redhat.com>, Tyler Fanelli <tfanelli@redhat.com>,\n <mknaust@amazon.com>, <nh-open-source@amazon.com>", "Subject": "[PATCH 10/10] docs: Add Nitro Enclaves documentation", "Date": "Wed, 18 Feb 2026 01:51:50 +0000", "Message-ID": "<20260218015151.4052-11-graf@amazon.com>", "X-Mailer": "git-send-email 2.47.1", "In-Reply-To": "<20260218015151.4052-1-graf@amazon.com>", "References": "<20260218015151.4052-1-graf@amazon.com>", "MIME-Version": "1.0", "X-Originating-IP": "[172.19.99.218]", "X-ClientProxiedBy": "EX19D032UWA004.ant.amazon.com (10.13.139.56) To\n EX19D020UWC004.ant.amazon.com (10.13.138.149)", "Content-Type": "text/plain; charset=\"us-ascii\"", "Content-Transfer-Encoding": "7bit", "Received-SPF": "pass client-ip=35.83.148.184;\n envelope-from=prvs=502105d20=graf@amazon.de;\n helo=pdx-out-014.esa.us-west-2.outbound.mail-perimeter.amazon.com", "X-Spam_score_int": "-19", "X-Spam_score": "-2.0", "X-Spam_bar": "--", "X-Spam_report": "(-2.0 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.043,\n DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1,\n HEADER_FROM_DIFFERENT_DOMAINS=0.001, RCVD_IN_DNSWL_NONE=-0.0001,\n RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001,\n SPF_HELO_NONE=0.001, T_SPF_PERMERROR=0.01,\n UNPARSEABLE_RELAY=0.001 autolearn=ham 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": "Now that all pieces are in place to spawn Nitro Enclaves using\na special purpose accelerator and machine model, document how\nto use it.\n\nSigned-off-by: Alexander Graf <graf@amazon.com>\n---\n MAINTAINERS | 1 +\n docs/system/confidential-guest-support.rst | 1 +\n docs/system/index.rst | 1 +\n docs/system/nitro.rst | 128 +++++++++++++++++++++\n 4 files changed, 131 insertions(+)\n create mode 100644 docs/system/nitro.rst", "diff": "diff --git a/MAINTAINERS b/MAINTAINERS\nindex 53ce075e9a..5e9e429530 100644\n--- a/MAINTAINERS\n+++ b/MAINTAINERS\n@@ -3027,6 +3027,7 @@ M: Alexander Graf <graf@amazon.com>\n S: Maintained\n F: hw/nitro/\n F: include/hw/nitro/\n+F: docs/system/nitro.rst\n \n Subsystems\n ----------\ndiff --git a/docs/system/confidential-guest-support.rst b/docs/system/confidential-guest-support.rst\nindex 66129fbab6..562a7c3c28 100644\n--- a/docs/system/confidential-guest-support.rst\n+++ b/docs/system/confidential-guest-support.rst\n@@ -41,5 +41,6 @@ Currently supported confidential guest mechanisms are:\n * Intel Trust Domain Extension (TDX) (see :doc:`i386/tdx`)\n * POWER Protected Execution Facility (PEF) (see :ref:`power-papr-protected-execution-facility-pef`)\n * s390x Protected Virtualization (PV) (see :doc:`s390x/protvirt`)\n+* AWS Nitro Enclaves (see :doc:`nitro`)\n \n Other mechanisms may be supported in future.\ndiff --git a/docs/system/index.rst b/docs/system/index.rst\nindex 427b020483..d297a95282 100644\n--- a/docs/system/index.rst\n+++ b/docs/system/index.rst\n@@ -39,5 +39,6 @@ or Hypervisor.Framework.\n multi-process\n confidential-guest-support\n igvm\n+ nitro\n vm-templating\n sriov\ndiff --git a/docs/system/nitro.rst b/docs/system/nitro.rst\nnew file mode 100644\nindex 0000000000..ebf118a108\n--- /dev/null\n+++ b/docs/system/nitro.rst\n@@ -0,0 +1,128 @@\n+AWS Nitro Enclaves\n+==================\n+\n+`AWS Nitro Enclaves <https://aws.amazon.com/ec2/nitro/nitro-enclaves/>`_\n+are isolated compute environments that run alongside EC2 instances.\n+They are created by partitioning CPU and memory resources from a parent\n+instance and launching a signed Enclave Image Format (EIF) file inside\n+a confidential VM managed by the Nitro Hypervisor.\n+\n+QEMU supports launching Nitro Enclaves on EC2 instances that have\n+enclave support enabled, using the ``nitro`` accelerator and the\n+``nitro`` machine type.\n+\n+Prerequisites\n+-------------\n+\n+* An EC2 instance with Nitro Enclaves enabled\n+* The ``nitro_enclaves`` kernel module loaded (provides ``/dev/nitro_enclaves``)\n+* CPU cores allocated to the Nitro Enclaves pool via ``nitro-enclaves-allocator``\n+* Huge pages allocated for Nitro Enclaves via ``nitro-enclaves-allocator``\n+\n+Quick Start\n+-----------\n+\n+Launch a Nitro Enclave from a pre-built EIF file::\n+\n+ $ qemu-system-x86_64 -accel nitro,debug-mode=on -M nitro -nographic \\\n+ -smp 2 -m 512M -kernel enclave.eif\n+\n+Launch an enclave from individual kernel and initrd files::\n+\n+ $ qemu-system-x86_64 -accel nitro,debug-mode=on -M nitro -nographic \\\n+ -smp 2 -m 512M -kernel vmlinuz -initrd initrd.cpio \\\n+ -append \"console=ttyS0\"\n+\n+The same commands work with ``qemu-system-aarch64`` on Graviton based EC2\n+instances.\n+\n+Accelerator\n+-----------\n+\n+The ``nitro`` accelerator (``-accel nitro``) drives the\n+``/dev/nitro_enclaves`` device to create and manage a Nitro Enclave.\n+It handles:\n+\n+* Creating the enclave VM slot\n+* Donating memory regions (must be huge page backed)\n+* Adding vCPUs (must be full physical cores)\n+* Starting the enclave\n+* Forwarding the enclave CID to devices that need it\n+\n+Accelerator options:\n+\n+``debug-mode=on|off``\n+ Enable debug mode. When enabled, the Nitro Hypervisor exposes the\n+ enclave's serial console output via a vsock port that the machine\n+ model automatically connects to. In debug mode, PCR values are zero.\n+ Default is ``off``.\n+\n+Machine\n+-------\n+\n+The ``nitro`` machine (``-M nitro``) is a minimal, architecture-independent\n+machine that provides only what a Nitro Enclave needs:\n+\n+* RAM (huge page backed via memfd)\n+* vCPUs (defaults to ``host`` CPU type)\n+* A heartbeat device (vsock server on port 9000)\n+* A serial console bridge (vsock client, debug mode only)\n+\n+Communication to the Nitro Enclave is limited to virtio-vsock. The Enclave\n+is allocated a CID at launch at which it is reachable. The CID is available\n+as QOM property in the accelerator and as a trace event.\n+\n+EIF Image Format\n+^^^^^^^^^^^^^^^^\n+\n+Nitro Enclaves boot from EIF (Enclave Image Format) files. When\n+``-kernel`` points to an EIF file (detected by the ``.eif`` magic\n+bytes), it is loaded directly into guest memory.\n+\n+When ``-kernel`` points to a regular kernel image (e.g. a bzImage or\n+Image), the machine automatically assembles a minimal EIF on the fly\n+from ``-kernel``, ``-initrd``, and ``-append``. This allows standard\n+direct kernel boot without external EIF tooling.\n+\n+CPU Requirements\n+^^^^^^^^^^^^^^^^\n+\n+Nitro Enclaves require full physical CPU cores. On hyperthreaded\n+systems, this means ``-smp`` must be a multiple of the threads per\n+core (typically 2).\n+\n+Nitro Enclaves can only consume cores that are donated to the Nitro Enclave\n+CPU pool. You can configure the CPU pool using the ``nitro-enclaves-allocator``\n+tool or manually by writing to the nitro_enclaves cpu pool parameter. To\n+allocate vCPUs 1, 2 and 3, you can call::\n+\n+ $ echo 1,2,3 | sudo tee /sys/module/nitro_enclaves/parameters/ne_cpus\n+\n+Beware that on x86-64 systems, hyperthread siblings are not consecutive\n+and must be added in pairs to the pool. Consult tools like ``lstopo``\n+or ``lscpu`` for details about your instance's CPU topology.\n+\n+Memory Requirements\n+^^^^^^^^^^^^^^^^^^^\n+\n+Enclave memory must be huge page backed. The machine automatically\n+creates a memfd memory backend with huge pages enabled. To make the\n+huge page allocation work, ensure that huge pages are reserved in\n+the system. To reserve 1 GiB of memory on a 4 KiB PAGE_SIZE system,\n+you can call::\n+\n+ $ echo 512 | sudo tee /proc/sys/vm/nr_hugepages\n+\n+Emulated Nitro Enclaves\n+-----------------------\n+\n+In addition to the native Nitro Enclaves invocation, you can also use\n+the emulated nitro-enclave machine target (see :doc:`i386/nitro-enclave`)\n+which implements the x86 Nitro Enclave device model. While -M nitro\n+delegates virtual machine device emulation to the Nitro Hypervisor, -M\n+nitro-enclave implements all devices itself, which means it also works\n+on non-EC2 instances.\n+\n+If you require NSM based attestation backed by valid AWS certificates,\n+you must use -M nitro. The -M nitro-enclave model does not provide\n+you with an AWS signed attestation document.\n", "prefixes": [ "10/10" ] }