From nobody Tue Sep 9 19:11:26 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; arc=fail (BodyHash is different from the expected one); dmarc=pass(p=reject dis=none) header.from=lists.libvirt.org Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1753255625765465.2013577932096; Wed, 23 Jul 2025 00:27:05 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 996) id C5B0D146B; Wed, 23 Jul 2025 03:27:04 -0400 (EDT) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 1F26614BD; Wed, 23 Jul 2025 03:22:52 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 991B211BA; Tue, 22 Jul 2025 16:26:30 -0400 (EDT) Received: from NAM02-SN1-obe.outbound.protection.outlook.com (mail-sn1nam02on2083.outbound.protection.outlook.com [40.107.96.83]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id EADE511B3 for ; Tue, 22 Jul 2025 16:26:29 -0400 (EDT) Received: from CH0PR12MB5092.namprd12.prod.outlook.com (2603:10b6:610:bf::16) by CY5PR12MB6346.namprd12.prod.outlook.com (2603:10b6:930:21::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.8964.21; Tue, 22 Jul 2025 20:26:27 +0000 Received: from CH0PR12MB5092.namprd12.prod.outlook.com ([fe80::969b:49e4:6d48:b058]) by CH0PR12MB5092.namprd12.prod.outlook.com ([fe80::969b:49e4:6d48:b058%5]) with mapi id 15.20.8943.029; Tue, 22 Jul 2025 20:26:27 +0000 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, FORGED_SPF_HELO,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_PASS autolearn=no autolearn_force=no version=3.4.4 ARC-Seal: i=1; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=none; b=pSm5ELt5TAmPHHGBbEYFP7ajyZ0UdW73rkowFuVqbR07a/BghMAPXJyQPHqxvJaRSGUY3egEbe62TTryL1lGlbcY7Y+1v4C8JUaSom/2X1IyqhwVHheMzzA+F2M+UUcycECTai5ym//heWfw3wQEHM91ldnSLRGAhmEWn6PpvmF0YOeUelbtxZDu2juPwu8I3q91kWuwEpFxmm1HgQkeXS/2hnKNFRfVLk7piOBs+x79jL3gBh/YI4YjnGcNd15nC+RXFjQ1REEPwGUsTtY5Am5D7gbnU5Ek87YTnJy9MGdc5V4xj8lYmWE1/ok8a78oKT3j9FvLoK28bjR4Ntd2eQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector10001; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=jtvaQRawwIMOsI7BUWynh0PevLcKAiflIbVseA2W5Ec=; b=mg8GpDE9rFsADM2177vy7WAUjuoNDWWM4GaC/h7lhEdX9bQNC3RURfVsYkWvv+32dPtkJFK3js9jptlaym9f3LLZcxp/OnMMA9qT19HhKCKrJei2drI3d4vXPimQbtBs4EqW7ru8UcYaKRBT6gEQMDxwEpPyN4D1z7P5VpB5kSxsCET8Jo3ZB/tRt6BesIp6IeNX1zscSaGpOUXWKDVbXoHW99BpLjet3i7X8wLfuJYf4RhhJOVK+5KZJZrIGUoq3mhxAg5ffwC0nLIlPHUvJ0o9i/fiHEXopI6TXA/RnrjGLYEnXsjYthuWhALpCp7FQPpYxdBdb/7stjjshsicBA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=nvidia.com; dmarc=pass action=none header.from=nvidia.com; dkim=pass header.d=nvidia.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=Nvidia.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=jtvaQRawwIMOsI7BUWynh0PevLcKAiflIbVseA2W5Ec=; b=RmGkbGfSpJCM9j2X/t1Q+VfKaUtkJV9rJ+7lKuevdBlfy6rlyyRzkkiBXAQo55v9PCBvevgWnYz/z7fgQQpKkavWozGvQuyhGmZqV0LcDY7PlIBbvdS+wybkZSIYqJJqH+n4G63j9S9EudPh3C8PHXY8cSTHvz7lhIz93GtTifzfdWNb3XczWN269uJn3NgzvidtJKdo28lCE4LGL7YhQ4ptaG/vParm4DaYJrp3jR5LaKNEHu+KU7SNLVcEERnubKefBMScXgwj9pWhW5MBZnpb9Z/vOJqv8jBs1y2o380DetjJLVeHfbIG+T/Kq2sDhQvti703ImkY6zC9CqDPzQ== Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=nvidia.com; To: devel@lists.libvirt.org Subject: [RFC PATCH 7/8] docs: Document ACPI EGM memory device Date: Tue, 22 Jul 2025 15:26:07 -0500 Message-ID: <20250722202609.1823658-8-ianm@nvidia.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250722202609.1823658-1-ianm@nvidia.com> References: <20250722202609.1823658-1-ianm@nvidia.com> X-ClientProxiedBy: SA0PR11CA0033.namprd11.prod.outlook.com (2603:10b6:806:d0::8) To CH0PR12MB5092.namprd12.prod.outlook.com (2603:10b6:610:bf::16) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: CH0PR12MB5092:EE_|CY5PR12MB6346:EE_ X-MS-Office365-Filtering-Correlation-Id: ce5af733-f858-41e5-fe5a-08ddc95e0912 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0;ARA:13230040|1800799024|366016|376014; X-Microsoft-Antispam-Message-Info: =?us-ascii?Q?WOeVy3U1ABCxwBI2RPTD2JAUPlQUSYwwc8RwAF26CxSydTSWsr7vqLomg2ft?= =?us-ascii?Q?jkirUaWqjha4+emqwZDmpsqr2ts2kmnEOVllAoC2KMyvhDI787EQI5kmBDwE?= =?us-ascii?Q?keVhraYtsGfqsgkDQG3f/vzuQARSCAWRiUygejHYQ9jKGXTpnWUu0WFIjOJt?= =?us-ascii?Q?1eWNQmzehFmpfdYgItJB7XA+MLeHgCR+XLu2U/u7GBW1xSXQBoRSR8ktSxAQ?= =?us-ascii?Q?lT+FAIzM5S+GEc+wiEA7ufnaHhFs9OEXxHnuyxXfaZy9SdMlCMxu8bQ9j1cZ?= =?us-ascii?Q?W28mEk4rNeiDIH9rZ7doF7ZxSjh4qu6EUcNqdIBnghtoAU72AQ3ALt+E5ZUR?= =?us-ascii?Q?7Jf4+gxOIvMYjMljLQnkpJQAu5XFlYDuJQo350zEu7VUGZXHZG4U33vsMk5a?= =?us-ascii?Q?pTewI+SqHYAqZXZqcdi0DBjj0qnov6EaaYyNG/6DLnu8Wt4wu0bkLfBAbmeM?= =?us-ascii?Q?8JeJ3ZyvSfZyHbFiDcgkof/DGRyPnDmfqPwyxFHJjECliYcWrf7AmOBqqjmB?= =?us-ascii?Q?xnRrnq/6yNU+e9zL9vn2NjWxXv2HsI1kOmQfcUbYsqT0avCXPEsdRIjiOTW4?= =?us-ascii?Q?Ha20u3bvLdMehi/M+B0/sV2WKjuRwlOQ8/AFhez5GlAGkXg2gEHEifeGFiGU?= =?us-ascii?Q?c3wakAAV4GouS99kB+u6BTB9HeG7l4nQYoWBKF/8M3eLxBTGcXdYYsCMj7iS?= =?us-ascii?Q?YrLwZGKmi5K4qyGEPZ2TFzjvYWcyLwR8tFp5XZg25l8S39eCIm/LRDWcsXsO?= =?us-ascii?Q?nYbsOAlaBELiv6QM+mVR4Gmgf47uEDQbfKtvG1PniW27VL8aGZGjDWz+6nCx?= =?us-ascii?Q?nYBgXA/cX0SNycy5qjdsuzOA8LFm7cG6KTIUgoiqqXC9MFLErHB46VAdlT5z?= =?us-ascii?Q?dM4dLBSZJDbGKlFIFzAUB7avI8en61y+vsjeH6jND7sjZnmpZzdHg0UGoDuw?= =?us-ascii?Q?HhCyG47sNUP9pgz1H86iyaHcZkgZUdyR6zogxsSJrleSjHCg6qCHp48K22FK?= =?us-ascii?Q?VKw2sjZ2egcKk06RD9wQ5lzEAId2noXhCOW3O0LuCyNdW/Hart11u7i9zjJt?= =?us-ascii?Q?XdXopyIkyUVHLxEG8khTDQAZqQ8Qi5B5G2S6KwUuhItveFhpZU4lZ/TMgTCT?= =?us-ascii?Q?mYIULD1JkZtsen9DvUOlZW91YqRO/GyxZTz+qbkTf0EFHnpJVzOOyDbA6iyL?= =?us-ascii?Q?aInnzm8xUugsPzR203zaCTCGF+BA06E38xxpHva6UTjzR8kykdUfAsOoTC+A?= =?us-ascii?Q?ZYFdzeTP7enOynZojlf5hZVW1Iti8CDK2LotLz4k3VNndnkmm+s7MRpxWRI5?= =?us-ascii?Q?uTZjN9uZ5c9xYN6iK341gHWrLaIKBnbd3gnCnULJpGx+QkWTusdc5ivwzkLg?= =?us-ascii?Q?09AjzFnhT3U69z0ID3JO838e9RtdsNTOwVlVUV5EEZ9aGiACAzns67FGxvKx?= =?us-ascii?Q?xDKRK/9Giu0=3D?= X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:CH0PR12MB5092.namprd12.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230040)(1800799024)(366016)(376014);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?lL/2+oTv6V8kydSnbHmVhJ4EkymYNYKS25Ay+BEAtxOLNvyGBJSQv7kqXZNa?= =?us-ascii?Q?2uaXps++9KnyNDkRxHSA8L9kmIo/NVpcmccXhdv1oCUty78s/lG+9umQuPnO?= =?us-ascii?Q?godAhr+tA+r6yBMucIX0KY7OinQP9VzkIcT98ebCB1Qfv9MT3urzc8WLDkP5?= =?us-ascii?Q?5TKqEeW8UcdV+/V/X4EEOORHOpBp5TDlLMjtMnZlFE6j1yg5siK6LP7fRaAE?= =?us-ascii?Q?EGg8GaLVV9milpMszvbn9xQo3NVna4RakA5lAmCY1X3EBqJAFOs6NUhkBsM4?= =?us-ascii?Q?i/+f2B1Tz8t6xiP4HtDz+CJ/ltdorFd43Ob7+V7Cj1OKvAvrvLvDHZkjq2M/?= =?us-ascii?Q?kJRkm1n9VRsoHMG5U9jHf+Jiegmfizgj0xupVHFOBm6KB/02npiEViK9T4xM?= =?us-ascii?Q?NemdnJrrMfApV5/41nUZ/1pYLb/odQCW1asYytpJi692BdcsvvmTj0ihfMCn?= =?us-ascii?Q?5UocHmIuQE9qy0x3664pa52l+8xSYlaoeuGntNKyXlqL+Dzodr49v54idH+k?= =?us-ascii?Q?0yIClSoCnHc7RFwZYHs5fqv4bKyueYyD0wPO29Wn7/1j8FguQ6Pci852vpmA?= =?us-ascii?Q?VfX2IXQHpOwWbzqZhhsFDMHAjDRxV8FJqM/udCqRwWC1jmXvCsrh0Sdk1cLi?= =?us-ascii?Q?zprpEJOOyWHpSwST3tAQO3Nb4aMbLbPnDyww6goAR+TKrsYupLkTUxqZUafM?= =?us-ascii?Q?xY5tLmcV6C79d0NBYzhcpc7iiHidlCjKGop9WJOcVhGTa1OlY4uM5YVD13NW?= =?us-ascii?Q?Zjp8/guXprJ1Nn+pwFJO4XGqDpW4ZG1M4OQm6nB0+b4G5q+phUIRIQwH64VP?= =?us-ascii?Q?dTDu7JYFJD3ic6XKoSVCZeyt/7a7ifq1lLCaqIGhm7/u8Ksw2tGDWFt1IltG?= =?us-ascii?Q?EaoIfCgUJ5WSWteJPJiLu4SvC1VsUGLfnZfJAkRc/xF5hSLkHuV2YdN1wE39?= =?us-ascii?Q?AAOrX0ggKQjoMLzfXB2NwifR7oCV6GAbm0zzquVlnw2ryjwnUkJ4A1dil1ZH?= =?us-ascii?Q?h9bQAwfoZTRh46T6xnhbiIazux4MbCC7/sa27EigWulsknD+xdPR3TfZHGsg?= =?us-ascii?Q?uvMNlAcFOM9dqg2EPVXa4BqMjILMMnzgTRoE06lz8DrlTJSy3GTAp9dMICtC?= =?us-ascii?Q?U/9ZnZA/tkCQZhgM5JMgyMLfPLshT/nBM1wmCdK1p1wHhiCJ8G5kL0gu7BRC?= =?us-ascii?Q?ZYhRi+fxYjmF6ur8iA89CrlFExJmJue9rgSSRcrowRzHviAiDmbMI+eG25TM?= =?us-ascii?Q?ZD4mlSuPUxkomQvKT64fV1UicWeVpe2aHTjL9/kQdX8gZNYiFYThkynLJtcx?= =?us-ascii?Q?m7nmUVc0vK5405iQDdg4+RdjtO3/2jvVD1BokoN+ZHrP3/jDaLEdX02JOOjK?= =?us-ascii?Q?pGF9PtHcsm8eBqgkZBINIKE1KxTOzCbJ2CznCdwjLxuVAJomZb/3ak+dMH5t?= =?us-ascii?Q?fPk35mLtPvss96UQIii55zbepSHVPiamtuTVZdt0GTVdQCPt2DgVzlPYcVAF?= =?us-ascii?Q?ggamQJQLoCchGjwgqMSguXadxM2q96Q8+de9KtbVw6FUeKhYeo2jxeF0LYQ6?= =?us-ascii?Q?tT8ypLk1w5upRJAJOjTMeyjex+4H7SNtzdi1H2wu?= X-OriginatorOrg: Nvidia.com X-MS-Exchange-CrossTenant-Network-Message-Id: ce5af733-f858-41e5-fe5a-08ddc95e0912 X-MS-Exchange-CrossTenant-AuthSource: CH0PR12MB5092.namprd12.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 22 Jul 2025 20:26:27.4131 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 43083d15-7273-40c1-b7db-39efd9ccc17a X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: gSjM+lL1jMI4DVbpjHPTS/7cY+bz42m7uqzM1x0KR49ni61/XFQcgN87jEoBXTj0 X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY5PR12MB6346 Content-Transfer-Encoding: quoted-printable X-MailFrom: ianm@nvidia.com X-Mailman-Rule-Hits: nonmember-moderation X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0 Message-ID-Hash: CXEAQ6QZZ5AXWF62JV2CZ435ZDRE6LX7 X-Message-ID-Hash: CXEAQ6QZZ5AXWF62JV2CZ435ZDRE6LX7 X-Mailman-Approved-At: Wed, 23 Jul 2025 07:22:29 -0400 CC: ianm@nvidia.com X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: From: Ian May via Devel Reply-To: Ian May X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1753255626106116600 Content-Type: text/plain; charset="utf-8" Add documentation for the ACPI EGM memory device feature: - Describe the purpose and use cases - Document XML configuration options - Provide example configurations - Explain requirements and limitations Signed-off-by: Ian May --- docs/formatdomain.rst | 80 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 54a809eaf9..806af24fc2 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1897,6 +1897,86 @@ For instance, ``target=3D'0' cache=3D'1'`` refers to= the first level cache of NUMA node 0. =20 =20 +ACPI EGM Memory Devices +~~~~~~~~~~~~~~~~~~~~~~~ + +The ACPI EGM (Extended Guest Memory) device enables a guest to access exte= nded memory regions +through ACPI. This is useful for exposing specialized memory regions from = passthrough devices +to the guest OS. + +:: + + + ... + + + ua-hostdev0 + 0 + + ... + + +The ``acpiEgmMemory`` element has the following sub-elements: + +``alias`` + Specifies a unique identifier for the EGM device. + +``pciDev`` + Specifies the ID of the PCI device that provides the extended memory. T= his must + reference a valid PCI device defined in the domain configuration. + +``numaNode`` + Specifies the NUMA node to which the extended memory is assigned. This = must reference + a valid NUMA node defined in the domain configuration. + +To use ACPI EGM, you typically need: + +1. A passthrough PCI device that exposes memory regions +2. A NUMA topology defined in the domain configuration +3. A suitable guest OS that can recognize and utilize the ACPI EGM tables +4. A QEMU version that supports the ACPI EGM feature + +The memory region exposed by the EGM device can be accessed by the guest O= S through the ACPI +tables. This mechanism is often used for specialized workloads that requir= e direct access to +device memory regions. + +Example configuration: + +:: + + + egm-example + 8192 + 4 + + + + + + + + hvm + /usr/share/AAVMF/AAVMF_COD= E.fd + + + + + + +
+ + + + + + + ua-hostdev0 + 0 + + + + + Events configuration -------------------- =20 --=20 2.43.0