External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-01-19 11:05:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Clarify documentation of host-model CPU mode

Browse Source 
The host-model CPU mode was described as similar to copying the host CPU
definition from capabilities, which has not been the case for ages. The
host-model definition from domain capabilities is used instead.

Only the first sentence changed, but it required reformatting
essentially the whole paragraph so I used this as an opportunity to
reformat it a little bit more and split the long paragraph into several
smaller ones for better readability.

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
Jiri Denemark 2025-01-09 15:06:24 +01:00
parent 4c7bb1cc4a
commit 30b0e553bc
1 changed files with 38 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/formatdomain.rst
View File

@ -1482,38 +1482,46 @@ In case no restrictions need to be put on CPU model and its features, a simpler
presented to the guest. This is the default when no ``mode`` attribute is presented to the guest. This is the default when no ``mode`` attribute is
specified. This mode makes it so that a persistent guest will see the same specified. This mode makes it so that a persistent guest will see the same
hardware no matter what host the guest is booted on. hardware no matter what host the guest is booted on.
``host-model`` ``host-model``
The ``host-model`` mode is essentially a shortcut to copying host CPU The ``host-model`` mode is essentially a shortcut to copying host-model
definition from capabilities XML into domain XML. Since the CPU definition CPU definition from `domain capabilities XML
is copied just before starting a domain, exactly the same XML can be used <formatdomaincaps.html#cpu-configuration>`__ into domain XML. Since the
on different hosts while still providing the best guest CPU each host CPU definition is copied just before starting a domain, exactly the same
supports. The ``match`` attribute can't be used in this mode. Specifying XML can be used on different hosts while still providing the best guest
CPU model is not supported either, but ``model``'s ``fallback`` attribute CPU each host supports. The ``match`` attribute can't be used in this
may still be used. Using the ``feature`` element, specific flags may be mode. Specifying CPU model is not supported either, but ``model``'s
enabled or disabled specifically in addition to the host model. This may ``fallback`` attribute may still be used. Using the ``feature`` element,
be used to fine tune features that can be emulated. :since:`(Since 1.1.1)` specific flags may be enabled or disabled specifically in addition to the
. Libvirt does not model every aspect of each CPU so the guest CPU will host model. This may be used to fine tune features that can be emulated.
not match the host CPU exactly. On the other hand, the ABI provided to the :since:`(Since 1.1.1)`
Libvirt does not model every aspect of each CPU so the guest CPU will not
match the host CPU exactly. On the other hand, the ABI provided to the
guest is reproducible. During migration, complete CPU model definition is guest is reproducible. During migration, complete CPU model definition is
transferred to the destination host so the migrated guest will see exactly transferred to the destination host so the migrated guest will see
the same CPU model for the running instance of the guest, even if the exactly the same CPU model for the running instance of the guest, even if
destination host contains more capable CPUs or newer kernel; but shutting the destination host contains more capable CPUs or newer kernel; but
down and restarting the guest may present different hardware to the guest shutting down and restarting the guest may present different hardware to
according to the capabilities of the new host. Prior to libvirt 3.2.0 and the guest according to the capabilities of the new host.
QEMU 2.9.0 detection of the host CPU model via QEMU is not supported. Thus
the CPU configuration created using ``host-model`` may not work as Prior to libvirt 3.2.0 and QEMU 2.9.0 detection of the host CPU model via
expected. :since:`Since 3.2.0 and QEMU 2.9.0` this mode works the way it QEMU is not supported. Thus the CPU configuration created using
was designed and it is indicated by the ``fallback`` attribute set to ``host-model`` may not work as expected. :since:`Since 3.2.0 and QEMU
``forbid`` in the host-model CPU definition advertised in `domain 2.9.0` this mode works the way it was designed and it is indicated by the
capabilities XML <formatdomaincaps.html#cpu-configuration>`__. When ``fallback`` attribute set to ``forbid`` in the host-model CPU definition
``fallback`` attribute is set to ``allow`` in the domain capabilities advertised in `domain capabilities XML
XML, it is recommended to use ``custom`` mode with just the CPU model <formatdomaincaps.html#cpu-configuration>`__. When ``fallback`` attribute
from the host capabilities XML. :since:`Since 1.2.11` PowerISA allows is set to ``allow`` in the domain capabilities XML, it is recommended to
processors to run VMs in binary compatibility mode supporting an older use ``custom`` mode with just the CPU model from the host capabilities
version of ISA. Libvirt on PowerPC architecture uses the ``host-model`` XML.
to signify a guest mode CPU running in binary compatibility mode.
Example: When a user needs a power7 VM to run in compatibility mode on a :since:`Since 1.2.11` PowerISA allows processors to run VMs in binary
Power8 host, this can be described in XML as follows : compatibility mode supporting an older version of ISA. Libvirt on
PowerPC architecture uses the ``host-model`` to signify a guest mode CPU
running in binary compatibility mode. Example: When a user needs a power7
VM to run in compatibility mode on a Power8 host, this can be described
in XML as follows:
:: ::