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 <i...@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
