Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

20.11. CPU Model and Topology

This section covers the requirements for CPU model. Note that every hypervisor has its own policy for which CPU features guest will see by default. The set of CPU features presented to the guest by QEMU/KVM depends on the CPU model chosen in the guest virtual machine configuration. qemu32 and qemu64 are basic CPU models but there are other models (with additional features) available. Each model and its topology is specified using the following elements from the domain XML: 
<cpu match='exact'>
    <model fallback='allow'>core2duo</model>
    <vendor>Intel</vendor>
    <topology sockets='1' cores='2' threads='1'/>
    <feature policy='disable' name='lahf_lm'/>
  </cpu>

Figure 20.13. CPU model and topology example 1

<cpu mode='host-model'>
   <model fallback='forbid'/>
   <topology sockets='1' cores='2' threads='1'/>
</cpu>

Figure 20.14. CPU model and topology example 2

<cpu mode='host-passthrough'/>

Figure 20.15. CPU model and topology example 3

In cases where no restrictions are to be put on either the CPU model nor its features, a simpler cpu element such as the following may be used. 
<cpu>
   <topology sockets='1' cores='2' threads='1'/>
</cpu>

Figure 20.16. CPU model and topology example 4

The components of this section of the domain XML are as follows:

Table 20.9. CPU model and topology elements

ElementDescription
<cpu>This element contains all parameters for the vCPU feature set.
<match>Specifies how closely the features indicated in the <cpu> element must match the vCPUs that are available. The match attribute can be omitted if <topology> is the only element nested in the <cpu> element. Possible values for the match attribute are:
  • minimum - The features listed are the minimum requirement. There may be more features available in the vCPU then are indicated, but this is the minimum that will be accepted. This value will fail if the minimum requirements are not met.
  • exact - the virtual CPU provided to the guest virtual machine must exactly match the features specified. If no match is found, an error will result.
  • strict - the guest virtual machine will not be created unless the host physical machine CPU exactly matches the specification.
If the match attribute is omitted from the <cpu> element, the default setting match='exact' is used.
<mode>This optional attribute may be used to make it easier to configure a guest virtual machine CPU to be as close to the host physical machine CPU as possible. Possible values for the mode attribute are:
  • custom - describes how the CPU is presented to the guest virtual machine. This is the default setting when the mode attribute is not specified. This mode makes it so that a persistent guest virtual machine will see the same hardware no matter what host physical machine the guest virtual machine is booted on.
  • host-model - this is essentially a shortcut to copying host physical machine CPU definition from the capabilities XML into the domain XML. As the CPU definition is copied just before starting a domain, the same XML can be used on different host physical machines while still providing the best guest virtual machine CPU each host physical machine supports. Neither the match attribute nor any feature elements can be used in this mode. For more information see libvirt domain XML CPU models
  • host-passthrough With this mode, the CPU visible to the guest virtual machine is exactly the same as the host physical machine CPU including elements that cause errors within libvirt. The obvious the downside of this mode is that the guest virtual machine environment cannot be reproduced on different hardware and therefore this mode is recommended with great caution. Neither model nor feature elements are allowed in this mode.
  • Note that in both host-model and host-passthrough mode, the real (approximate in host-passthrough mode) CPU definition which would be used on current host physical machine can be determined by specifying VIR_DOMAIN_XML_UPDATE_CPU flag when calling virDomainGetXMLDesc API. When running a guest virtual machine that might be prone to operating system reactivation when presented with different hardware, and which will be migrated between host physical machines with different capabilities, you can use this output to rewrite XML to the custom mode for more robust migration.
<model>Specifies CPU model requested by the guest virtual machine. The list of available CPU models and their definition can be found in cpu_map.xml file installed in libvirt's data directory. If a hypervisor is not able to use the exact CPU model, libvirt automatically falls back to a closest model supported by the hypervisor while maintaining the list of CPU features. An optional fallback attribute can be used to forbid this behavior, in which case an attempt to start a domain requesting an unsupported CPU model will fail. Supported values for fallback attribute are: allow (this is the default), and forbid. The optional vendor_id attribute can be used to set the vendor id seen by the guest virtual machine. It must be exactly 12 characters long. If not set, the vendor id of the host physical machine is used. Typical possible values are AuthenticAMD and GenuineIntel.
<vendor>Specifies CPU vendor requested by the guest virtual machine. If this element is missing, the guest virtual machine runs on a CPU matching given features regardless of its vendor. The list of supported vendors can be found in cpu_map.xml.
<topology>Specifies requested topology of virtual CPU provided to the guest virtual machine. Three non-zero values have to be given for sockets, cores, and threads: total number of CPU sockets, number of cores per socket, and number of threads per core, respectively.
<feature>Can contain zero or more elements used to fine-tune features provided by the selected CPU model. The list of known feature names can be found in the same file as CPU models. The meaning of each feature element depends on its policy attribute, which has to be set to one of the following values:
  • force - forces the virtual to be supported regardless of whether it is actually supported by host physical machine CPU.
  • require - dictates that guest virtual machine creation will fail unless the feature is supported by host physical machine CPU. This is the default setting
  • optional - this feature is supported by virtual CPU but and only if it is supported by host physical machine CPU.
  • disable - this is not supported by virtual CPU.
  • forbid - guest virtual machine creation will fail if the feature is supported by host physical machine CPU.

20.11.1. Guest virtual machine NUMA topology

Guest virtual machine NUMA topology can be specified using the <numa> element and the following from the domain XML: 

  <cpu>
    <numa>
      <cell cpus='0-3' memory='512000'/>
      <cell cpus='4-7' memory='512000'/>
    </numa>
  </cpu>
  ...

Figure 20.17. Guest Virtual Machine NUMA Topology

Each cell element specifies a NUMA cell or a NUMA node. cpus specifies the CPU or range of CPUs that are part of the node. memory specifies the node memory in kibibytes (blocks of 1024 bytes). Each cell or node is assigned cellid or nodeid in increasing order starting from 0.