{"id":2197507,"url":"http://patchwork.ozlabs.org/api/1.0/patches/2197507/?format=json","project":{"id":14,"url":"http://patchwork.ozlabs.org/api/1.0/projects/14/?format=json","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=json","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=json","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":"","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 ; 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 )\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 )\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 )\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 ","To":"","CC":", Peter Maydell , \"Thomas\n Huth\" , , ,\n , , Cornelia Huck\n , , Dorjoy Chowdhury\n , Pierrick Bouvier ,\n Paolo Bonzini , Tyler Fanelli ,\n , ","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 ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","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 \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 \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 `_\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"]}