1@c man begin SYNOPSIS 2QEMU / KVM CPU model configuration 3@c man end 4 5@c man begin DESCRIPTION 6 7@menu 8* recommendations_cpu_models_x86:: Recommendations for KVM CPU model configuration on x86 hosts 9* recommendations_cpu_models_MIPS:: Supported CPU model configurations on MIPS hosts 10* cpu_model_syntax_apps:: Syntax for configuring CPU models 11@end menu 12 13QEMU / KVM virtualization supports two ways to configure CPU models 14 15@table @option 16 17@item Host passthrough 18 19This passes the host CPU model features, model, stepping, exactly to the 20guest. Note that KVM may filter out some host CPU model features if they 21cannot be supported with virtualization. Live migration is unsafe when 22this mode is used as libvirt / QEMU cannot guarantee a stable CPU is 23exposed to the guest across hosts. This is the recommended CPU to use, 24provided live migration is not required. 25 26@item Named model 27 28QEMU comes with a number of predefined named CPU models, that typically 29refer to specific generations of hardware released by Intel and AMD. 30These allow the guest VMs to have a degree of isolation from the host CPU, 31allowing greater flexibility in live migrating between hosts with differing 32hardware. 33@end table 34 35In both cases, it is possible to optionally add or remove individual CPU 36features, to alter what is presented to the guest by default. 37 38Libvirt supports a third way to configure CPU models known as "Host model". 39This uses the QEMU "Named model" feature, automatically picking a CPU model 40that is similar the host CPU, and then adding extra features to approximate 41the host model as closely as possible. This does not guarantee the CPU family, 42stepping, etc will precisely match the host CPU, as they would with "Host 43passthrough", but gives much of the benefit of passthrough, while making 44live migration safe. 45 46@node recommendations_cpu_models_x86 47@subsection Recommendations for KVM CPU model configuration on x86 hosts 48 49The information that follows provides recommendations for configuring 50CPU models on x86 hosts. The goals are to maximise performance, while 51protecting guest OS against various CPU hardware flaws, and optionally 52enabling live migration between hosts with heterogeneous CPU models. 53 54@menu 55* preferred_cpu_models_intel_x86:: Preferred CPU models for Intel x86 hosts 56* important_cpu_features_intel_x86:: Important CPU features for Intel x86 hosts 57* preferred_cpu_models_amd_x86:: Preferred CPU models for AMD x86 hosts 58* important_cpu_features_amd_x86:: Important CPU features for AMD x86 hosts 59* default_cpu_models_x86:: Default x86 CPU models 60* other_non_recommended_cpu_models_x86:: Other non-recommended x86 CPUs 61@end menu 62 63@node preferred_cpu_models_intel_x86 64@subsubsection Preferred CPU models for Intel x86 hosts 65 66The following CPU models are preferred for use on Intel hosts. Administrators / 67applications are recommended to use the CPU model that matches the generation 68of the host CPUs in use. In a deployment with a mixture of host CPU models 69between machines, if live migration compatibility is required, use the newest 70CPU model that is compatible across all desired hosts. 71 72@table @option 73@item @code{Skylake-Server} 74@item @code{Skylake-Server-IBRS} 75 76Intel Xeon Processor (Skylake, 2016) 77 78 79@item @code{Skylake-Client} 80@item @code{Skylake-Client-IBRS} 81 82Intel Core Processor (Skylake, 2015) 83 84 85@item @code{Broadwell} 86@item @code{Broadwell-IBRS} 87@item @code{Broadwell-noTSX} 88@item @code{Broadwell-noTSX-IBRS} 89 90Intel Core Processor (Broadwell, 2014) 91 92 93@item @code{Haswell} 94@item @code{Haswell-IBRS} 95@item @code{Haswell-noTSX} 96@item @code{Haswell-noTSX-IBRS} 97 98Intel Core Processor (Haswell, 2013) 99 100 101@item @code{IvyBridge} 102@item @code{IvyBridge-IBRS} 103 104Intel Xeon E3-12xx v2 (Ivy Bridge, 2012) 105 106 107@item @code{SandyBridge} 108@item @code{SandyBridge-IBRS} 109 110Intel Xeon E312xx (Sandy Bridge, 2011) 111 112 113@item @code{Westmere} 114@item @code{Westmere-IBRS} 115 116Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010) 117 118 119@item @code{Nehalem} 120@item @code{Nehalem-IBRS} 121 122Intel Core i7 9xx (Nehalem Class Core i7, 2008) 123 124 125@item @code{Penryn} 126 127Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007) 128 129 130@item @code{Conroe} 131 132Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006) 133 134@end table 135 136@node important_cpu_features_intel_x86 137@subsubsection Important CPU features for Intel x86 hosts 138 139The following are important CPU features that should be used on Intel x86 140hosts, when available in the host CPU. Some of them require explicit 141configuration to enable, as they are not included by default in some, or all, 142of the named CPU models listed above. In general all of these features are 143included if using "Host passthrough" or "Host model". 144 145 146@table @option 147 148@item @code{pcid} 149 150Recommended to mitigate the cost of the Meltdown (CVE-2017-5754) fix 151 152Included by default in Haswell, Broadwell & Skylake Intel CPU models. 153 154Should be explicitly turned on for Westmere, SandyBridge, and IvyBridge 155Intel CPU models. Note that some desktop/mobile Westmere CPUs cannot 156support this feature. 157 158 159@item @code{spec-ctrl} 160 161Required to enable the Spectre v2 (CVE-2017-5715) fix. 162 163Included by default in Intel CPU models with -IBRS suffix. 164 165Must be explicitly turned on for Intel CPU models without -IBRS suffix. 166 167Requires the host CPU microcode to support this feature before it 168can be used for guest CPUs. 169 170 171@item @code{stibp} 172 173Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some 174operating systems. 175 176Must be explicitly turned on for all Intel CPU models. 177 178Requires the host CPU microcode to support this feature before it 179can be used for guest CPUs. 180 181 182@item @code{ssbd} 183 184Required to enable the CVE-2018-3639 fix 185 186Not included by default in any Intel CPU model. 187 188Must be explicitly turned on for all Intel CPU models. 189 190Requires the host CPU microcode to support this feature before it 191can be used for guest CPUs. 192 193 194@item @code{pdpe1gb} 195 196Recommended to allow guest OS to use 1GB size pages 197 198Not included by default in any Intel CPU model. 199 200Should be explicitly turned on for all Intel CPU models. 201 202Note that not all CPU hardware will support this feature. 203 204@item @code{md-clear} 205 206Required to confirm the MDS (CVE-2018-12126, CVE-2018-12127, CVE-2018-12130, 207CVE-2019-11091) fixes. 208 209Not included by default in any Intel CPU model. 210 211Must be explicitly turned on for all Intel CPU models. 212 213Requires the host CPU microcode to support this feature before it 214can be used for guest CPUs. 215@end table 216 217 218@node preferred_cpu_models_amd_x86 219@subsubsection Preferred CPU models for AMD x86 hosts 220 221The following CPU models are preferred for use on Intel hosts. Administrators / 222applications are recommended to use the CPU model that matches the generation 223of the host CPUs in use. In a deployment with a mixture of host CPU models 224between machines, if live migration compatibility is required, use the newest 225CPU model that is compatible across all desired hosts. 226 227@table @option 228 229@item @code{EPYC} 230@item @code{EPYC-IBPB} 231 232AMD EPYC Processor (2017) 233 234 235@item @code{Opteron_G5} 236 237AMD Opteron 63xx class CPU (2012) 238 239 240@item @code{Opteron_G4} 241 242AMD Opteron 62xx class CPU (2011) 243 244 245@item @code{Opteron_G3} 246 247AMD Opteron 23xx (Gen 3 Class Opteron, 2009) 248 249 250@item @code{Opteron_G2} 251 252AMD Opteron 22xx (Gen 2 Class Opteron, 2006) 253 254 255@item @code{Opteron_G1} 256 257AMD Opteron 240 (Gen 1 Class Opteron, 2004) 258@end table 259 260@node important_cpu_features_amd_x86 261@subsubsection Important CPU features for AMD x86 hosts 262 263The following are important CPU features that should be used on AMD x86 264hosts, when available in the host CPU. Some of them require explicit 265configuration to enable, as they are not included by default in some, or all, 266of the named CPU models listed above. In general all of these features are 267included if using "Host passthrough" or "Host model". 268 269 270@table @option 271 272@item @code{ibpb} 273 274Required to enable the Spectre v2 (CVE-2017-5715) fix. 275 276Included by default in AMD CPU models with -IBPB suffix. 277 278Must be explicitly turned on for AMD CPU models without -IBPB suffix. 279 280Requires the host CPU microcode to support this feature before it 281can be used for guest CPUs. 282 283 284@item @code{stibp} 285 286Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some 287operating systems. 288 289Must be explicitly turned on for all AMD CPU models. 290 291Requires the host CPU microcode to support this feature before it 292can be used for guest CPUs. 293 294 295@item @code{virt-ssbd} 296 297Required to enable the CVE-2018-3639 fix 298 299Not included by default in any AMD CPU model. 300 301Must be explicitly turned on for all AMD CPU models. 302 303This should be provided to guests, even if amd-ssbd is also 304provided, for maximum guest compatibility. 305 306Note for some QEMU / libvirt versions, this must be force enabled 307when when using "Host model", because this is a virtual feature 308that doesn't exist in the physical host CPUs. 309 310 311@item @code{amd-ssbd} 312 313Required to enable the CVE-2018-3639 fix 314 315Not included by default in any AMD CPU model. 316 317Must be explicitly turned on for all AMD CPU models. 318 319This provides higher performance than virt-ssbd so should be 320exposed to guests whenever available in the host. virt-ssbd 321should none the less also be exposed for maximum guest 322compatibility as some kernels only know about virt-ssbd. 323 324 325@item @code{amd-no-ssb} 326 327Recommended to indicate the host is not vulnerable CVE-2018-3639 328 329Not included by default in any AMD CPU model. 330 331Future hardware generations of CPU will not be vulnerable to 332CVE-2018-3639, and thus the guest should be told not to enable 333its mitigations, by exposing amd-no-ssb. This is mutually 334exclusive with virt-ssbd and amd-ssbd. 335 336 337@item @code{pdpe1gb} 338 339Recommended to allow guest OS to use 1GB size pages 340 341Not included by default in any AMD CPU model. 342 343Should be explicitly turned on for all AMD CPU models. 344 345Note that not all CPU hardware will support this feature. 346@end table 347 348 349@node default_cpu_models_x86 350@subsubsection Default x86 CPU models 351 352The default QEMU CPU models are designed such that they can run on all hosts. 353If an application does not wish to do perform any host compatibility checks 354before launching guests, the default is guaranteed to work. 355 356The default CPU models will, however, leave the guest OS vulnerable to various 357CPU hardware flaws, so their use is strongly discouraged. Applications should 358follow the earlier guidance to setup a better CPU configuration, with host 359passthrough recommended if live migration is not needed. 360 361@table @option 362@item @code{qemu32} 363@item @code{qemu64} 364 365QEMU Virtual CPU version 2.5+ (32 & 64 bit variants) 366 367qemu64 is used for x86_64 guests and qemu32 is used for i686 guests, when no 368-cpu argument is given to QEMU, or no <cpu> is provided in libvirt XML. 369@end table 370 371 372@node other_non_recommended_cpu_models_x86 373@subsubsection Other non-recommended x86 CPUs 374 375The following CPUs models are compatible with most AMD and Intel x86 hosts, but 376their usage is discouraged, as they expose a very limited featureset, which 377prevents guests having optimal performance. 378 379@table @option 380 381@item @code{kvm32} 382@item @code{kvm64} 383 384Common KVM processor (32 & 64 bit variants) 385 386Legacy models just for historical compatibility with ancient QEMU versions. 387 388 389@item @code{486} 390@item @code{athlon} 391@item @code{phenom} 392@item @code{coreduo} 393@item @code{core2duo} 394@item @code{n270} 395@item @code{pentium} 396@item @code{pentium2} 397@item @code{pentium3} 398 399Various very old x86 CPU models, mostly predating the introduction of 400hardware assisted virtualization, that should thus not be required for 401running virtual machines. 402@end table 403 404@node recommendations_cpu_models_MIPS 405@subsection Supported CPU model configurations on MIPS hosts 406 407QEMU supports variety of MIPS CPU models: 408 409@menu 410* cpu_models_MIPS32:: Supported CPU models for MIPS32 hosts 411* cpu_models_MIPS64:: Supported CPU models for MIPS64 hosts 412* cpu_models_nanoMIPS:: Supported CPU models for nanoMIPS hosts 413* preferred_cpu_models_MIPS:: Preferred CPU models for MIPS hosts 414@end menu 415 416@node cpu_models_MIPS32 417@subsubsection Supported CPU models for MIPS32 hosts 418 419The following CPU models are supported for use on MIPS32 hosts. Administrators / 420applications are recommended to use the CPU model that matches the generation 421of the host CPUs in use. In a deployment with a mixture of host CPU models 422between machines, if live migration compatibility is required, use the newest 423CPU model that is compatible across all desired hosts. 424 425@table @option 426@item @code{mips32r6-generic} 427 428MIPS32 Processor (Release 6, 2015) 429 430 431@item @code{P5600} 432 433MIPS32 Processor (P5600, 2014) 434 435 436@item @code{M14K} 437@item @code{M14Kc} 438 439MIPS32 Processor (M14K, 2009) 440 441 442@item @code{74Kf} 443 444MIPS32 Processor (74K, 2007) 445 446 447@item @code{34Kf} 448 449MIPS32 Processor (34K, 2006) 450 451 452@item @code{24Kc} 453@item @code{24KEc} 454@item @code{24Kf} 455 456MIPS32 Processor (24K, 2003) 457 458 459@item @code{4Kc} 460@item @code{4Km} 461@item @code{4KEcR1} 462@item @code{4KEmR1} 463@item @code{4KEc} 464@item @code{4KEm} 465 466MIPS32 Processor (4K, 1999) 467@end table 468 469@node cpu_models_MIPS64 470@subsubsection Supported CPU models for MIPS64 hosts 471 472The following CPU models are supported for use on MIPS64 hosts. Administrators / 473applications are recommended to use the CPU model that matches the generation 474of the host CPUs in use. In a deployment with a mixture of host CPU models 475between machines, if live migration compatibility is required, use the newest 476CPU model that is compatible across all desired hosts. 477 478@table @option 479@item @code{I6400} 480 481MIPS64 Processor (Release 6, 2014) 482 483 484@item @code{Loongson-2F} 485 486MIPS64 Processor (Loongson 2, 2008) 487 488 489@item @code{Loongson-2E} 490 491MIPS64 Processor (Loongson 2, 2006) 492 493 494@item @code{mips64dspr2} 495 496MIPS64 Processor (Release 2, 2006) 497 498 499@item @code{MIPS64R2-generic} 500@item @code{5KEc} 501@item @code{5KEf} 502 503MIPS64 Processor (Release 2, 2002) 504 505 506@item @code{20Kc} 507 508MIPS64 Processor (20K, 2000) 509 510 511@item @code{5Kc} 512@item @code{5Kf} 513 514MIPS64 Processor (5K, 1999) 515 516 517@item @code{VR5432} 518 519MIPS64 Processor (VR, 1998) 520 521 522@item @code{R4000} 523 524MIPS64 Processor (MIPS III, 1991) 525@end table 526 527@node cpu_models_nanoMIPS 528@subsubsection Supported CPU models for nanoMIPS hosts 529 530The following CPU models are supported for use on nanoMIPS hosts. Administrators / 531applications are recommended to use the CPU model that matches the generation 532of the host CPUs in use. In a deployment with a mixture of host CPU models 533between machines, if live migration compatibility is required, use the newest 534CPU model that is compatible across all desired hosts. 535 536@table @option 537@item @code{I7200} 538 539MIPS I7200 (nanoMIPS, 2018) 540 541@end table 542 543@node preferred_cpu_models_MIPS 544@subsubsection Preferred CPU models for MIPS hosts 545 546The following CPU models are preferred for use on different MIPS hosts: 547 548@table @option 549@item @code{MIPS III} 550R4000 551 552@item @code{MIPS32R2} 55334Kf 554 555@item @code{MIPS64R6} 556I6400 557 558@item @code{nanoMIPS} 559I7200 560@end table 561 562@node cpu_model_syntax_apps 563@subsection Syntax for configuring CPU models 564 565The example below illustrate the approach to configuring the various 566CPU models / features in QEMU and libvirt 567 568@menu 569* cpu_model_syntax_qemu:: QEMU command line 570* cpu_model_syntax_libvirt:: Libvirt guest XML 571@end menu 572 573@node cpu_model_syntax_qemu 574@subsubsection QEMU command line 575 576@table @option 577 578@item Host passthrough 579 580@example 581 $ qemu-system-x86_64 -cpu host 582@end example 583 584With feature customization: 585 586@example 587 $ qemu-system-x86_64 -cpu host,-vmx,... 588@end example 589 590@item Named CPU models 591 592@example 593 $ qemu-system-x86_64 -cpu Westmere 594@end example 595 596With feature customization: 597 598@example 599 $ qemu-system-x86_64 -cpu Westmere,+pcid,... 600@end example 601 602@end table 603 604@node cpu_model_syntax_libvirt 605@subsubsection Libvirt guest XML 606 607@table @option 608 609@item Host passthrough 610 611@example 612 <cpu mode='host-passthrough'/> 613@end example 614 615With feature customization: 616 617@example 618 <cpu mode='host-passthrough'> 619 <feature name="vmx" policy="disable"/> 620 ... 621 </cpu> 622@end example 623 624@item Host model 625 626@example 627 <cpu mode='host-model'/> 628@end example 629 630With feature customization: 631 632@example 633 <cpu mode='host-model'> 634 <feature name="vmx" policy="disable"/> 635 ... 636 </cpu> 637@end example 638 639@item Named model 640 641@example 642 <cpu mode='custom'> 643 <model name="Westmere"/> 644 </cpu> 645@end example 646 647With feature customization: 648 649@example 650 <cpu mode='custom'> 651 <model name="Westmere"/> 652 <feature name="pcid" policy="require"/> 653 ... 654 </cpu> 655@end example 656 657@end table 658 659@c man end 660 661@ignore 662 663@setfilename qemu-cpu-models 664@settitle QEMU / KVM CPU model configuration 665 666@c man begin SEEALSO 667The HTML documentation of QEMU for more precise information and Linux 668user mode emulator invocation. 669@c man end 670 671@c man begin AUTHOR 672Daniel P. Berrange 673@c man end 674 675@end ignore 676