Guest CPU Model configuration in libvirt with qemu/KVM

Because of the management problems in our alization are caused by the annoyingly popular & desirable host Migration Feature! I previusly talked about PCI device addressing problems, but this time the topic to consider is that of CPU models. every hypervisor has its own policies for what a guest will see for its CPUs by default, xen just passes through the host CPU, with qemu/KVM the guest sees a generic model called "qemu32" or "qemu64 ″. VMWare does something more advanced, classifying all physical CPUs into a handful of groups and has one baseline CPU model for each group that's exposed to the guest. VMware's behaviour lets guests safely migrate between hosts provided they all have physical CPUs that classify into the same group. libvirt does not like to enforce policy itself, preferring just to provide the mechanisms on which the higher layers define their own desired policy. CPU models are a complex subject, so it has taken longer than desirable to support their configuration in libvirt. in the 0.7.5 release that will be in fedora 13, there is finally a comprehensive mechanic for controlling guest CPUs. learning about the host CPU Model

If you have been following earlier articles (or otherwise know a bit about libvirt) you'll know that the "virsh capabilities" command displays an XML document describing the capabilities of the hypervisor connection & host. it shoshould thus come as no surprise that this XML schema has been extended to provide information about the host CPU model.

One of the big challenges in describing a CPU models is that every architecture has different approach to exposing their capabilities.

On x86, a modern CPUs 'capabilities are exposed via the cpuid instruction. Essential this comes down to a set of 32-bit integers with each bit given a specific meaning.

Fortunately amd & Intel agree on common semantics for these bits. VMware and xen both expose the notion of cpuid masks directly in their guest configuration format.

Unfortunately (or fortunately depending on your POV) qemu/KVM support far more than just the X86 architecture, so cpuid is clearly not suitable as the canonical configuration format. qemu ended up using a scheme which combines a CPU model name string, with a set of named flags. on x86 the CPU model maps to a baseline cpuid mask, and the flags can be used to then toggle bits in the mask on or off. libvirt decided to follow this lead and use a combination of a model name and flags. without further ado, here is an example of what libvirt reports as the capabilities of my laptop's CPU

# virsh capabilities<capabilities>  
In it not practical to have a database listing all known CPU models, so libvirt has a small list of baseline CPU Model names. it picks the one that shares the greatest number of cpuid bits with the actual host CPU and then lists the remaining bits as named features. notice that libvirt does not tell you what features the baseline CPU contains. this might seem like a flaw at first, but as will be shown next, it is not actually necessary to know this information. determining a compatible CPU model to suit a pool of hosts
Now that it is possible to find out what CPU capabilities a single host has, the next problem is to determine what CPU capabilities are best to expose to the guest.
If it is known that the guest willNeverNeed to be migrated to another host, the host CPU model can be passed straight through unmodified.
Some lucky people might have a receivalized data center where they can guarantee all servers will have 100% identical CPUs. Again the host CPU model can be passed straight through unmodified.
The interesting case though, is where there is variation in CPUs between hosts. in this case the lowest common denominator CPU must be determined. this is not entirely straightforward, so libvirt provides an API for exactly this task. provide libvirt with a list of XML documents, each describing a host's CPU model, and it will internally convert these to cpuid masks, calculate their intersection, finally converting the cpuid mask result back into an xml cpu description.
Taking the CPU description from a random Server
<capabilities>  
As a quick check is it possible to ask libvirt whether this CPU description is compatible with the previous laptop CPU description, using the"virsh cpu-compare"Command
$ ./tools/virsh cpu-compare cpu-server.xmlCPU described in cpu-server.xml is incompatible with host CPU
Libvirt is correctly reporting the CPUs are incompatible, because there are several features in the laptop CPU that are missing in the server CPU.
To be able to migrate between the laptop and the server, it will be necessary to mask out some features, but which ones?
Again libvirt provides an API for this, also exposed via the"virsh cpu-baseline"Command
# virsh cpu-baseline both-cpus.xml<cpu match=‘exact‘>  <model>pentium3</model>  <feature policy=‘require‘ name=‘lahf_lm‘/>  <feature policy=‘require‘ name=‘lm‘/>  <feature policy=‘require‘ name=‘cx16‘/>  <feature policy=‘require‘ name=‘monitor‘/>  <feature policy=‘require‘ name=‘pni‘/>  <feature policy=‘require‘ name=‘ht‘/>  <feature policy=‘require‘ name=‘sse2‘/>  <feature policy=‘require‘ name=‘clflush‘/>  <feature policy=‘require‘ name=‘apic‘/></cpu>
Libvirt has determined that in order to safely migrate a guest between the laptop and the server, It Is neccesary to mask out 11 features from the laptop's XML description. Allocation ing the guest CPU Model
To simplify life, the guest CPU configuration accepts the same basic XML representation as the host capabilities XML exposes.
In other words, the XML from that "CPU-baseline" virsh command, can now be copied directly into the guest XML at the top level under the <domain> element.
The above XML can be added to the domain XML.
As the observant reader will have noticed from that last XML snippet, there are a few extra attributes available when describing a CPU in the guest XML. these can mostly be ignored, but for the curious here's a quick description of what they do.
The top level <CPU> element gets an attribute called "match" with possible values

  

 
   
Match = "minimum"-the host CPU must have at least the CPU features described in the guest XML. if the host has additional features beyond the guest configuration, these will also be exposed to the guest
 
   
Match = "exact"-the host CPU must have at least the CPU features described in the guest XML. if the host has additional features beyond the guest configuration, these will be masked out from the guest
 
   
Match = "strict"-the host CPU must have exactly the same CPU features described in the guest XML. No more, no less.

  
The next enhancement is that the <feature> elements can each have an extra "policy" attribute with possible values

  

 
   
Policy = "force"-expose the feature to the guest even if the host does not have it. This is kind of crazy, cannot be in the case of software emulation.
 
   
Policy = "require"-expose the feature to the guest and fail if the host does not have it. This is the sensible default.
 
   
Policy = "optional"-expose the feature to the guest if it happens to support it.
 
   
Policy = "disable"-if the host has this feature, then hide it from the guest
 
   
Policy = "forbid"-if the host has this feature, then fail and refuse to start the guest

  
The "Forbid" policy is for a niche scenario where a badly behaved application will try to use a feature even if it is not in the cpuid mask, and you wish to prevent accidentally running the guest on a host with that feature. the "optional" policy has special behaviour WRT migration. when the guest is initially started the flag is optional, but when the guest is live migrated, this policy turns into "require", since you can't have features disappearing into SS migration.
All the stuff described in this posting is currently implemented for libvirt's qemu/KVM driver, basic code in the 0.7.5/6 releases, but the final 'cpu-baseline 'stuff is arriving in 0.7.7. needless to say this will all be available in fedora 13 and future RHEL. this obviusly also needs to be ported over to the xen and VMWare ESX drivers in libvirt, which isn't as hard as it sounds, because libvirt Has a very good internal API for processed cpuid masks now. Kudos to jsiri denemark for doing all the really hardwork on this CPU modelling system!