[RFC PATCH 7/8] docs: Document ACPI EGM memory device
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 <ianm(a)nvidia.com>
---
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='0' cache='1'`` refers to
the first level cache of NUMA
node 0.
+ACPI EGM Memory Devices
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The ACPI EGM (Extended Guest Memory) device enables a guest to access extended memory
regions
+through ACPI. This is useful for exposing specialized memory regions from passthrough
devices
+to the guest OS.
+
+::
+
+ <devices>
+ ...
+ <acpiEgmMemory>
+ <alias name='egm0'/>
+ <pciDev>ua-hostdev0</pciDev>
+ <numaNode>0</numaNode>
+ </acpiEgmMemory>
+ ...
+ </devices>
+
+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. This 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 OS through the
ACPI
+tables. This mechanism is often used for specialized workloads that require direct access
to
+device memory regions.
+
+Example configuration:
+
+::
+
+ <domain type='kvm'>
+ <name>egm-example</name>
+ <memory unit='MiB'>8192</memory>
+ <vcpu>4</vcpu>
+ <cpu mode='host-passthrough'>
+ <topology sockets='1' cores='4' threads='1'/>
+ <numa>
+ <cell id='0' cpus='0-3' memory='8192'
unit='MiB'/>
+ </numa>
+ </cpu>
+ <os>
+ <type arch='aarch64' machine='virt'>hvm</type>
+ <loader readonly='yes'
type='pflash'>/usr/share/AAVMF/AAVMF_CODE.fd</loader>
+ </os>
+ <devices>
+ <!-- Passthrough PCI device -->
+ <hostdev mode='subsystem' type='pci' managed='yes'>
+ <alias name='ua-hostdev0'/>
+ <source>
+ <address domain='0x0009' bus='0x01' slot='0x00'
function='0x00'/>
+ </source>
+ </hostdev>
+
+ <!-- ACPI EGM device referencing the PCI device -->
+ <acpiEgmMemory>
+ <alias name='egm0'/>
+ <pciDev>ua-hostdev0</pciDev>
+ <numaNode>0</numaNode>
+ </acpiEgmMemory>
+ </devices>
+ </domain>
+
+
Events configuration
--------------------
--
2.43.0