Add documentation for the new <acpi nodeset="..."> element in hostdev,
which allows associating devices with ACPI Generic Initiator objects in
QEMU.
A typical use case is NVIDIA Multi-Instance GPU (MIG), where a physical
GPU is partitioned into multiple isolated instances, each tied to one or
more virtual NUMA nodes. The documentation includes an example showing
how to configure <numa> cells together with a MIG device.
Signed-off-by: Andrea Righi <arighi@nvidia.com>
---
docs/formatdomain.rst | 49 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 49 insertions(+)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 9f7311b6d5..24f7cdd018 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -4894,6 +4894,55 @@ or:
host device. :since:`Since 1.0.6`, but only works as expected
:since:`since 1.2.2`.
+ACPI Generic Initiators
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A host device may include an ``<acpi>`` element to create ACPI Generic
+Initiator objects for the device in QEMU.
+
+This can be used for **NVIDIA Multi-Instance GPU (MIG)** configurations,
+where a physical GPU is partitioned into multiple isolated instances, each
+associated with one or more virtual NUMA nodes.
+
+By attaching an ``<acpi nodeset=.../>`` element to the MIG device in the
+domain XML, the guest will configure the correct partitioning for that
+instance.
+
+.. code-block:: xml
+
+ <numa>
+ <cell id='0' cpus='0-15' memory='8388608' unit='KiB'/>
+ <cell id='1' memory='0' unit='KiB'/>
+ <cell id='2' memory='0' unit='KiB'/>
+ <cell id='3' memory='0' unit='KiB'/>
+ <cell id='4' memory='0' unit='KiB'/>
+ <cell id='5' memory='0' unit='KiB'/>
+ <cell id='6' memory='0' unit='KiB'/>
+ <cell id='7' memory='0' unit='KiB'/>
+ <cell id='8' memory='0' unit='KiB'/>
+ </numa>
+ ...
+ <hostdev mode='subsystem' type='pci' managed='yes'>
+ <source>
+ <address domain='0x0000' bus='0x06' slot='0x12' function='0x1'/>
+ </source>
+ <acpi nodeset='1-8'/>
+ <address type='pci' domain='0x0000' bus='0x00'
+ slot='0x02' function='0x0'/>
+ </hostdev>
+
+Attributes of ``<acpi>``:
+
+``nodeset``
+ A list of NUMA node IDs that will be associated with the device.
+ Each node in the set causes libvirt to create an
+ ``acpi-generic-initiator`` object in QEMU, tied to this device.
+
+ The value uses the standard libvirt *nodeset* syntax (e.g. ``0-3,5``).
+
+If the ``<acpi>`` element is omitted, no acpi-generic-initiator objects are
+created for the device.
+
Block / character devices
^^^^^^^^^^^^^^^^^^^^^^^^^
--
2.51.0On Sat, Sep 06, 2025 at 03:09:02PM +0200, Andrea Righi wrote: > Add documentation for the new <acpi nodeset="..."> element in hostdev, > which allows associating devices with ACPI Generic Initiator objects in > QEMU. > > A typical use case is NVIDIA Multi-Instance GPU (MIG), where a physical > GPU is partitioned into multiple isolated instances, each tied to one or > more virtual NUMA nodes. The documentation includes an example showing > how to configure <numa> cells together with a MIG device. > > Signed-off-by: Andrea Righi <arighi@nvidia.com> > --- > docs/formatdomain.rst | 49 +++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 49 insertions(+) > > diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst > index 9f7311b6d5..24f7cdd018 100644 > --- a/docs/formatdomain.rst > +++ b/docs/formatdomain.rst > @@ -4894,6 +4894,55 @@ or: > host device. :since:`Since 1.0.6`, but only works as expected > :since:`since 1.2.2`. > > +ACPI Generic Initiators > +^^^^^^^^^^^^^^^^^^^^^^^^ > + > +A host device may include an ``<acpi>`` element to create ACPI Generic > +Initiator objects for the device in QEMU. > + > +This can be used for **NVIDIA Multi-Instance GPU (MIG)** configurations, > +where a physical GPU is partitioned into multiple isolated instances, each > +associated with one or more virtual NUMA nodes. > + > +By attaching an ``<acpi nodeset=.../>`` element to the MIG device in the > +domain XML, the guest will configure the correct partitioning for that > +instance. > + > +.. code-block:: xml We can't use code formatting in CI, so I've changed this to a plain pre-formatted text block like the rest of the doc > + > + <numa> > + <cell id='0' cpus='0-15' memory='8388608' unit='KiB'/> > + <cell id='1' memory='0' unit='KiB'/> > + <cell id='2' memory='0' unit='KiB'/> > + <cell id='3' memory='0' unit='KiB'/> > + <cell id='4' memory='0' unit='KiB'/> > + <cell id='5' memory='0' unit='KiB'/> > + <cell id='6' memory='0' unit='KiB'/> > + <cell id='7' memory='0' unit='KiB'/> > + <cell id='8' memory='0' unit='KiB'/> > + </numa> > + ... > + <hostdev mode='subsystem' type='pci' managed='yes'> > + <source> > + <address domain='0x0000' bus='0x06' slot='0x12' function='0x1'/> > + </source> > + <acpi nodeset='1-8'/> > + <address type='pci' domain='0x0000' bus='0x00' > + slot='0x02' function='0x0'/> > + </hostdev> > + > +Attributes of ``<acpi>``: > + > +``nodeset`` > + A list of NUMA node IDs that will be associated with the device. > + Each node in the set causes libvirt to create an > + ``acpi-generic-initiator`` object in QEMU, tied to this device. > + > + The value uses the standard libvirt *nodeset* syntax (e.g. ``0-3,5``). > + > +If the ``<acpi>`` element is omitted, no acpi-generic-initiator objects are > +created for the device. > + > Block / character devices > ^^^^^^^^^^^^^^^^^^^^^^^^^ > > -- > 2.51.0 > With regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Sat, Sep 06, 2025 at 03:09:02PM +0200, Andrea Righi wrote: > Add documentation for the new <acpi nodeset="..."> element in hostdev, > which allows associating devices with ACPI Generic Initiator objects in > QEMU. > > A typical use case is NVIDIA Multi-Instance GPU (MIG), where a physical > GPU is partitioned into multiple isolated instances, each tied to one or > more virtual NUMA nodes. The documentation includes an example showing > how to configure <numa> cells together with a MIG device. > > Signed-off-by: Andrea Righi <arighi@nvidia.com> > --- > docs/formatdomain.rst | 49 +++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 49 insertions(+) Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> With regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
© 2016 - 2026 Red Hat, Inc.