1The Definitive KVM (Kernel-based Virtual Machine) API Documentation 2=================================================================== 3 41. General description 5---------------------- 6 7The kvm API is a set of ioctls that are issued to control various aspects 8of a virtual machine. The ioctls belong to three classes 9 10 - System ioctls: These query and set global attributes which affect the 11 whole kvm subsystem. In addition a system ioctl is used to create 12 virtual machines 13 14 - VM ioctls: These query and set attributes that affect an entire virtual 15 machine, for example memory layout. In addition a VM ioctl is used to 16 create virtual cpus (vcpus) and devices. 17 18 Only run VM ioctls from the same process (address space) that was used 19 to create the VM. 20 21 - vcpu ioctls: These query and set attributes that control the operation 22 of a single virtual cpu. 23 24 Only run vcpu ioctls from the same thread that was used to create the 25 vcpu. 26 27 - device ioctls: These query and set attributes that control the operation 28 of a single device. 29 30 device ioctls must be issued from the same process (address space) that 31 was used to create the VM. 32 332. File descriptors 34------------------- 35 36The kvm API is centered around file descriptors. An initial 37open("/dev/kvm") obtains a handle to the kvm subsystem; this handle 38can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this 39handle will create a VM file descriptor which can be used to issue VM 40ioctls. A KVM_CREATE_VCPU or KVM_CREATE_DEVICE ioctl on a VM fd will 41create a virtual cpu or device and return a file descriptor pointing to 42the new resource. Finally, ioctls on a vcpu or device fd can be used 43to control the vcpu or device. For vcpus, this includes the important 44task of actually running guest code. 45 46In general file descriptors can be migrated among processes by means 47of fork() and the SCM_RIGHTS facility of unix domain socket. These 48kinds of tricks are explicitly not supported by kvm. While they will 49not cause harm to the host, their actual behavior is not guaranteed by 50the API. The only supported use is one virtual machine per process, 51and one vcpu per thread. 52 53 543. Extensions 55------------- 56 57As of Linux 2.6.22, the KVM ABI has been stabilized: no backward 58incompatible change are allowed. However, there is an extension 59facility that allows backward-compatible extensions to the API to be 60queried and used. 61 62The extension mechanism is not based on the Linux version number. 63Instead, kvm defines extension identifiers and a facility to query 64whether a particular extension identifier is available. If it is, a 65set of ioctls is available for application use. 66 67 684. API description 69------------------ 70 71This section describes ioctls that can be used to control kvm guests. 72For each ioctl, the following information is provided along with a 73description: 74 75 Capability: which KVM extension provides this ioctl. Can be 'basic', 76 which means that is will be provided by any kernel that supports 77 API version 12 (see section 4.1), a KVM_CAP_xyz constant, which 78 means availability needs to be checked with KVM_CHECK_EXTENSION 79 (see section 4.4), or 'none' which means that while not all kernels 80 support this ioctl, there's no capability bit to check its 81 availability: for kernels that don't support the ioctl, 82 the ioctl returns -ENOTTY. 83 84 Architectures: which instruction set architectures provide this ioctl. 85 x86 includes both i386 and x86_64. 86 87 Type: system, vm, or vcpu. 88 89 Parameters: what parameters are accepted by the ioctl. 90 91 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) 92 are not detailed, but errors with specific meanings are. 93 94 954.1 KVM_GET_API_VERSION 96 97Capability: basic 98Architectures: all 99Type: system ioctl 100Parameters: none 101Returns: the constant KVM_API_VERSION (=12) 102 103This identifies the API version as the stable kvm API. It is not 104expected that this number will change. However, Linux 2.6.20 and 1052.6.21 report earlier versions; these are not documented and not 106supported. Applications should refuse to run if KVM_GET_API_VERSION 107returns a value other than 12. If this check passes, all ioctls 108described as 'basic' will be available. 109 110 1114.2 KVM_CREATE_VM 112 113Capability: basic 114Architectures: all 115Type: system ioctl 116Parameters: machine type identifier (KVM_VM_*) 117Returns: a VM fd that can be used to control the new virtual machine. 118 119The new VM has no virtual cpus and no memory. 120You probably want to use 0 as machine type. 121 122In order to create user controlled virtual machines on S390, check 123KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as 124privileged user (CAP_SYS_ADMIN). 125 126To use hardware assisted virtualization on MIPS (VZ ASE) rather than 127the default trap & emulate implementation (which changes the virtual 128memory layout to fit in user mode), check KVM_CAP_MIPS_VZ and use the 129flag KVM_VM_MIPS_VZ. 130 131 1324.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST 133 134Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST 135Architectures: x86 136Type: system ioctl 137Parameters: struct kvm_msr_list (in/out) 138Returns: 0 on success; -1 on error 139Errors: 140 EFAULT: the msr index list cannot be read from or written to 141 E2BIG: the msr index list is to be to fit in the array specified by 142 the user. 143 144struct kvm_msr_list { 145 __u32 nmsrs; /* number of msrs in entries */ 146 __u32 indices[0]; 147}; 148 149The user fills in the size of the indices array in nmsrs, and in return 150kvm adjusts nmsrs to reflect the actual number of msrs and fills in the 151indices array with their numbers. 152 153KVM_GET_MSR_INDEX_LIST returns the guest msrs that are supported. The list 154varies by kvm version and host processor, but does not change otherwise. 155 156Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are 157not returned in the MSR list, as different vcpus can have a different number 158of banks, as set via the KVM_X86_SETUP_MCE ioctl. 159 160KVM_GET_MSR_FEATURE_INDEX_LIST returns the list of MSRs that can be passed 161to the KVM_GET_MSRS system ioctl. This lets userspace probe host capabilities 162and processor features that are exposed via MSRs (e.g., VMX capabilities). 163This list also varies by kvm version and host processor, but does not change 164otherwise. 165 166 1674.4 KVM_CHECK_EXTENSION 168 169Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl 170Architectures: all 171Type: system ioctl, vm ioctl 172Parameters: extension identifier (KVM_CAP_*) 173Returns: 0 if unsupported; 1 (or some other positive integer) if supported 174 175The API allows the application to query about extensions to the core 176kvm API. Userspace passes an extension identifier (an integer) and 177receives an integer that describes the extension availability. 178Generally 0 means no and 1 means yes, but some extensions may report 179additional information in the integer return value. 180 181Based on their initialization different VMs may have different capabilities. 182It is thus encouraged to use the vm ioctl to query for capabilities (available 183with KVM_CAP_CHECK_EXTENSION_VM on the vm fd) 184 1854.5 KVM_GET_VCPU_MMAP_SIZE 186 187Capability: basic 188Architectures: all 189Type: system ioctl 190Parameters: none 191Returns: size of vcpu mmap area, in bytes 192 193The KVM_RUN ioctl (cf.) communicates with userspace via a shared 194memory region. This ioctl returns the size of that region. See the 195KVM_RUN documentation for details. 196 197 1984.6 KVM_SET_MEMORY_REGION 199 200Capability: basic 201Architectures: all 202Type: vm ioctl 203Parameters: struct kvm_memory_region (in) 204Returns: 0 on success, -1 on error 205 206This ioctl is obsolete and has been removed. 207 208 2094.7 KVM_CREATE_VCPU 210 211Capability: basic 212Architectures: all 213Type: vm ioctl 214Parameters: vcpu id (apic id on x86) 215Returns: vcpu fd on success, -1 on error 216 217This API adds a vcpu to a virtual machine. No more than max_vcpus may be added. 218The vcpu id is an integer in the range [0, max_vcpu_id). 219 220The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of 221the KVM_CHECK_EXTENSION ioctl() at run-time. 222The maximum possible value for max_vcpus can be retrieved using the 223KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time. 224 225If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4 226cpus max. 227If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is 228same as the value returned from KVM_CAP_NR_VCPUS. 229 230The maximum possible value for max_vcpu_id can be retrieved using the 231KVM_CAP_MAX_VCPU_ID of the KVM_CHECK_EXTENSION ioctl() at run-time. 232 233If the KVM_CAP_MAX_VCPU_ID does not exist, you should assume that max_vcpu_id 234is the same as the value returned from KVM_CAP_MAX_VCPUS. 235 236On powerpc using book3s_hv mode, the vcpus are mapped onto virtual 237threads in one or more virtual CPU cores. (This is because the 238hardware requires all the hardware threads in a CPU core to be in the 239same partition.) The KVM_CAP_PPC_SMT capability indicates the number 240of vcpus per virtual core (vcore). The vcore id is obtained by 241dividing the vcpu id by the number of vcpus per vcore. The vcpus in a 242given vcore will always be in the same physical core as each other 243(though that might be a different physical core from time to time). 244Userspace can control the threading (SMT) mode of the guest by its 245allocation of vcpu ids. For example, if userspace wants 246single-threaded guest vcpus, it should make all vcpu ids be a multiple 247of the number of vcpus per vcore. 248 249For virtual cpus that have been created with S390 user controlled virtual 250machines, the resulting vcpu fd can be memory mapped at page offset 251KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtual 252cpu's hardware control block. 253 254 2554.8 KVM_GET_DIRTY_LOG (vm ioctl) 256 257Capability: basic 258Architectures: x86 259Type: vm ioctl 260Parameters: struct kvm_dirty_log (in/out) 261Returns: 0 on success, -1 on error 262 263/* for KVM_GET_DIRTY_LOG */ 264struct kvm_dirty_log { 265 __u32 slot; 266 __u32 padding; 267 union { 268 void __user *dirty_bitmap; /* one bit per page */ 269 __u64 padding; 270 }; 271}; 272 273Given a memory slot, return a bitmap containing any pages dirtied 274since the last call to this ioctl. Bit 0 is the first page in the 275memory slot. Ensure the entire structure is cleared to avoid padding 276issues. 277 278If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 specifies 279the address space for which you want to return the dirty bitmap. 280They must be less than the value that KVM_CHECK_EXTENSION returns for 281the KVM_CAP_MULTI_ADDRESS_SPACE capability. 282 283 2844.9 KVM_SET_MEMORY_ALIAS 285 286Capability: basic 287Architectures: x86 288Type: vm ioctl 289Parameters: struct kvm_memory_alias (in) 290Returns: 0 (success), -1 (error) 291 292This ioctl is obsolete and has been removed. 293 294 2954.10 KVM_RUN 296 297Capability: basic 298Architectures: all 299Type: vcpu ioctl 300Parameters: none 301Returns: 0 on success, -1 on error 302Errors: 303 EINTR: an unmasked signal is pending 304 305This ioctl is used to run a guest virtual cpu. While there are no 306explicit parameters, there is an implicit parameter block that can be 307obtained by mmap()ing the vcpu fd at offset 0, with the size given by 308KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct 309kvm_run' (see below). 310 311 3124.11 KVM_GET_REGS 313 314Capability: basic 315Architectures: all except ARM, arm64 316Type: vcpu ioctl 317Parameters: struct kvm_regs (out) 318Returns: 0 on success, -1 on error 319 320Reads the general purpose registers from the vcpu. 321 322/* x86 */ 323struct kvm_regs { 324 /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ 325 __u64 rax, rbx, rcx, rdx; 326 __u64 rsi, rdi, rsp, rbp; 327 __u64 r8, r9, r10, r11; 328 __u64 r12, r13, r14, r15; 329 __u64 rip, rflags; 330}; 331 332/* mips */ 333struct kvm_regs { 334 /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */ 335 __u64 gpr[32]; 336 __u64 hi; 337 __u64 lo; 338 __u64 pc; 339}; 340 341 3424.12 KVM_SET_REGS 343 344Capability: basic 345Architectures: all except ARM, arm64 346Type: vcpu ioctl 347Parameters: struct kvm_regs (in) 348Returns: 0 on success, -1 on error 349 350Writes the general purpose registers into the vcpu. 351 352See KVM_GET_REGS for the data structure. 353 354 3554.13 KVM_GET_SREGS 356 357Capability: basic 358Architectures: x86, ppc 359Type: vcpu ioctl 360Parameters: struct kvm_sregs (out) 361Returns: 0 on success, -1 on error 362 363Reads special registers from the vcpu. 364 365/* x86 */ 366struct kvm_sregs { 367 struct kvm_segment cs, ds, es, fs, gs, ss; 368 struct kvm_segment tr, ldt; 369 struct kvm_dtable gdt, idt; 370 __u64 cr0, cr2, cr3, cr4, cr8; 371 __u64 efer; 372 __u64 apic_base; 373 __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64]; 374}; 375 376/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */ 377 378interrupt_bitmap is a bitmap of pending external interrupts. At most 379one bit may be set. This interrupt has been acknowledged by the APIC 380but not yet injected into the cpu core. 381 382 3834.14 KVM_SET_SREGS 384 385Capability: basic 386Architectures: x86, ppc 387Type: vcpu ioctl 388Parameters: struct kvm_sregs (in) 389Returns: 0 on success, -1 on error 390 391Writes special registers into the vcpu. See KVM_GET_SREGS for the 392data structures. 393 394 3954.15 KVM_TRANSLATE 396 397Capability: basic 398Architectures: x86 399Type: vcpu ioctl 400Parameters: struct kvm_translation (in/out) 401Returns: 0 on success, -1 on error 402 403Translates a virtual address according to the vcpu's current address 404translation mode. 405 406struct kvm_translation { 407 /* in */ 408 __u64 linear_address; 409 410 /* out */ 411 __u64 physical_address; 412 __u8 valid; 413 __u8 writeable; 414 __u8 usermode; 415 __u8 pad[5]; 416}; 417 418 4194.16 KVM_INTERRUPT 420 421Capability: basic 422Architectures: x86, ppc, mips 423Type: vcpu ioctl 424Parameters: struct kvm_interrupt (in) 425Returns: 0 on success, negative on failure. 426 427Queues a hardware interrupt vector to be injected. 428 429/* for KVM_INTERRUPT */ 430struct kvm_interrupt { 431 /* in */ 432 __u32 irq; 433}; 434 435X86: 436 437Returns: 0 on success, 438 -EEXIST if an interrupt is already enqueued 439 -EINVAL the the irq number is invalid 440 -ENXIO if the PIC is in the kernel 441 -EFAULT if the pointer is invalid 442 443Note 'irq' is an interrupt vector, not an interrupt pin or line. This 444ioctl is useful if the in-kernel PIC is not used. 445 446PPC: 447 448Queues an external interrupt to be injected. This ioctl is overleaded 449with 3 different irq values: 450 451a) KVM_INTERRUPT_SET 452 453 This injects an edge type external interrupt into the guest once it's ready 454 to receive interrupts. When injected, the interrupt is done. 455 456b) KVM_INTERRUPT_UNSET 457 458 This unsets any pending interrupt. 459 460 Only available with KVM_CAP_PPC_UNSET_IRQ. 461 462c) KVM_INTERRUPT_SET_LEVEL 463 464 This injects a level type external interrupt into the guest context. The 465 interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET 466 is triggered. 467 468 Only available with KVM_CAP_PPC_IRQ_LEVEL. 469 470Note that any value for 'irq' other than the ones stated above is invalid 471and incurs unexpected behavior. 472 473MIPS: 474 475Queues an external interrupt to be injected into the virtual CPU. A negative 476interrupt number dequeues the interrupt. 477 478 4794.17 KVM_DEBUG_GUEST 480 481Capability: basic 482Architectures: none 483Type: vcpu ioctl 484Parameters: none) 485Returns: -1 on error 486 487Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead. 488 489 4904.18 KVM_GET_MSRS 491 492Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system) 493Architectures: x86 494Type: system ioctl, vcpu ioctl 495Parameters: struct kvm_msrs (in/out) 496Returns: number of msrs successfully returned; 497 -1 on error 498 499When used as a system ioctl: 500Reads the values of MSR-based features that are available for the VM. This 501is similar to KVM_GET_SUPPORTED_CPUID, but it returns MSR indices and values. 502The list of msr-based features can be obtained using KVM_GET_MSR_FEATURE_INDEX_LIST 503in a system ioctl. 504 505When used as a vcpu ioctl: 506Reads model-specific registers from the vcpu. Supported msr indices can 507be obtained using KVM_GET_MSR_INDEX_LIST in a system ioctl. 508 509struct kvm_msrs { 510 __u32 nmsrs; /* number of msrs in entries */ 511 __u32 pad; 512 513 struct kvm_msr_entry entries[0]; 514}; 515 516struct kvm_msr_entry { 517 __u32 index; 518 __u32 reserved; 519 __u64 data; 520}; 521 522Application code should set the 'nmsrs' member (which indicates the 523size of the entries array) and the 'index' member of each array entry. 524kvm will fill in the 'data' member. 525 526 5274.19 KVM_SET_MSRS 528 529Capability: basic 530Architectures: x86 531Type: vcpu ioctl 532Parameters: struct kvm_msrs (in) 533Returns: 0 on success, -1 on error 534 535Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the 536data structures. 537 538Application code should set the 'nmsrs' member (which indicates the 539size of the entries array), and the 'index' and 'data' members of each 540array entry. 541 542 5434.20 KVM_SET_CPUID 544 545Capability: basic 546Architectures: x86 547Type: vcpu ioctl 548Parameters: struct kvm_cpuid (in) 549Returns: 0 on success, -1 on error 550 551Defines the vcpu responses to the cpuid instruction. Applications 552should use the KVM_SET_CPUID2 ioctl if available. 553 554 555struct kvm_cpuid_entry { 556 __u32 function; 557 __u32 eax; 558 __u32 ebx; 559 __u32 ecx; 560 __u32 edx; 561 __u32 padding; 562}; 563 564/* for KVM_SET_CPUID */ 565struct kvm_cpuid { 566 __u32 nent; 567 __u32 padding; 568 struct kvm_cpuid_entry entries[0]; 569}; 570 571 5724.21 KVM_SET_SIGNAL_MASK 573 574Capability: basic 575Architectures: all 576Type: vcpu ioctl 577Parameters: struct kvm_signal_mask (in) 578Returns: 0 on success, -1 on error 579 580Defines which signals are blocked during execution of KVM_RUN. This 581signal mask temporarily overrides the threads signal mask. Any 582unblocked signal received (except SIGKILL and SIGSTOP, which retain 583their traditional behaviour) will cause KVM_RUN to return with -EINTR. 584 585Note the signal will only be delivered if not blocked by the original 586signal mask. 587 588/* for KVM_SET_SIGNAL_MASK */ 589struct kvm_signal_mask { 590 __u32 len; 591 __u8 sigset[0]; 592}; 593 594 5954.22 KVM_GET_FPU 596 597Capability: basic 598Architectures: x86 599Type: vcpu ioctl 600Parameters: struct kvm_fpu (out) 601Returns: 0 on success, -1 on error 602 603Reads the floating point state from the vcpu. 604 605/* for KVM_GET_FPU and KVM_SET_FPU */ 606struct kvm_fpu { 607 __u8 fpr[8][16]; 608 __u16 fcw; 609 __u16 fsw; 610 __u8 ftwx; /* in fxsave format */ 611 __u8 pad1; 612 __u16 last_opcode; 613 __u64 last_ip; 614 __u64 last_dp; 615 __u8 xmm[16][16]; 616 __u32 mxcsr; 617 __u32 pad2; 618}; 619 620 6214.23 KVM_SET_FPU 622 623Capability: basic 624Architectures: x86 625Type: vcpu ioctl 626Parameters: struct kvm_fpu (in) 627Returns: 0 on success, -1 on error 628 629Writes the floating point state to the vcpu. 630 631/* for KVM_GET_FPU and KVM_SET_FPU */ 632struct kvm_fpu { 633 __u8 fpr[8][16]; 634 __u16 fcw; 635 __u16 fsw; 636 __u8 ftwx; /* in fxsave format */ 637 __u8 pad1; 638 __u16 last_opcode; 639 __u64 last_ip; 640 __u64 last_dp; 641 __u8 xmm[16][16]; 642 __u32 mxcsr; 643 __u32 pad2; 644}; 645 646 6474.24 KVM_CREATE_IRQCHIP 648 649Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390) 650Architectures: x86, ARM, arm64, s390 651Type: vm ioctl 652Parameters: none 653Returns: 0 on success, -1 on error 654 655Creates an interrupt controller model in the kernel. 656On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up 657future vcpus to have a local APIC. IRQ routing for GSIs 0-15 is set to both 658PIC and IOAPIC; GSI 16-23 only go to the IOAPIC. 659On ARM/arm64, a GICv2 is created. Any other GIC versions require the usage of 660KVM_CREATE_DEVICE, which also supports creating a GICv2. Using 661KVM_CREATE_DEVICE is preferred over KVM_CREATE_IRQCHIP for GICv2. 662On s390, a dummy irq routing table is created. 663 664Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled 665before KVM_CREATE_IRQCHIP can be used. 666 667 6684.25 KVM_IRQ_LINE 669 670Capability: KVM_CAP_IRQCHIP 671Architectures: x86, arm, arm64 672Type: vm ioctl 673Parameters: struct kvm_irq_level 674Returns: 0 on success, -1 on error 675 676Sets the level of a GSI input to the interrupt controller model in the kernel. 677On some architectures it is required that an interrupt controller model has 678been previously created with KVM_CREATE_IRQCHIP. Note that edge-triggered 679interrupts require the level to be set to 1 and then back to 0. 680 681On real hardware, interrupt pins can be active-low or active-high. This 682does not matter for the level field of struct kvm_irq_level: 1 always 683means active (asserted), 0 means inactive (deasserted). 684 685x86 allows the operating system to program the interrupt polarity 686(active-low/active-high) for level-triggered interrupts, and KVM used 687to consider the polarity. However, due to bitrot in the handling of 688active-low interrupts, the above convention is now valid on x86 too. 689This is signaled by KVM_CAP_X86_IOAPIC_POLARITY_IGNORED. Userspace 690should not present interrupts to the guest as active-low unless this 691capability is present (or unless it is not using the in-kernel irqchip, 692of course). 693 694 695ARM/arm64 can signal an interrupt either at the CPU level, or at the 696in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to 697use PPIs designated for specific cpus. The irq field is interpreted 698like this: 699 700 bits: | 31 ... 24 | 23 ... 16 | 15 ... 0 | 701 field: | irq_type | vcpu_index | irq_id | 702 703The irq_type field has the following values: 704- irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ 705- irq_type[1]: in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.) 706 (the vcpu_index field is ignored) 707- irq_type[2]: in-kernel GIC: PPI, irq_id between 16 and 31 (incl.) 708 709(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs) 710 711In both cases, level is used to assert/deassert the line. 712 713struct kvm_irq_level { 714 union { 715 __u32 irq; /* GSI */ 716 __s32 status; /* not used for KVM_IRQ_LEVEL */ 717 }; 718 __u32 level; /* 0 or 1 */ 719}; 720 721 7224.26 KVM_GET_IRQCHIP 723 724Capability: KVM_CAP_IRQCHIP 725Architectures: x86 726Type: vm ioctl 727Parameters: struct kvm_irqchip (in/out) 728Returns: 0 on success, -1 on error 729 730Reads the state of a kernel interrupt controller created with 731KVM_CREATE_IRQCHIP into a buffer provided by the caller. 732 733struct kvm_irqchip { 734 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ 735 __u32 pad; 736 union { 737 char dummy[512]; /* reserving space */ 738 struct kvm_pic_state pic; 739 struct kvm_ioapic_state ioapic; 740 } chip; 741}; 742 743 7444.27 KVM_SET_IRQCHIP 745 746Capability: KVM_CAP_IRQCHIP 747Architectures: x86 748Type: vm ioctl 749Parameters: struct kvm_irqchip (in) 750Returns: 0 on success, -1 on error 751 752Sets the state of a kernel interrupt controller created with 753KVM_CREATE_IRQCHIP from a buffer provided by the caller. 754 755struct kvm_irqchip { 756 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */ 757 __u32 pad; 758 union { 759 char dummy[512]; /* reserving space */ 760 struct kvm_pic_state pic; 761 struct kvm_ioapic_state ioapic; 762 } chip; 763}; 764 765 7664.28 KVM_XEN_HVM_CONFIG 767 768Capability: KVM_CAP_XEN_HVM 769Architectures: x86 770Type: vm ioctl 771Parameters: struct kvm_xen_hvm_config (in) 772Returns: 0 on success, -1 on error 773 774Sets the MSR that the Xen HVM guest uses to initialize its hypercall 775page, and provides the starting address and size of the hypercall 776blobs in userspace. When the guest writes the MSR, kvm copies one 777page of a blob (32- or 64-bit, depending on the vcpu mode) to guest 778memory. 779 780struct kvm_xen_hvm_config { 781 __u32 flags; 782 __u32 msr; 783 __u64 blob_addr_32; 784 __u64 blob_addr_64; 785 __u8 blob_size_32; 786 __u8 blob_size_64; 787 __u8 pad2[30]; 788}; 789 790 7914.29 KVM_GET_CLOCK 792 793Capability: KVM_CAP_ADJUST_CLOCK 794Architectures: x86 795Type: vm ioctl 796Parameters: struct kvm_clock_data (out) 797Returns: 0 on success, -1 on error 798 799Gets the current timestamp of kvmclock as seen by the current guest. In 800conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios 801such as migration. 802 803When KVM_CAP_ADJUST_CLOCK is passed to KVM_CHECK_EXTENSION, it returns the 804set of bits that KVM can return in struct kvm_clock_data's flag member. 805 806The only flag defined now is KVM_CLOCK_TSC_STABLE. If set, the returned 807value is the exact kvmclock value seen by all VCPUs at the instant 808when KVM_GET_CLOCK was called. If clear, the returned value is simply 809CLOCK_MONOTONIC plus a constant offset; the offset can be modified 810with KVM_SET_CLOCK. KVM will try to make all VCPUs follow this clock, 811but the exact value read by each VCPU could differ, because the host 812TSC is not stable. 813 814struct kvm_clock_data { 815 __u64 clock; /* kvmclock current value */ 816 __u32 flags; 817 __u32 pad[9]; 818}; 819 820 8214.30 KVM_SET_CLOCK 822 823Capability: KVM_CAP_ADJUST_CLOCK 824Architectures: x86 825Type: vm ioctl 826Parameters: struct kvm_clock_data (in) 827Returns: 0 on success, -1 on error 828 829Sets the current timestamp of kvmclock to the value specified in its parameter. 830In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios 831such as migration. 832 833struct kvm_clock_data { 834 __u64 clock; /* kvmclock current value */ 835 __u32 flags; 836 __u32 pad[9]; 837}; 838 839 8404.31 KVM_GET_VCPU_EVENTS 841 842Capability: KVM_CAP_VCPU_EVENTS 843Extended by: KVM_CAP_INTR_SHADOW 844Architectures: x86 845Type: vm ioctl 846Parameters: struct kvm_vcpu_event (out) 847Returns: 0 on success, -1 on error 848 849Gets currently pending exceptions, interrupts, and NMIs as well as related 850states of the vcpu. 851 852struct kvm_vcpu_events { 853 struct { 854 __u8 injected; 855 __u8 nr; 856 __u8 has_error_code; 857 __u8 pad; 858 __u32 error_code; 859 } exception; 860 struct { 861 __u8 injected; 862 __u8 nr; 863 __u8 soft; 864 __u8 shadow; 865 } interrupt; 866 struct { 867 __u8 injected; 868 __u8 pending; 869 __u8 masked; 870 __u8 pad; 871 } nmi; 872 __u32 sipi_vector; 873 __u32 flags; 874 struct { 875 __u8 smm; 876 __u8 pending; 877 __u8 smm_inside_nmi; 878 __u8 latched_init; 879 } smi; 880}; 881 882Only two fields are defined in the flags field: 883 884- KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that 885 interrupt.shadow contains a valid state. 886 887- KVM_VCPUEVENT_VALID_SMM may be set in the flags field to signal that 888 smi contains a valid state. 889 8904.32 KVM_SET_VCPU_EVENTS 891 892Capability: KVM_CAP_VCPU_EVENTS 893Extended by: KVM_CAP_INTR_SHADOW 894Architectures: x86 895Type: vm ioctl 896Parameters: struct kvm_vcpu_event (in) 897Returns: 0 on success, -1 on error 898 899Set pending exceptions, interrupts, and NMIs as well as related states of the 900vcpu. 901 902See KVM_GET_VCPU_EVENTS for the data structure. 903 904Fields that may be modified asynchronously by running VCPUs can be excluded 905from the update. These fields are nmi.pending, sipi_vector, smi.smm, 906smi.pending. Keep the corresponding bits in the flags field cleared to 907suppress overwriting the current in-kernel state. The bits are: 908 909KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel 910KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector 911KVM_VCPUEVENT_VALID_SMM - transfer the smi sub-struct. 912 913If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in 914the flags field to signal that interrupt.shadow contains a valid state and 915shall be written into the VCPU. 916 917KVM_VCPUEVENT_VALID_SMM can only be set if KVM_CAP_X86_SMM is available. 918 919 9204.33 KVM_GET_DEBUGREGS 921 922Capability: KVM_CAP_DEBUGREGS 923Architectures: x86 924Type: vm ioctl 925Parameters: struct kvm_debugregs (out) 926Returns: 0 on success, -1 on error 927 928Reads debug registers from the vcpu. 929 930struct kvm_debugregs { 931 __u64 db[4]; 932 __u64 dr6; 933 __u64 dr7; 934 __u64 flags; 935 __u64 reserved[9]; 936}; 937 938 9394.34 KVM_SET_DEBUGREGS 940 941Capability: KVM_CAP_DEBUGREGS 942Architectures: x86 943Type: vm ioctl 944Parameters: struct kvm_debugregs (in) 945Returns: 0 on success, -1 on error 946 947Writes debug registers into the vcpu. 948 949See KVM_GET_DEBUGREGS for the data structure. The flags field is unused 950yet and must be cleared on entry. 951 952 9534.35 KVM_SET_USER_MEMORY_REGION 954 955Capability: KVM_CAP_USER_MEM 956Architectures: all 957Type: vm ioctl 958Parameters: struct kvm_userspace_memory_region (in) 959Returns: 0 on success, -1 on error 960 961struct kvm_userspace_memory_region { 962 __u32 slot; 963 __u32 flags; 964 __u64 guest_phys_addr; 965 __u64 memory_size; /* bytes */ 966 __u64 userspace_addr; /* start of the userspace allocated memory */ 967}; 968 969/* for kvm_memory_region::flags */ 970#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0) 971#define KVM_MEM_READONLY (1UL << 1) 972 973This ioctl allows the user to create or modify a guest physical memory 974slot. When changing an existing slot, it may be moved in the guest 975physical memory space, or its flags may be modified. It may not be 976resized. Slots may not overlap in guest physical address space. 977Bits 0-15 of "slot" specifies the slot id and this value should be 978less than the maximum number of user memory slots supported per VM. 979The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS, 980if this capability is supported by the architecture. 981 982If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot" 983specifies the address space which is being modified. They must be 984less than the value that KVM_CHECK_EXTENSION returns for the 985KVM_CAP_MULTI_ADDRESS_SPACE capability. Slots in separate address spaces 986are unrelated; the restriction on overlapping slots only applies within 987each address space. 988 989Memory for the region is taken starting at the address denoted by the 990field userspace_addr, which must point at user addressable memory for 991the entire memory slot size. Any object may back this memory, including 992anonymous memory, ordinary files, and hugetlbfs. 993 994It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr 995be identical. This allows large pages in the guest to be backed by large 996pages in the host. 997 998The flags field supports two flags: KVM_MEM_LOG_DIRTY_PAGES and 999KVM_MEM_READONLY. The former can be set to instruct KVM to keep track of 1000writes to memory within the slot. See KVM_GET_DIRTY_LOG ioctl to know how to 1001use it. The latter can be set, if KVM_CAP_READONLY_MEM capability allows it, 1002to make a new slot read-only. In this case, writes to this memory will be 1003posted to userspace as KVM_EXIT_MMIO exits. 1004 1005When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of 1006the memory region are automatically reflected into the guest. For example, an 1007mmap() that affects the region will be made visible immediately. Another 1008example is madvise(MADV_DROP). 1009 1010It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl. 1011The KVM_SET_MEMORY_REGION does not allow fine grained control over memory 1012allocation and is deprecated. 1013 1014 10154.36 KVM_SET_TSS_ADDR 1016 1017Capability: KVM_CAP_SET_TSS_ADDR 1018Architectures: x86 1019Type: vm ioctl 1020Parameters: unsigned long tss_address (in) 1021Returns: 0 on success, -1 on error 1022 1023This ioctl defines the physical address of a three-page region in the guest 1024physical address space. The region must be within the first 4GB of the 1025guest physical address space and must not conflict with any memory slot 1026or any mmio address. The guest may malfunction if it accesses this memory 1027region. 1028 1029This ioctl is required on Intel-based hosts. This is needed on Intel hardware 1030because of a quirk in the virtualization implementation (see the internals 1031documentation when it pops into existence). 1032 1033 10344.37 KVM_ENABLE_CAP 1035 1036Capability: KVM_CAP_ENABLE_CAP, KVM_CAP_ENABLE_CAP_VM 1037Architectures: x86 (only KVM_CAP_ENABLE_CAP_VM), 1038 mips (only KVM_CAP_ENABLE_CAP), ppc, s390 1039Type: vcpu ioctl, vm ioctl (with KVM_CAP_ENABLE_CAP_VM) 1040Parameters: struct kvm_enable_cap (in) 1041Returns: 0 on success; -1 on error 1042 1043+Not all extensions are enabled by default. Using this ioctl the application 1044can enable an extension, making it available to the guest. 1045 1046On systems that do not support this ioctl, it always fails. On systems that 1047do support it, it only works for extensions that are supported for enablement. 1048 1049To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should 1050be used. 1051 1052struct kvm_enable_cap { 1053 /* in */ 1054 __u32 cap; 1055 1056The capability that is supposed to get enabled. 1057 1058 __u32 flags; 1059 1060A bitfield indicating future enhancements. Has to be 0 for now. 1061 1062 __u64 args[4]; 1063 1064Arguments for enabling a feature. If a feature needs initial values to 1065function properly, this is the place to put them. 1066 1067 __u8 pad[64]; 1068}; 1069 1070The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl 1071for vm-wide capabilities. 1072 10734.38 KVM_GET_MP_STATE 1074 1075Capability: KVM_CAP_MP_STATE 1076Architectures: x86, s390, arm, arm64 1077Type: vcpu ioctl 1078Parameters: struct kvm_mp_state (out) 1079Returns: 0 on success; -1 on error 1080 1081struct kvm_mp_state { 1082 __u32 mp_state; 1083}; 1084 1085Returns the vcpu's current "multiprocessing state" (though also valid on 1086uniprocessor guests). 1087 1088Possible values are: 1089 1090 - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86,arm/arm64] 1091 - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP) 1092 which has not yet received an INIT signal [x86] 1093 - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is 1094 now ready for a SIPI [x86] 1095 - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and 1096 is waiting for an interrupt [x86] 1097 - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector 1098 accessible via KVM_GET_VCPU_EVENTS) [x86] 1099 - KVM_MP_STATE_STOPPED: the vcpu is stopped [s390,arm/arm64] 1100 - KVM_MP_STATE_CHECK_STOP: the vcpu is in a special error state [s390] 1101 - KVM_MP_STATE_OPERATING: the vcpu is operating (running or halted) 1102 [s390] 1103 - KVM_MP_STATE_LOAD: the vcpu is in a special load/startup state 1104 [s390] 1105 1106On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an 1107in-kernel irqchip, the multiprocessing state must be maintained by userspace on 1108these architectures. 1109 1110For arm/arm64: 1111 1112The only states that are valid are KVM_MP_STATE_STOPPED and 1113KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not. 1114 11154.39 KVM_SET_MP_STATE 1116 1117Capability: KVM_CAP_MP_STATE 1118Architectures: x86, s390, arm, arm64 1119Type: vcpu ioctl 1120Parameters: struct kvm_mp_state (in) 1121Returns: 0 on success; -1 on error 1122 1123Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for 1124arguments. 1125 1126On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an 1127in-kernel irqchip, the multiprocessing state must be maintained by userspace on 1128these architectures. 1129 1130For arm/arm64: 1131 1132The only states that are valid are KVM_MP_STATE_STOPPED and 1133KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not. 1134 11354.40 KVM_SET_IDENTITY_MAP_ADDR 1136 1137Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR 1138Architectures: x86 1139Type: vm ioctl 1140Parameters: unsigned long identity (in) 1141Returns: 0 on success, -1 on error 1142 1143This ioctl defines the physical address of a one-page region in the guest 1144physical address space. The region must be within the first 4GB of the 1145guest physical address space and must not conflict with any memory slot 1146or any mmio address. The guest may malfunction if it accesses this memory 1147region. 1148 1149This ioctl is required on Intel-based hosts. This is needed on Intel hardware 1150because of a quirk in the virtualization implementation (see the internals 1151documentation when it pops into existence). 1152 1153 11544.41 KVM_SET_BOOT_CPU_ID 1155 1156Capability: KVM_CAP_SET_BOOT_CPU_ID 1157Architectures: x86 1158Type: vm ioctl 1159Parameters: unsigned long vcpu_id 1160Returns: 0 on success, -1 on error 1161 1162Define which vcpu is the Bootstrap Processor (BSP). Values are the same 1163as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default 1164is vcpu 0. 1165 1166 11674.42 KVM_GET_XSAVE 1168 1169Capability: KVM_CAP_XSAVE 1170Architectures: x86 1171Type: vcpu ioctl 1172Parameters: struct kvm_xsave (out) 1173Returns: 0 on success, -1 on error 1174 1175struct kvm_xsave { 1176 __u32 region[1024]; 1177}; 1178 1179This ioctl would copy current vcpu's xsave struct to the userspace. 1180 1181 11824.43 KVM_SET_XSAVE 1183 1184Capability: KVM_CAP_XSAVE 1185Architectures: x86 1186Type: vcpu ioctl 1187Parameters: struct kvm_xsave (in) 1188Returns: 0 on success, -1 on error 1189 1190struct kvm_xsave { 1191 __u32 region[1024]; 1192}; 1193 1194This ioctl would copy userspace's xsave struct to the kernel. 1195 1196 11974.44 KVM_GET_XCRS 1198 1199Capability: KVM_CAP_XCRS 1200Architectures: x86 1201Type: vcpu ioctl 1202Parameters: struct kvm_xcrs (out) 1203Returns: 0 on success, -1 on error 1204 1205struct kvm_xcr { 1206 __u32 xcr; 1207 __u32 reserved; 1208 __u64 value; 1209}; 1210 1211struct kvm_xcrs { 1212 __u32 nr_xcrs; 1213 __u32 flags; 1214 struct kvm_xcr xcrs[KVM_MAX_XCRS]; 1215 __u64 padding[16]; 1216}; 1217 1218This ioctl would copy current vcpu's xcrs to the userspace. 1219 1220 12214.45 KVM_SET_XCRS 1222 1223Capability: KVM_CAP_XCRS 1224Architectures: x86 1225Type: vcpu ioctl 1226Parameters: struct kvm_xcrs (in) 1227Returns: 0 on success, -1 on error 1228 1229struct kvm_xcr { 1230 __u32 xcr; 1231 __u32 reserved; 1232 __u64 value; 1233}; 1234 1235struct kvm_xcrs { 1236 __u32 nr_xcrs; 1237 __u32 flags; 1238 struct kvm_xcr xcrs[KVM_MAX_XCRS]; 1239 __u64 padding[16]; 1240}; 1241 1242This ioctl would set vcpu's xcr to the value userspace specified. 1243 1244 12454.46 KVM_GET_SUPPORTED_CPUID 1246 1247Capability: KVM_CAP_EXT_CPUID 1248Architectures: x86 1249Type: system ioctl 1250Parameters: struct kvm_cpuid2 (in/out) 1251Returns: 0 on success, -1 on error 1252 1253struct kvm_cpuid2 { 1254 __u32 nent; 1255 __u32 padding; 1256 struct kvm_cpuid_entry2 entries[0]; 1257}; 1258 1259#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) 1260#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) 1261#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) 1262 1263struct kvm_cpuid_entry2 { 1264 __u32 function; 1265 __u32 index; 1266 __u32 flags; 1267 __u32 eax; 1268 __u32 ebx; 1269 __u32 ecx; 1270 __u32 edx; 1271 __u32 padding[3]; 1272}; 1273 1274This ioctl returns x86 cpuid features which are supported by both the hardware 1275and kvm. Userspace can use the information returned by this ioctl to 1276construct cpuid information (for KVM_SET_CPUID2) that is consistent with 1277hardware, kernel, and userspace capabilities, and with user requirements (for 1278example, the user may wish to constrain cpuid to emulate older hardware, 1279or for feature consistency across a cluster). 1280 1281Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure 1282with the 'nent' field indicating the number of entries in the variable-size 1283array 'entries'. If the number of entries is too low to describe the cpu 1284capabilities, an error (E2BIG) is returned. If the number is too high, 1285the 'nent' field is adjusted and an error (ENOMEM) is returned. If the 1286number is just right, the 'nent' field is adjusted to the number of valid 1287entries in the 'entries' array, which is then filled. 1288 1289The entries returned are the host cpuid as returned by the cpuid instruction, 1290with unknown or unsupported features masked out. Some features (for example, 1291x2apic), may not be present in the host cpu, but are exposed by kvm if it can 1292emulate them efficiently. The fields in each entry are defined as follows: 1293 1294 function: the eax value used to obtain the entry 1295 index: the ecx value used to obtain the entry (for entries that are 1296 affected by ecx) 1297 flags: an OR of zero or more of the following: 1298 KVM_CPUID_FLAG_SIGNIFCANT_INDEX: 1299 if the index field is valid 1300 KVM_CPUID_FLAG_STATEFUL_FUNC: 1301 if cpuid for this function returns different values for successive 1302 invocations; there will be several entries with the same function, 1303 all with this flag set 1304 KVM_CPUID_FLAG_STATE_READ_NEXT: 1305 for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is 1306 the first entry to be read by a cpu 1307 eax, ebx, ecx, edx: the values returned by the cpuid instruction for 1308 this function/index combination 1309 1310The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned 1311as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC 1312support. Instead it is reported via 1313 1314 ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER) 1315 1316if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the 1317feature in userspace, then you can enable the feature for KVM_SET_CPUID2. 1318 1319 13204.47 KVM_PPC_GET_PVINFO 1321 1322Capability: KVM_CAP_PPC_GET_PVINFO 1323Architectures: ppc 1324Type: vm ioctl 1325Parameters: struct kvm_ppc_pvinfo (out) 1326Returns: 0 on success, !0 on error 1327 1328struct kvm_ppc_pvinfo { 1329 __u32 flags; 1330 __u32 hcall[4]; 1331 __u8 pad[108]; 1332}; 1333 1334This ioctl fetches PV specific information that need to be passed to the guest 1335using the device tree or other means from vm context. 1336 1337The hcall array defines 4 instructions that make up a hypercall. 1338 1339If any additional field gets added to this structure later on, a bit for that 1340additional piece of information will be set in the flags bitmap. 1341 1342The flags bitmap is defined as: 1343 1344 /* the host supports the ePAPR idle hcall 1345 #define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0) 1346 13474.52 KVM_SET_GSI_ROUTING 1348 1349Capability: KVM_CAP_IRQ_ROUTING 1350Architectures: x86 s390 arm arm64 1351Type: vm ioctl 1352Parameters: struct kvm_irq_routing (in) 1353Returns: 0 on success, -1 on error 1354 1355Sets the GSI routing table entries, overwriting any previously set entries. 1356 1357On arm/arm64, GSI routing has the following limitation: 1358- GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD. 1359 1360struct kvm_irq_routing { 1361 __u32 nr; 1362 __u32 flags; 1363 struct kvm_irq_routing_entry entries[0]; 1364}; 1365 1366No flags are specified so far, the corresponding field must be set to zero. 1367 1368struct kvm_irq_routing_entry { 1369 __u32 gsi; 1370 __u32 type; 1371 __u32 flags; 1372 __u32 pad; 1373 union { 1374 struct kvm_irq_routing_irqchip irqchip; 1375 struct kvm_irq_routing_msi msi; 1376 struct kvm_irq_routing_s390_adapter adapter; 1377 struct kvm_irq_routing_hv_sint hv_sint; 1378 __u32 pad[8]; 1379 } u; 1380}; 1381 1382/* gsi routing entry types */ 1383#define KVM_IRQ_ROUTING_IRQCHIP 1 1384#define KVM_IRQ_ROUTING_MSI 2 1385#define KVM_IRQ_ROUTING_S390_ADAPTER 3 1386#define KVM_IRQ_ROUTING_HV_SINT 4 1387 1388flags: 1389- KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entry 1390 type, specifies that the devid field contains a valid value. The per-VM 1391 KVM_CAP_MSI_DEVID capability advertises the requirement to provide 1392 the device ID. If this capability is not available, userspace should 1393 never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail. 1394- zero otherwise 1395 1396struct kvm_irq_routing_irqchip { 1397 __u32 irqchip; 1398 __u32 pin; 1399}; 1400 1401struct kvm_irq_routing_msi { 1402 __u32 address_lo; 1403 __u32 address_hi; 1404 __u32 data; 1405 union { 1406 __u32 pad; 1407 __u32 devid; 1408 }; 1409}; 1410 1411If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier 1412for the device that wrote the MSI message. For PCI, this is usually a 1413BFD identifier in the lower 16 bits. 1414 1415On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS 1416feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled, 1417address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of 1418address_hi must be zero. 1419 1420struct kvm_irq_routing_s390_adapter { 1421 __u64 ind_addr; 1422 __u64 summary_addr; 1423 __u64 ind_offset; 1424 __u32 summary_offset; 1425 __u32 adapter_id; 1426}; 1427 1428struct kvm_irq_routing_hv_sint { 1429 __u32 vcpu; 1430 __u32 sint; 1431}; 1432 1433 14344.55 KVM_SET_TSC_KHZ 1435 1436Capability: KVM_CAP_TSC_CONTROL 1437Architectures: x86 1438Type: vcpu ioctl 1439Parameters: virtual tsc_khz 1440Returns: 0 on success, -1 on error 1441 1442Specifies the tsc frequency for the virtual machine. The unit of the 1443frequency is KHz. 1444 1445 14464.56 KVM_GET_TSC_KHZ 1447 1448Capability: KVM_CAP_GET_TSC_KHZ 1449Architectures: x86 1450Type: vcpu ioctl 1451Parameters: none 1452Returns: virtual tsc-khz on success, negative value on error 1453 1454Returns the tsc frequency of the guest. The unit of the return value is 1455KHz. If the host has unstable tsc this ioctl returns -EIO instead as an 1456error. 1457 1458 14594.57 KVM_GET_LAPIC 1460 1461Capability: KVM_CAP_IRQCHIP 1462Architectures: x86 1463Type: vcpu ioctl 1464Parameters: struct kvm_lapic_state (out) 1465Returns: 0 on success, -1 on error 1466 1467#define KVM_APIC_REG_SIZE 0x400 1468struct kvm_lapic_state { 1469 char regs[KVM_APIC_REG_SIZE]; 1470}; 1471 1472Reads the Local APIC registers and copies them into the input argument. The 1473data format and layout are the same as documented in the architecture manual. 1474 1475If KVM_X2APIC_API_USE_32BIT_IDS feature of KVM_CAP_X2APIC_API is 1476enabled, then the format of APIC_ID register depends on the APIC mode 1477(reported by MSR_IA32_APICBASE) of its VCPU. x2APIC stores APIC ID in 1478the APIC_ID register (bytes 32-35). xAPIC only allows an 8-bit APIC ID 1479which is stored in bits 31-24 of the APIC register, or equivalently in 1480byte 35 of struct kvm_lapic_state's regs field. KVM_GET_LAPIC must then 1481be called after MSR_IA32_APICBASE has been set with KVM_SET_MSR. 1482 1483If KVM_X2APIC_API_USE_32BIT_IDS feature is disabled, struct kvm_lapic_state 1484always uses xAPIC format. 1485 1486 14874.58 KVM_SET_LAPIC 1488 1489Capability: KVM_CAP_IRQCHIP 1490Architectures: x86 1491Type: vcpu ioctl 1492Parameters: struct kvm_lapic_state (in) 1493Returns: 0 on success, -1 on error 1494 1495#define KVM_APIC_REG_SIZE 0x400 1496struct kvm_lapic_state { 1497 char regs[KVM_APIC_REG_SIZE]; 1498}; 1499 1500Copies the input argument into the Local APIC registers. The data format 1501and layout are the same as documented in the architecture manual. 1502 1503The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's 1504regs field) depends on the state of the KVM_CAP_X2APIC_API capability. 1505See the note in KVM_GET_LAPIC. 1506 1507 15084.59 KVM_IOEVENTFD 1509 1510Capability: KVM_CAP_IOEVENTFD 1511Architectures: all 1512Type: vm ioctl 1513Parameters: struct kvm_ioeventfd (in) 1514Returns: 0 on success, !0 on error 1515 1516This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address 1517within the guest. A guest write in the registered address will signal the 1518provided event instead of triggering an exit. 1519 1520struct kvm_ioeventfd { 1521 __u64 datamatch; 1522 __u64 addr; /* legal pio/mmio address */ 1523 __u32 len; /* 0, 1, 2, 4, or 8 bytes */ 1524 __s32 fd; 1525 __u32 flags; 1526 __u8 pad[36]; 1527}; 1528 1529For the special case of virtio-ccw devices on s390, the ioevent is matched 1530to a subchannel/virtqueue tuple instead. 1531 1532The following flags are defined: 1533 1534#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch) 1535#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio) 1536#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign) 1537#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \ 1538 (1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify) 1539 1540If datamatch flag is set, the event will be signaled only if the written value 1541to the registered address is equal to datamatch in struct kvm_ioeventfd. 1542 1543For virtio-ccw devices, addr contains the subchannel id and datamatch the 1544virtqueue index. 1545 1546With KVM_CAP_IOEVENTFD_ANY_LENGTH, a zero length ioeventfd is allowed, and 1547the kernel will ignore the length of guest write and may get a faster vmexit. 1548The speedup may only apply to specific architectures, but the ioeventfd will 1549work anyway. 1550 15514.60 KVM_DIRTY_TLB 1552 1553Capability: KVM_CAP_SW_TLB 1554Architectures: ppc 1555Type: vcpu ioctl 1556Parameters: struct kvm_dirty_tlb (in) 1557Returns: 0 on success, -1 on error 1558 1559struct kvm_dirty_tlb { 1560 __u64 bitmap; 1561 __u32 num_dirty; 1562}; 1563 1564This must be called whenever userspace has changed an entry in the shared 1565TLB, prior to calling KVM_RUN on the associated vcpu. 1566 1567The "bitmap" field is the userspace address of an array. This array 1568consists of a number of bits, equal to the total number of TLB entries as 1569determined by the last successful call to KVM_CONFIG_TLB, rounded up to the 1570nearest multiple of 64. 1571 1572Each bit corresponds to one TLB entry, ordered the same as in the shared TLB 1573array. 1574 1575The array is little-endian: the bit 0 is the least significant bit of the 1576first byte, bit 8 is the least significant bit of the second byte, etc. 1577This avoids any complications with differing word sizes. 1578 1579The "num_dirty" field is a performance hint for KVM to determine whether it 1580should skip processing the bitmap and just invalidate everything. It must 1581be set to the number of set bits in the bitmap. 1582 1583 15844.62 KVM_CREATE_SPAPR_TCE 1585 1586Capability: KVM_CAP_SPAPR_TCE 1587Architectures: powerpc 1588Type: vm ioctl 1589Parameters: struct kvm_create_spapr_tce (in) 1590Returns: file descriptor for manipulating the created TCE table 1591 1592This creates a virtual TCE (translation control entry) table, which 1593is an IOMMU for PAPR-style virtual I/O. It is used to translate 1594logical addresses used in virtual I/O into guest physical addresses, 1595and provides a scatter/gather capability for PAPR virtual I/O. 1596 1597/* for KVM_CAP_SPAPR_TCE */ 1598struct kvm_create_spapr_tce { 1599 __u64 liobn; 1600 __u32 window_size; 1601}; 1602 1603The liobn field gives the logical IO bus number for which to create a 1604TCE table. The window_size field specifies the size of the DMA window 1605which this TCE table will translate - the table will contain one 64 1606bit TCE entry for every 4kiB of the DMA window. 1607 1608When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE 1609table has been created using this ioctl(), the kernel will handle it 1610in real mode, updating the TCE table. H_PUT_TCE calls for other 1611liobns will cause a vm exit and must be handled by userspace. 1612 1613The return value is a file descriptor which can be passed to mmap(2) 1614to map the created TCE table into userspace. This lets userspace read 1615the entries written by kernel-handled H_PUT_TCE calls, and also lets 1616userspace update the TCE table directly which is useful in some 1617circumstances. 1618 1619 16204.63 KVM_ALLOCATE_RMA 1621 1622Capability: KVM_CAP_PPC_RMA 1623Architectures: powerpc 1624Type: vm ioctl 1625Parameters: struct kvm_allocate_rma (out) 1626Returns: file descriptor for mapping the allocated RMA 1627 1628This allocates a Real Mode Area (RMA) from the pool allocated at boot 1629time by the kernel. An RMA is a physically-contiguous, aligned region 1630of memory used on older POWER processors to provide the memory which 1631will be accessed by real-mode (MMU off) accesses in a KVM guest. 1632POWER processors support a set of sizes for the RMA that usually 1633includes 64MB, 128MB, 256MB and some larger powers of two. 1634 1635/* for KVM_ALLOCATE_RMA */ 1636struct kvm_allocate_rma { 1637 __u64 rma_size; 1638}; 1639 1640The return value is a file descriptor which can be passed to mmap(2) 1641to map the allocated RMA into userspace. The mapped area can then be 1642passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the 1643RMA for a virtual machine. The size of the RMA in bytes (which is 1644fixed at host kernel boot time) is returned in the rma_size field of 1645the argument structure. 1646 1647The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl 1648is supported; 2 if the processor requires all virtual machines to have 1649an RMA, or 1 if the processor can use an RMA but doesn't require it, 1650because it supports the Virtual RMA (VRMA) facility. 1651 1652 16534.64 KVM_NMI 1654 1655Capability: KVM_CAP_USER_NMI 1656Architectures: x86 1657Type: vcpu ioctl 1658Parameters: none 1659Returns: 0 on success, -1 on error 1660 1661Queues an NMI on the thread's vcpu. Note this is well defined only 1662when KVM_CREATE_IRQCHIP has not been called, since this is an interface 1663between the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIP 1664has been called, this interface is completely emulated within the kernel. 1665 1666To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the 1667following algorithm: 1668 1669 - pause the vcpu 1670 - read the local APIC's state (KVM_GET_LAPIC) 1671 - check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1) 1672 - if so, issue KVM_NMI 1673 - resume the vcpu 1674 1675Some guests configure the LINT1 NMI input to cause a panic, aiding in 1676debugging. 1677 1678 16794.65 KVM_S390_UCAS_MAP 1680 1681Capability: KVM_CAP_S390_UCONTROL 1682Architectures: s390 1683Type: vcpu ioctl 1684Parameters: struct kvm_s390_ucas_mapping (in) 1685Returns: 0 in case of success 1686 1687The parameter is defined like this: 1688 struct kvm_s390_ucas_mapping { 1689 __u64 user_addr; 1690 __u64 vcpu_addr; 1691 __u64 length; 1692 }; 1693 1694This ioctl maps the memory at "user_addr" with the length "length" to 1695the vcpu's address space starting at "vcpu_addr". All parameters need to 1696be aligned by 1 megabyte. 1697 1698 16994.66 KVM_S390_UCAS_UNMAP 1700 1701Capability: KVM_CAP_S390_UCONTROL 1702Architectures: s390 1703Type: vcpu ioctl 1704Parameters: struct kvm_s390_ucas_mapping (in) 1705Returns: 0 in case of success 1706 1707The parameter is defined like this: 1708 struct kvm_s390_ucas_mapping { 1709 __u64 user_addr; 1710 __u64 vcpu_addr; 1711 __u64 length; 1712 }; 1713 1714This ioctl unmaps the memory in the vcpu's address space starting at 1715"vcpu_addr" with the length "length". The field "user_addr" is ignored. 1716All parameters need to be aligned by 1 megabyte. 1717 1718 17194.67 KVM_S390_VCPU_FAULT 1720 1721Capability: KVM_CAP_S390_UCONTROL 1722Architectures: s390 1723Type: vcpu ioctl 1724Parameters: vcpu absolute address (in) 1725Returns: 0 in case of success 1726 1727This call creates a page table entry on the virtual cpu's address space 1728(for user controlled virtual machines) or the virtual machine's address 1729space (for regular virtual machines). This only works for minor faults, 1730thus it's recommended to access subject memory page via the user page 1731table upfront. This is useful to handle validity intercepts for user 1732controlled virtual machines to fault in the virtual cpu's lowcore pages 1733prior to calling the KVM_RUN ioctl. 1734 1735 17364.68 KVM_SET_ONE_REG 1737 1738Capability: KVM_CAP_ONE_REG 1739Architectures: all 1740Type: vcpu ioctl 1741Parameters: struct kvm_one_reg (in) 1742Returns: 0 on success, negative value on failure 1743 1744struct kvm_one_reg { 1745 __u64 id; 1746 __u64 addr; 1747}; 1748 1749Using this ioctl, a single vcpu register can be set to a specific value 1750defined by user space with the passed in struct kvm_one_reg, where id 1751refers to the register identifier as described below and addr is a pointer 1752to a variable with the respective size. There can be architecture agnostic 1753and architecture specific registers. Each have their own range of operation 1754and their own constants and width. To keep track of the implemented 1755registers, find a list below: 1756 1757 Arch | Register | Width (bits) 1758 | | 1759 PPC | KVM_REG_PPC_HIOR | 64 1760 PPC | KVM_REG_PPC_IAC1 | 64 1761 PPC | KVM_REG_PPC_IAC2 | 64 1762 PPC | KVM_REG_PPC_IAC3 | 64 1763 PPC | KVM_REG_PPC_IAC4 | 64 1764 PPC | KVM_REG_PPC_DAC1 | 64 1765 PPC | KVM_REG_PPC_DAC2 | 64 1766 PPC | KVM_REG_PPC_DABR | 64 1767 PPC | KVM_REG_PPC_DSCR | 64 1768 PPC | KVM_REG_PPC_PURR | 64 1769 PPC | KVM_REG_PPC_SPURR | 64 1770 PPC | KVM_REG_PPC_DAR | 64 1771 PPC | KVM_REG_PPC_DSISR | 32 1772 PPC | KVM_REG_PPC_AMR | 64 1773 PPC | KVM_REG_PPC_UAMOR | 64 1774 PPC | KVM_REG_PPC_MMCR0 | 64 1775 PPC | KVM_REG_PPC_MMCR1 | 64 1776 PPC | KVM_REG_PPC_MMCRA | 64 1777 PPC | KVM_REG_PPC_MMCR2 | 64 1778 PPC | KVM_REG_PPC_MMCRS | 64 1779 PPC | KVM_REG_PPC_SIAR | 64 1780 PPC | KVM_REG_PPC_SDAR | 64 1781 PPC | KVM_REG_PPC_SIER | 64 1782 PPC | KVM_REG_PPC_PMC1 | 32 1783 PPC | KVM_REG_PPC_PMC2 | 32 1784 PPC | KVM_REG_PPC_PMC3 | 32 1785 PPC | KVM_REG_PPC_PMC4 | 32 1786 PPC | KVM_REG_PPC_PMC5 | 32 1787 PPC | KVM_REG_PPC_PMC6 | 32 1788 PPC | KVM_REG_PPC_PMC7 | 32 1789 PPC | KVM_REG_PPC_PMC8 | 32 1790 PPC | KVM_REG_PPC_FPR0 | 64 1791 ... 1792 PPC | KVM_REG_PPC_FPR31 | 64 1793 PPC | KVM_REG_PPC_VR0 | 128 1794 ... 1795 PPC | KVM_REG_PPC_VR31 | 128 1796 PPC | KVM_REG_PPC_VSR0 | 128 1797 ... 1798 PPC | KVM_REG_PPC_VSR31 | 128 1799 PPC | KVM_REG_PPC_FPSCR | 64 1800 PPC | KVM_REG_PPC_VSCR | 32 1801 PPC | KVM_REG_PPC_VPA_ADDR | 64 1802 PPC | KVM_REG_PPC_VPA_SLB | 128 1803 PPC | KVM_REG_PPC_VPA_DTL | 128 1804 PPC | KVM_REG_PPC_EPCR | 32 1805 PPC | KVM_REG_PPC_EPR | 32 1806 PPC | KVM_REG_PPC_TCR | 32 1807 PPC | KVM_REG_PPC_TSR | 32 1808 PPC | KVM_REG_PPC_OR_TSR | 32 1809 PPC | KVM_REG_PPC_CLEAR_TSR | 32 1810 PPC | KVM_REG_PPC_MAS0 | 32 1811 PPC | KVM_REG_PPC_MAS1 | 32 1812 PPC | KVM_REG_PPC_MAS2 | 64 1813 PPC | KVM_REG_PPC_MAS7_3 | 64 1814 PPC | KVM_REG_PPC_MAS4 | 32 1815 PPC | KVM_REG_PPC_MAS6 | 32 1816 PPC | KVM_REG_PPC_MMUCFG | 32 1817 PPC | KVM_REG_PPC_TLB0CFG | 32 1818 PPC | KVM_REG_PPC_TLB1CFG | 32 1819 PPC | KVM_REG_PPC_TLB2CFG | 32 1820 PPC | KVM_REG_PPC_TLB3CFG | 32 1821 PPC | KVM_REG_PPC_TLB0PS | 32 1822 PPC | KVM_REG_PPC_TLB1PS | 32 1823 PPC | KVM_REG_PPC_TLB2PS | 32 1824 PPC | KVM_REG_PPC_TLB3PS | 32 1825 PPC | KVM_REG_PPC_EPTCFG | 32 1826 PPC | KVM_REG_PPC_ICP_STATE | 64 1827 PPC | KVM_REG_PPC_TB_OFFSET | 64 1828 PPC | KVM_REG_PPC_SPMC1 | 32 1829 PPC | KVM_REG_PPC_SPMC2 | 32 1830 PPC | KVM_REG_PPC_IAMR | 64 1831 PPC | KVM_REG_PPC_TFHAR | 64 1832 PPC | KVM_REG_PPC_TFIAR | 64 1833 PPC | KVM_REG_PPC_TEXASR | 64 1834 PPC | KVM_REG_PPC_FSCR | 64 1835 PPC | KVM_REG_PPC_PSPB | 32 1836 PPC | KVM_REG_PPC_EBBHR | 64 1837 PPC | KVM_REG_PPC_EBBRR | 64 1838 PPC | KVM_REG_PPC_BESCR | 64 1839 PPC | KVM_REG_PPC_TAR | 64 1840 PPC | KVM_REG_PPC_DPDES | 64 1841 PPC | KVM_REG_PPC_DAWR | 64 1842 PPC | KVM_REG_PPC_DAWRX | 64 1843 PPC | KVM_REG_PPC_CIABR | 64 1844 PPC | KVM_REG_PPC_IC | 64 1845 PPC | KVM_REG_PPC_VTB | 64 1846 PPC | KVM_REG_PPC_CSIGR | 64 1847 PPC | KVM_REG_PPC_TACR | 64 1848 PPC | KVM_REG_PPC_TCSCR | 64 1849 PPC | KVM_REG_PPC_PID | 64 1850 PPC | KVM_REG_PPC_ACOP | 64 1851 PPC | KVM_REG_PPC_VRSAVE | 32 1852 PPC | KVM_REG_PPC_LPCR | 32 1853 PPC | KVM_REG_PPC_LPCR_64 | 64 1854 PPC | KVM_REG_PPC_PPR | 64 1855 PPC | KVM_REG_PPC_ARCH_COMPAT | 32 1856 PPC | KVM_REG_PPC_DABRX | 32 1857 PPC | KVM_REG_PPC_WORT | 64 1858 PPC | KVM_REG_PPC_SPRG9 | 64 1859 PPC | KVM_REG_PPC_DBSR | 32 1860 PPC | KVM_REG_PPC_TIDR | 64 1861 PPC | KVM_REG_PPC_PSSCR | 64 1862 PPC | KVM_REG_PPC_DEC_EXPIRY | 64 1863 PPC | KVM_REG_PPC_TM_GPR0 | 64 1864 ... 1865 PPC | KVM_REG_PPC_TM_GPR31 | 64 1866 PPC | KVM_REG_PPC_TM_VSR0 | 128 1867 ... 1868 PPC | KVM_REG_PPC_TM_VSR63 | 128 1869 PPC | KVM_REG_PPC_TM_CR | 64 1870 PPC | KVM_REG_PPC_TM_LR | 64 1871 PPC | KVM_REG_PPC_TM_CTR | 64 1872 PPC | KVM_REG_PPC_TM_FPSCR | 64 1873 PPC | KVM_REG_PPC_TM_AMR | 64 1874 PPC | KVM_REG_PPC_TM_PPR | 64 1875 PPC | KVM_REG_PPC_TM_VRSAVE | 64 1876 PPC | KVM_REG_PPC_TM_VSCR | 32 1877 PPC | KVM_REG_PPC_TM_DSCR | 64 1878 PPC | KVM_REG_PPC_TM_TAR | 64 1879 PPC | KVM_REG_PPC_TM_XER | 64 1880 | | 1881 MIPS | KVM_REG_MIPS_R0 | 64 1882 ... 1883 MIPS | KVM_REG_MIPS_R31 | 64 1884 MIPS | KVM_REG_MIPS_HI | 64 1885 MIPS | KVM_REG_MIPS_LO | 64 1886 MIPS | KVM_REG_MIPS_PC | 64 1887 MIPS | KVM_REG_MIPS_CP0_INDEX | 32 1888 MIPS | KVM_REG_MIPS_CP0_ENTRYLO0 | 64 1889 MIPS | KVM_REG_MIPS_CP0_ENTRYLO1 | 64 1890 MIPS | KVM_REG_MIPS_CP0_CONTEXT | 64 1891 MIPS | KVM_REG_MIPS_CP0_CONTEXTCONFIG| 32 1892 MIPS | KVM_REG_MIPS_CP0_USERLOCAL | 64 1893 MIPS | KVM_REG_MIPS_CP0_XCONTEXTCONFIG| 64 1894 MIPS | KVM_REG_MIPS_CP0_PAGEMASK | 32 1895 MIPS | KVM_REG_MIPS_CP0_PAGEGRAIN | 32 1896 MIPS | KVM_REG_MIPS_CP0_SEGCTL0 | 64 1897 MIPS | KVM_REG_MIPS_CP0_SEGCTL1 | 64 1898 MIPS | KVM_REG_MIPS_CP0_SEGCTL2 | 64 1899 MIPS | KVM_REG_MIPS_CP0_PWBASE | 64 1900 MIPS | KVM_REG_MIPS_CP0_PWFIELD | 64 1901 MIPS | KVM_REG_MIPS_CP0_PWSIZE | 64 1902 MIPS | KVM_REG_MIPS_CP0_WIRED | 32 1903 MIPS | KVM_REG_MIPS_CP0_PWCTL | 32 1904 MIPS | KVM_REG_MIPS_CP0_HWRENA | 32 1905 MIPS | KVM_REG_MIPS_CP0_BADVADDR | 64 1906 MIPS | KVM_REG_MIPS_CP0_BADINSTR | 32 1907 MIPS | KVM_REG_MIPS_CP0_BADINSTRP | 32 1908 MIPS | KVM_REG_MIPS_CP0_COUNT | 32 1909 MIPS | KVM_REG_MIPS_CP0_ENTRYHI | 64 1910 MIPS | KVM_REG_MIPS_CP0_COMPARE | 32 1911 MIPS | KVM_REG_MIPS_CP0_STATUS | 32 1912 MIPS | KVM_REG_MIPS_CP0_INTCTL | 32 1913 MIPS | KVM_REG_MIPS_CP0_CAUSE | 32 1914 MIPS | KVM_REG_MIPS_CP0_EPC | 64 1915 MIPS | KVM_REG_MIPS_CP0_PRID | 32 1916 MIPS | KVM_REG_MIPS_CP0_EBASE | 64 1917 MIPS | KVM_REG_MIPS_CP0_CONFIG | 32 1918 MIPS | KVM_REG_MIPS_CP0_CONFIG1 | 32 1919 MIPS | KVM_REG_MIPS_CP0_CONFIG2 | 32 1920 MIPS | KVM_REG_MIPS_CP0_CONFIG3 | 32 1921 MIPS | KVM_REG_MIPS_CP0_CONFIG4 | 32 1922 MIPS | KVM_REG_MIPS_CP0_CONFIG5 | 32 1923 MIPS | KVM_REG_MIPS_CP0_CONFIG7 | 32 1924 MIPS | KVM_REG_MIPS_CP0_XCONTEXT | 64 1925 MIPS | KVM_REG_MIPS_CP0_ERROREPC | 64 1926 MIPS | KVM_REG_MIPS_CP0_KSCRATCH1 | 64 1927 MIPS | KVM_REG_MIPS_CP0_KSCRATCH2 | 64 1928 MIPS | KVM_REG_MIPS_CP0_KSCRATCH3 | 64 1929 MIPS | KVM_REG_MIPS_CP0_KSCRATCH4 | 64 1930 MIPS | KVM_REG_MIPS_CP0_KSCRATCH5 | 64 1931 MIPS | KVM_REG_MIPS_CP0_KSCRATCH6 | 64 1932 MIPS | KVM_REG_MIPS_CP0_MAAR(0..63) | 64 1933 MIPS | KVM_REG_MIPS_COUNT_CTL | 64 1934 MIPS | KVM_REG_MIPS_COUNT_RESUME | 64 1935 MIPS | KVM_REG_MIPS_COUNT_HZ | 64 1936 MIPS | KVM_REG_MIPS_FPR_32(0..31) | 32 1937 MIPS | KVM_REG_MIPS_FPR_64(0..31) | 64 1938 MIPS | KVM_REG_MIPS_VEC_128(0..31) | 128 1939 MIPS | KVM_REG_MIPS_FCR_IR | 32 1940 MIPS | KVM_REG_MIPS_FCR_CSR | 32 1941 MIPS | KVM_REG_MIPS_MSA_IR | 32 1942 MIPS | KVM_REG_MIPS_MSA_CSR | 32 1943 1944ARM registers are mapped using the lower 32 bits. The upper 16 of that 1945is the register group type, or coprocessor number: 1946 1947ARM core registers have the following id bit patterns: 1948 0x4020 0000 0010 <index into the kvm_regs struct:16> 1949 1950ARM 32-bit CP15 registers have the following id bit patterns: 1951 0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3> 1952 1953ARM 64-bit CP15 registers have the following id bit patterns: 1954 0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3> 1955 1956ARM CCSIDR registers are demultiplexed by CSSELR value: 1957 0x4020 0000 0011 00 <csselr:8> 1958 1959ARM 32-bit VFP control registers have the following id bit patterns: 1960 0x4020 0000 0012 1 <regno:12> 1961 1962ARM 64-bit FP registers have the following id bit patterns: 1963 0x4030 0000 0012 0 <regno:12> 1964 1965ARM firmware pseudo-registers have the following bit pattern: 1966 0x4030 0000 0014 <regno:16> 1967 1968 1969arm64 registers are mapped using the lower 32 bits. The upper 16 of 1970that is the register group type, or coprocessor number: 1971 1972arm64 core/FP-SIMD registers have the following id bit patterns. Note 1973that the size of the access is variable, as the kvm_regs structure 1974contains elements ranging from 32 to 128 bits. The index is a 32bit 1975value in the kvm_regs structure seen as a 32bit array. 1976 0x60x0 0000 0010 <index into the kvm_regs struct:16> 1977 1978arm64 CCSIDR registers are demultiplexed by CSSELR value: 1979 0x6020 0000 0011 00 <csselr:8> 1980 1981arm64 system registers have the following id bit patterns: 1982 0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3> 1983 1984arm64 firmware pseudo-registers have the following bit pattern: 1985 0x6030 0000 0014 <regno:16> 1986 1987 1988MIPS registers are mapped using the lower 32 bits. The upper 16 of that is 1989the register group type: 1990 1991MIPS core registers (see above) have the following id bit patterns: 1992 0x7030 0000 0000 <reg:16> 1993 1994MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit 1995patterns depending on whether they're 32-bit or 64-bit registers: 1996 0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit) 1997 0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit) 1998 1999Note: KVM_REG_MIPS_CP0_ENTRYLO0 and KVM_REG_MIPS_CP0_ENTRYLO1 are the MIPS64 2000versions of the EntryLo registers regardless of the word size of the host 2001hardware, host kernel, guest, and whether XPA is present in the guest, i.e. 2002with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and 2003the PFNX field starting at bit 30. 2004 2005MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit 2006patterns: 2007 0x7030 0000 0001 01 <reg:8> 2008 2009MIPS KVM control registers (see above) have the following id bit patterns: 2010 0x7030 0000 0002 <reg:16> 2011 2012MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following 2013id bit patterns depending on the size of the register being accessed. They are 2014always accessed according to the current guest FPU mode (Status.FR and 2015Config5.FRE), i.e. as the guest would see them, and they become unpredictable 2016if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector 2017registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they 2018overlap the FPU registers: 2019 0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers) 2020 0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers) 2021 0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers) 2022 2023MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the 2024following id bit patterns: 2025 0x7020 0000 0003 01 <0:3> <reg:5> 2026 2027MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the 2028following id bit patterns: 2029 0x7020 0000 0003 02 <0:3> <reg:5> 2030 2031 20324.69 KVM_GET_ONE_REG 2033 2034Capability: KVM_CAP_ONE_REG 2035Architectures: all 2036Type: vcpu ioctl 2037Parameters: struct kvm_one_reg (in and out) 2038Returns: 0 on success, negative value on failure 2039 2040This ioctl allows to receive the value of a single register implemented 2041in a vcpu. The register to read is indicated by the "id" field of the 2042kvm_one_reg struct passed in. On success, the register value can be found 2043at the memory location pointed to by "addr". 2044 2045The list of registers accessible using this interface is identical to the 2046list in 4.68. 2047 2048 20494.70 KVM_KVMCLOCK_CTRL 2050 2051Capability: KVM_CAP_KVMCLOCK_CTRL 2052Architectures: Any that implement pvclocks (currently x86 only) 2053Type: vcpu ioctl 2054Parameters: None 2055Returns: 0 on success, -1 on error 2056 2057This signals to the host kernel that the specified guest is being paused by 2058userspace. The host will set a flag in the pvclock structure that is checked 2059from the soft lockup watchdog. The flag is part of the pvclock structure that 2060is shared between guest and host, specifically the second bit of the flags 2061field of the pvclock_vcpu_time_info structure. It will be set exclusively by 2062the host and read/cleared exclusively by the guest. The guest operation of 2063checking and clearing the flag must an atomic operation so 2064load-link/store-conditional, or equivalent must be used. There are two cases 2065where the guest will clear the flag: when the soft lockup watchdog timer resets 2066itself or when a soft lockup is detected. This ioctl can be called any time 2067after pausing the vcpu, but before it is resumed. 2068 2069 20704.71 KVM_SIGNAL_MSI 2071 2072Capability: KVM_CAP_SIGNAL_MSI 2073Architectures: x86 arm arm64 2074Type: vm ioctl 2075Parameters: struct kvm_msi (in) 2076Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error 2077 2078Directly inject a MSI message. Only valid with in-kernel irqchip that handles 2079MSI messages. 2080 2081struct kvm_msi { 2082 __u32 address_lo; 2083 __u32 address_hi; 2084 __u32 data; 2085 __u32 flags; 2086 __u32 devid; 2087 __u8 pad[12]; 2088}; 2089 2090flags: KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM 2091 KVM_CAP_MSI_DEVID capability advertises the requirement to provide 2092 the device ID. If this capability is not available, userspace 2093 should never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail. 2094 2095If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier 2096for the device that wrote the MSI message. For PCI, this is usually a 2097BFD identifier in the lower 16 bits. 2098 2099On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS 2100feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled, 2101address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of 2102address_hi must be zero. 2103 2104 21054.71 KVM_CREATE_PIT2 2106 2107Capability: KVM_CAP_PIT2 2108Architectures: x86 2109Type: vm ioctl 2110Parameters: struct kvm_pit_config (in) 2111Returns: 0 on success, -1 on error 2112 2113Creates an in-kernel device model for the i8254 PIT. This call is only valid 2114after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following 2115parameters have to be passed: 2116 2117struct kvm_pit_config { 2118 __u32 flags; 2119 __u32 pad[15]; 2120}; 2121 2122Valid flags are: 2123 2124#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */ 2125 2126PIT timer interrupts may use a per-VM kernel thread for injection. If it 2127exists, this thread will have a name of the following pattern: 2128 2129kvm-pit/<owner-process-pid> 2130 2131When running a guest with elevated priorities, the scheduling parameters of 2132this thread may have to be adjusted accordingly. 2133 2134This IOCTL replaces the obsolete KVM_CREATE_PIT. 2135 2136 21374.72 KVM_GET_PIT2 2138 2139Capability: KVM_CAP_PIT_STATE2 2140Architectures: x86 2141Type: vm ioctl 2142Parameters: struct kvm_pit_state2 (out) 2143Returns: 0 on success, -1 on error 2144 2145Retrieves the state of the in-kernel PIT model. Only valid after 2146KVM_CREATE_PIT2. The state is returned in the following structure: 2147 2148struct kvm_pit_state2 { 2149 struct kvm_pit_channel_state channels[3]; 2150 __u32 flags; 2151 __u32 reserved[9]; 2152}; 2153 2154Valid flags are: 2155 2156/* disable PIT in HPET legacy mode */ 2157#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001 2158 2159This IOCTL replaces the obsolete KVM_GET_PIT. 2160 2161 21624.73 KVM_SET_PIT2 2163 2164Capability: KVM_CAP_PIT_STATE2 2165Architectures: x86 2166Type: vm ioctl 2167Parameters: struct kvm_pit_state2 (in) 2168Returns: 0 on success, -1 on error 2169 2170Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2. 2171See KVM_GET_PIT2 for details on struct kvm_pit_state2. 2172 2173This IOCTL replaces the obsolete KVM_SET_PIT. 2174 2175 21764.74 KVM_PPC_GET_SMMU_INFO 2177 2178Capability: KVM_CAP_PPC_GET_SMMU_INFO 2179Architectures: powerpc 2180Type: vm ioctl 2181Parameters: None 2182Returns: 0 on success, -1 on error 2183 2184This populates and returns a structure describing the features of 2185the "Server" class MMU emulation supported by KVM. 2186This can in turn be used by userspace to generate the appropriate 2187device-tree properties for the guest operating system. 2188 2189The structure contains some global information, followed by an 2190array of supported segment page sizes: 2191 2192 struct kvm_ppc_smmu_info { 2193 __u64 flags; 2194 __u32 slb_size; 2195 __u32 pad; 2196 struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ]; 2197 }; 2198 2199The supported flags are: 2200 2201 - KVM_PPC_PAGE_SIZES_REAL: 2202 When that flag is set, guest page sizes must "fit" the backing 2203 store page sizes. When not set, any page size in the list can 2204 be used regardless of how they are backed by userspace. 2205 2206 - KVM_PPC_1T_SEGMENTS 2207 The emulated MMU supports 1T segments in addition to the 2208 standard 256M ones. 2209 2210The "slb_size" field indicates how many SLB entries are supported 2211 2212The "sps" array contains 8 entries indicating the supported base 2213page sizes for a segment in increasing order. Each entry is defined 2214as follow: 2215 2216 struct kvm_ppc_one_seg_page_size { 2217 __u32 page_shift; /* Base page shift of segment (or 0) */ 2218 __u32 slb_enc; /* SLB encoding for BookS */ 2219 struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ]; 2220 }; 2221 2222An entry with a "page_shift" of 0 is unused. Because the array is 2223organized in increasing order, a lookup can stop when encoutering 2224such an entry. 2225 2226The "slb_enc" field provides the encoding to use in the SLB for the 2227page size. The bits are in positions such as the value can directly 2228be OR'ed into the "vsid" argument of the slbmte instruction. 2229 2230The "enc" array is a list which for each of those segment base page 2231size provides the list of supported actual page sizes (which can be 2232only larger or equal to the base page size), along with the 2233corresponding encoding in the hash PTE. Similarly, the array is 22348 entries sorted by increasing sizes and an entry with a "0" shift 2235is an empty entry and a terminator: 2236 2237 struct kvm_ppc_one_page_size { 2238 __u32 page_shift; /* Page shift (or 0) */ 2239 __u32 pte_enc; /* Encoding in the HPTE (>>12) */ 2240 }; 2241 2242The "pte_enc" field provides a value that can OR'ed into the hash 2243PTE's RPN field (ie, it needs to be shifted left by 12 to OR it 2244into the hash PTE second double word). 2245 22464.75 KVM_IRQFD 2247 2248Capability: KVM_CAP_IRQFD 2249Architectures: x86 s390 arm arm64 2250Type: vm ioctl 2251Parameters: struct kvm_irqfd (in) 2252Returns: 0 on success, -1 on error 2253 2254Allows setting an eventfd to directly trigger a guest interrupt. 2255kvm_irqfd.fd specifies the file descriptor to use as the eventfd and 2256kvm_irqfd.gsi specifies the irqchip pin toggled by this event. When 2257an event is triggered on the eventfd, an interrupt is injected into 2258the guest using the specified gsi pin. The irqfd is removed using 2259the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd 2260and kvm_irqfd.gsi. 2261 2262With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify 2263mechanism allowing emulation of level-triggered, irqfd-based 2264interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an 2265additional eventfd in the kvm_irqfd.resamplefd field. When operating 2266in resample mode, posting of an interrupt through kvm_irq.fd asserts 2267the specified gsi in the irqchip. When the irqchip is resampled, such 2268as from an EOI, the gsi is de-asserted and the user is notified via 2269kvm_irqfd.resamplefd. It is the user's responsibility to re-queue 2270the interrupt if the device making use of it still requires service. 2271Note that closing the resamplefd is not sufficient to disable the 2272irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment 2273and need not be specified with KVM_IRQFD_FLAG_DEASSIGN. 2274 2275On arm/arm64, gsi routing being supported, the following can happen: 2276- in case no routing entry is associated to this gsi, injection fails 2277- in case the gsi is associated to an irqchip routing entry, 2278 irqchip.pin + 32 corresponds to the injected SPI ID. 2279- in case the gsi is associated to an MSI routing entry, the MSI 2280 message and device ID are translated into an LPI (support restricted 2281 to GICv3 ITS in-kernel emulation). 2282 22834.76 KVM_PPC_ALLOCATE_HTAB 2284 2285Capability: KVM_CAP_PPC_ALLOC_HTAB 2286Architectures: powerpc 2287Type: vm ioctl 2288Parameters: Pointer to u32 containing hash table order (in/out) 2289Returns: 0 on success, -1 on error 2290 2291This requests the host kernel to allocate an MMU hash table for a 2292guest using the PAPR paravirtualization interface. This only does 2293anything if the kernel is configured to use the Book 3S HV style of 2294virtualization. Otherwise the capability doesn't exist and the ioctl 2295returns an ENOTTY error. The rest of this description assumes Book 3S 2296HV. 2297 2298There must be no vcpus running when this ioctl is called; if there 2299are, it will do nothing and return an EBUSY error. 2300 2301The parameter is a pointer to a 32-bit unsigned integer variable 2302containing the order (log base 2) of the desired size of the hash 2303table, which must be between 18 and 46. On successful return from the 2304ioctl, the value will not be changed by the kernel. 2305 2306If no hash table has been allocated when any vcpu is asked to run 2307(with the KVM_RUN ioctl), the host kernel will allocate a 2308default-sized hash table (16 MB). 2309 2310If this ioctl is called when a hash table has already been allocated, 2311with a different order from the existing hash table, the existing hash 2312table will be freed and a new one allocated. If this is ioctl is 2313called when a hash table has already been allocated of the same order 2314as specified, the kernel will clear out the existing hash table (zero 2315all HPTEs). In either case, if the guest is using the virtualized 2316real-mode area (VRMA) facility, the kernel will re-create the VMRA 2317HPTEs on the next KVM_RUN of any vcpu. 2318 23194.77 KVM_S390_INTERRUPT 2320 2321Capability: basic 2322Architectures: s390 2323Type: vm ioctl, vcpu ioctl 2324Parameters: struct kvm_s390_interrupt (in) 2325Returns: 0 on success, -1 on error 2326 2327Allows to inject an interrupt to the guest. Interrupts can be floating 2328(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type. 2329 2330Interrupt parameters are passed via kvm_s390_interrupt: 2331 2332struct kvm_s390_interrupt { 2333 __u32 type; 2334 __u32 parm; 2335 __u64 parm64; 2336}; 2337 2338type can be one of the following: 2339 2340KVM_S390_SIGP_STOP (vcpu) - sigp stop; optional flags in parm 2341KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm 2342KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm 2343KVM_S390_RESTART (vcpu) - restart 2344KVM_S390_INT_CLOCK_COMP (vcpu) - clock comparator interrupt 2345KVM_S390_INT_CPU_TIMER (vcpu) - CPU timer interrupt 2346KVM_S390_INT_VIRTIO (vm) - virtio external interrupt; external interrupt 2347 parameters in parm and parm64 2348KVM_S390_INT_SERVICE (vm) - sclp external interrupt; sclp parameter in parm 2349KVM_S390_INT_EMERGENCY (vcpu) - sigp emergency; source cpu in parm 2350KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm 2351KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm) - compound value to indicate an 2352 I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel); 2353 I/O interruption parameters in parm (subchannel) and parm64 (intparm, 2354 interruption subclass) 2355KVM_S390_MCHK (vm, vcpu) - machine check interrupt; cr 14 bits in parm, 2356 machine check interrupt code in parm64 (note that 2357 machine checks needing further payload are not 2358 supported by this ioctl) 2359 2360Note that the vcpu ioctl is asynchronous to vcpu execution. 2361 23624.78 KVM_PPC_GET_HTAB_FD 2363 2364Capability: KVM_CAP_PPC_HTAB_FD 2365Architectures: powerpc 2366Type: vm ioctl 2367Parameters: Pointer to struct kvm_get_htab_fd (in) 2368Returns: file descriptor number (>= 0) on success, -1 on error 2369 2370This returns a file descriptor that can be used either to read out the 2371entries in the guest's hashed page table (HPT), or to write entries to 2372initialize the HPT. The returned fd can only be written to if the 2373KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and 2374can only be read if that bit is clear. The argument struct looks like 2375this: 2376 2377/* For KVM_PPC_GET_HTAB_FD */ 2378struct kvm_get_htab_fd { 2379 __u64 flags; 2380 __u64 start_index; 2381 __u64 reserved[2]; 2382}; 2383 2384/* Values for kvm_get_htab_fd.flags */ 2385#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1) 2386#define KVM_GET_HTAB_WRITE ((__u64)0x2) 2387 2388The `start_index' field gives the index in the HPT of the entry at 2389which to start reading. It is ignored when writing. 2390 2391Reads on the fd will initially supply information about all 2392"interesting" HPT entries. Interesting entries are those with the 2393bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise 2394all entries. When the end of the HPT is reached, the read() will 2395return. If read() is called again on the fd, it will start again from 2396the beginning of the HPT, but will only return HPT entries that have 2397changed since they were last read. 2398 2399Data read or written is structured as a header (8 bytes) followed by a 2400series of valid HPT entries (16 bytes) each. The header indicates how 2401many valid HPT entries there are and how many invalid entries follow 2402the valid entries. The invalid entries are not represented explicitly 2403in the stream. The header format is: 2404 2405struct kvm_get_htab_header { 2406 __u32 index; 2407 __u16 n_valid; 2408 __u16 n_invalid; 2409}; 2410 2411Writes to the fd create HPT entries starting at the index given in the 2412header; first `n_valid' valid entries with contents from the data 2413written, then `n_invalid' invalid entries, invalidating any previously 2414valid entries found. 2415 24164.79 KVM_CREATE_DEVICE 2417 2418Capability: KVM_CAP_DEVICE_CTRL 2419Type: vm ioctl 2420Parameters: struct kvm_create_device (in/out) 2421Returns: 0 on success, -1 on error 2422Errors: 2423 ENODEV: The device type is unknown or unsupported 2424 EEXIST: Device already created, and this type of device may not 2425 be instantiated multiple times 2426 2427 Other error conditions may be defined by individual device types or 2428 have their standard meanings. 2429 2430Creates an emulated device in the kernel. The file descriptor returned 2431in fd can be used with KVM_SET/GET/HAS_DEVICE_ATTR. 2432 2433If the KVM_CREATE_DEVICE_TEST flag is set, only test whether the 2434device type is supported (not necessarily whether it can be created 2435in the current vm). 2436 2437Individual devices should not define flags. Attributes should be used 2438for specifying any behavior that is not implied by the device type 2439number. 2440 2441struct kvm_create_device { 2442 __u32 type; /* in: KVM_DEV_TYPE_xxx */ 2443 __u32 fd; /* out: device handle */ 2444 __u32 flags; /* in: KVM_CREATE_DEVICE_xxx */ 2445}; 2446 24474.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR 2448 2449Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, 2450 KVM_CAP_VCPU_ATTRIBUTES for vcpu device 2451Type: device ioctl, vm ioctl, vcpu ioctl 2452Parameters: struct kvm_device_attr 2453Returns: 0 on success, -1 on error 2454Errors: 2455 ENXIO: The group or attribute is unknown/unsupported for this device 2456 or hardware support is missing. 2457 EPERM: The attribute cannot (currently) be accessed this way 2458 (e.g. read-only attribute, or attribute that only makes 2459 sense when the device is in a different state) 2460 2461 Other error conditions may be defined by individual device types. 2462 2463Gets/sets a specified piece of device configuration and/or state. The 2464semantics are device-specific. See individual device documentation in 2465the "devices" directory. As with ONE_REG, the size of the data 2466transferred is defined by the particular attribute. 2467 2468struct kvm_device_attr { 2469 __u32 flags; /* no flags currently defined */ 2470 __u32 group; /* device-defined */ 2471 __u64 attr; /* group-defined */ 2472 __u64 addr; /* userspace address of attr data */ 2473}; 2474 24754.81 KVM_HAS_DEVICE_ATTR 2476 2477Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device, 2478 KVM_CAP_VCPU_ATTRIBUTES for vcpu device 2479Type: device ioctl, vm ioctl, vcpu ioctl 2480Parameters: struct kvm_device_attr 2481Returns: 0 on success, -1 on error 2482Errors: 2483 ENXIO: The group or attribute is unknown/unsupported for this device 2484 or hardware support is missing. 2485 2486Tests whether a device supports a particular attribute. A successful 2487return indicates the attribute is implemented. It does not necessarily 2488indicate that the attribute can be read or written in the device's 2489current state. "addr" is ignored. 2490 24914.82 KVM_ARM_VCPU_INIT 2492 2493Capability: basic 2494Architectures: arm, arm64 2495Type: vcpu ioctl 2496Parameters: struct kvm_vcpu_init (in) 2497Returns: 0 on success; -1 on error 2498Errors: 2499 EINVAL: the target is unknown, or the combination of features is invalid. 2500 ENOENT: a features bit specified is unknown. 2501 2502This tells KVM what type of CPU to present to the guest, and what 2503optional features it should have. This will cause a reset of the cpu 2504registers to their initial values. If this is not called, KVM_RUN will 2505return ENOEXEC for that vcpu. 2506 2507Note that because some registers reflect machine topology, all vcpus 2508should be created before this ioctl is invoked. 2509 2510Userspace can call this function multiple times for a given vcpu, including 2511after the vcpu has been run. This will reset the vcpu to its initial 2512state. All calls to this function after the initial call must use the same 2513target and same set of feature flags, otherwise EINVAL will be returned. 2514 2515Possible features: 2516 - KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state. 2517 Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on 2518 and execute guest code when KVM_RUN is called. 2519 - KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode. 2520 Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only). 2521 - KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 (or a future revision 2522 backward compatible with v0.2) for the CPU. 2523 Depends on KVM_CAP_ARM_PSCI_0_2. 2524 - KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU. 2525 Depends on KVM_CAP_ARM_PMU_V3. 2526 2527 25284.83 KVM_ARM_PREFERRED_TARGET 2529 2530Capability: basic 2531Architectures: arm, arm64 2532Type: vm ioctl 2533Parameters: struct struct kvm_vcpu_init (out) 2534Returns: 0 on success; -1 on error 2535Errors: 2536 ENODEV: no preferred target available for the host 2537 2538This queries KVM for preferred CPU target type which can be emulated 2539by KVM on underlying host. 2540 2541The ioctl returns struct kvm_vcpu_init instance containing information 2542about preferred CPU target type and recommended features for it. The 2543kvm_vcpu_init->features bitmap returned will have feature bits set if 2544the preferred target recommends setting these features, but this is 2545not mandatory. 2546 2547The information returned by this ioctl can be used to prepare an instance 2548of struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result in 2549in VCPU matching underlying host. 2550 2551 25524.84 KVM_GET_REG_LIST 2553 2554Capability: basic 2555Architectures: arm, arm64, mips 2556Type: vcpu ioctl 2557Parameters: struct kvm_reg_list (in/out) 2558Returns: 0 on success; -1 on error 2559Errors: 2560 E2BIG: the reg index list is too big to fit in the array specified by 2561 the user (the number required will be written into n). 2562 2563struct kvm_reg_list { 2564 __u64 n; /* number of registers in reg[] */ 2565 __u64 reg[0]; 2566}; 2567 2568This ioctl returns the guest registers that are supported for the 2569KVM_GET_ONE_REG/KVM_SET_ONE_REG calls. 2570 2571 25724.85 KVM_ARM_SET_DEVICE_ADDR (deprecated) 2573 2574Capability: KVM_CAP_ARM_SET_DEVICE_ADDR 2575Architectures: arm, arm64 2576Type: vm ioctl 2577Parameters: struct kvm_arm_device_address (in) 2578Returns: 0 on success, -1 on error 2579Errors: 2580 ENODEV: The device id is unknown 2581 ENXIO: Device not supported on current system 2582 EEXIST: Address already set 2583 E2BIG: Address outside guest physical address space 2584 EBUSY: Address overlaps with other device range 2585 2586struct kvm_arm_device_addr { 2587 __u64 id; 2588 __u64 addr; 2589}; 2590 2591Specify a device address in the guest's physical address space where guests 2592can access emulated or directly exposed devices, which the host kernel needs 2593to know about. The id field is an architecture specific identifier for a 2594specific device. 2595 2596ARM/arm64 divides the id field into two parts, a device id and an 2597address type id specific to the individual device. 2598 2599 bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 | 2600 field: | 0x00000000 | device id | addr type id | 2601 2602ARM/arm64 currently only require this when using the in-kernel GIC 2603support for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2 2604as the device id. When setting the base address for the guest's 2605mapping of the VGIC virtual CPU and distributor interface, the ioctl 2606must be called after calling KVM_CREATE_IRQCHIP, but before calling 2607KVM_RUN on any of the VCPUs. Calling this ioctl twice for any of the 2608base addresses will return -EEXIST. 2609 2610Note, this IOCTL is deprecated and the more flexible SET/GET_DEVICE_ATTR API 2611should be used instead. 2612 2613 26144.86 KVM_PPC_RTAS_DEFINE_TOKEN 2615 2616Capability: KVM_CAP_PPC_RTAS 2617Architectures: ppc 2618Type: vm ioctl 2619Parameters: struct kvm_rtas_token_args 2620Returns: 0 on success, -1 on error 2621 2622Defines a token value for a RTAS (Run Time Abstraction Services) 2623service in order to allow it to be handled in the kernel. The 2624argument struct gives the name of the service, which must be the name 2625of a service that has a kernel-side implementation. If the token 2626value is non-zero, it will be associated with that service, and 2627subsequent RTAS calls by the guest specifying that token will be 2628handled by the kernel. If the token value is 0, then any token 2629associated with the service will be forgotten, and subsequent RTAS 2630calls by the guest for that service will be passed to userspace to be 2631handled. 2632 26334.87 KVM_SET_GUEST_DEBUG 2634 2635Capability: KVM_CAP_SET_GUEST_DEBUG 2636Architectures: x86, s390, ppc, arm64 2637Type: vcpu ioctl 2638Parameters: struct kvm_guest_debug (in) 2639Returns: 0 on success; -1 on error 2640 2641struct kvm_guest_debug { 2642 __u32 control; 2643 __u32 pad; 2644 struct kvm_guest_debug_arch arch; 2645}; 2646 2647Set up the processor specific debug registers and configure vcpu for 2648handling guest debug events. There are two parts to the structure, the 2649first a control bitfield indicates the type of debug events to handle 2650when running. Common control bits are: 2651 2652 - KVM_GUESTDBG_ENABLE: guest debugging is enabled 2653 - KVM_GUESTDBG_SINGLESTEP: the next run should single-step 2654 2655The top 16 bits of the control field are architecture specific control 2656flags which can include the following: 2657 2658 - KVM_GUESTDBG_USE_SW_BP: using software breakpoints [x86, arm64] 2659 - KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390, arm64] 2660 - KVM_GUESTDBG_INJECT_DB: inject DB type exception [x86] 2661 - KVM_GUESTDBG_INJECT_BP: inject BP type exception [x86] 2662 - KVM_GUESTDBG_EXIT_PENDING: trigger an immediate guest exit [s390] 2663 2664For example KVM_GUESTDBG_USE_SW_BP indicates that software breakpoints 2665are enabled in memory so we need to ensure breakpoint exceptions are 2666correctly trapped and the KVM run loop exits at the breakpoint and not 2667running off into the normal guest vector. For KVM_GUESTDBG_USE_HW_BP 2668we need to ensure the guest vCPUs architecture specific registers are 2669updated to the correct (supplied) values. 2670 2671The second part of the structure is architecture specific and 2672typically contains a set of debug registers. 2673 2674For arm64 the number of debug registers is implementation defined and 2675can be determined by querying the KVM_CAP_GUEST_DEBUG_HW_BPS and 2676KVM_CAP_GUEST_DEBUG_HW_WPS capabilities which return a positive number 2677indicating the number of supported registers. 2678 2679When debug events exit the main run loop with the reason 2680KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run 2681structure containing architecture specific debug information. 2682 26834.88 KVM_GET_EMULATED_CPUID 2684 2685Capability: KVM_CAP_EXT_EMUL_CPUID 2686Architectures: x86 2687Type: system ioctl 2688Parameters: struct kvm_cpuid2 (in/out) 2689Returns: 0 on success, -1 on error 2690 2691struct kvm_cpuid2 { 2692 __u32 nent; 2693 __u32 flags; 2694 struct kvm_cpuid_entry2 entries[0]; 2695}; 2696 2697The member 'flags' is used for passing flags from userspace. 2698 2699#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0) 2700#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1) 2701#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2) 2702 2703struct kvm_cpuid_entry2 { 2704 __u32 function; 2705 __u32 index; 2706 __u32 flags; 2707 __u32 eax; 2708 __u32 ebx; 2709 __u32 ecx; 2710 __u32 edx; 2711 __u32 padding[3]; 2712}; 2713 2714This ioctl returns x86 cpuid features which are emulated by 2715kvm.Userspace can use the information returned by this ioctl to query 2716which features are emulated by kvm instead of being present natively. 2717 2718Userspace invokes KVM_GET_EMULATED_CPUID by passing a kvm_cpuid2 2719structure with the 'nent' field indicating the number of entries in 2720the variable-size array 'entries'. If the number of entries is too low 2721to describe the cpu capabilities, an error (E2BIG) is returned. If the 2722number is too high, the 'nent' field is adjusted and an error (ENOMEM) 2723is returned. If the number is just right, the 'nent' field is adjusted 2724to the number of valid entries in the 'entries' array, which is then 2725filled. 2726 2727The entries returned are the set CPUID bits of the respective features 2728which kvm emulates, as returned by the CPUID instruction, with unknown 2729or unsupported feature bits cleared. 2730 2731Features like x2apic, for example, may not be present in the host cpu 2732but are exposed by kvm in KVM_GET_SUPPORTED_CPUID because they can be 2733emulated efficiently and thus not included here. 2734 2735The fields in each entry are defined as follows: 2736 2737 function: the eax value used to obtain the entry 2738 index: the ecx value used to obtain the entry (for entries that are 2739 affected by ecx) 2740 flags: an OR of zero or more of the following: 2741 KVM_CPUID_FLAG_SIGNIFCANT_INDEX: 2742 if the index field is valid 2743 KVM_CPUID_FLAG_STATEFUL_FUNC: 2744 if cpuid for this function returns different values for successive 2745 invocations; there will be several entries with the same function, 2746 all with this flag set 2747 KVM_CPUID_FLAG_STATE_READ_NEXT: 2748 for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is 2749 the first entry to be read by a cpu 2750 eax, ebx, ecx, edx: the values returned by the cpuid instruction for 2751 this function/index combination 2752 27534.89 KVM_S390_MEM_OP 2754 2755Capability: KVM_CAP_S390_MEM_OP 2756Architectures: s390 2757Type: vcpu ioctl 2758Parameters: struct kvm_s390_mem_op (in) 2759Returns: = 0 on success, 2760 < 0 on generic error (e.g. -EFAULT or -ENOMEM), 2761 > 0 if an exception occurred while walking the page tables 2762 2763Read or write data from/to the logical (virtual) memory of a VCPU. 2764 2765Parameters are specified via the following structure: 2766 2767struct kvm_s390_mem_op { 2768 __u64 gaddr; /* the guest address */ 2769 __u64 flags; /* flags */ 2770 __u32 size; /* amount of bytes */ 2771 __u32 op; /* type of operation */ 2772 __u64 buf; /* buffer in userspace */ 2773 __u8 ar; /* the access register number */ 2774 __u8 reserved[31]; /* should be set to 0 */ 2775}; 2776 2777The type of operation is specified in the "op" field. It is either 2778KVM_S390_MEMOP_LOGICAL_READ for reading from logical memory space or 2779KVM_S390_MEMOP_LOGICAL_WRITE for writing to logical memory space. The 2780KVM_S390_MEMOP_F_CHECK_ONLY flag can be set in the "flags" field to check 2781whether the corresponding memory access would create an access exception 2782(without touching the data in the memory at the destination). In case an 2783access exception occurred while walking the MMU tables of the guest, the 2784ioctl returns a positive error number to indicate the type of exception. 2785This exception is also raised directly at the corresponding VCPU if the 2786flag KVM_S390_MEMOP_F_INJECT_EXCEPTION is set in the "flags" field. 2787 2788The start address of the memory region has to be specified in the "gaddr" 2789field, and the length of the region in the "size" field. "buf" is the buffer 2790supplied by the userspace application where the read data should be written 2791to for KVM_S390_MEMOP_LOGICAL_READ, or where the data that should be written 2792is stored for a KVM_S390_MEMOP_LOGICAL_WRITE. "buf" is unused and can be NULL 2793when KVM_S390_MEMOP_F_CHECK_ONLY is specified. "ar" designates the access 2794register number to be used. 2795 2796The "reserved" field is meant for future extensions. It is not used by 2797KVM with the currently defined set of flags. 2798 27994.90 KVM_S390_GET_SKEYS 2800 2801Capability: KVM_CAP_S390_SKEYS 2802Architectures: s390 2803Type: vm ioctl 2804Parameters: struct kvm_s390_skeys 2805Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage 2806 keys, negative value on error 2807 2808This ioctl is used to get guest storage key values on the s390 2809architecture. The ioctl takes parameters via the kvm_s390_skeys struct. 2810 2811struct kvm_s390_skeys { 2812 __u64 start_gfn; 2813 __u64 count; 2814 __u64 skeydata_addr; 2815 __u32 flags; 2816 __u32 reserved[9]; 2817}; 2818 2819The start_gfn field is the number of the first guest frame whose storage keys 2820you want to get. 2821 2822The count field is the number of consecutive frames (starting from start_gfn) 2823whose storage keys to get. The count field must be at least 1 and the maximum 2824allowed value is defined as KVM_S390_SKEYS_ALLOC_MAX. Values outside this range 2825will cause the ioctl to return -EINVAL. 2826 2827The skeydata_addr field is the address to a buffer large enough to hold count 2828bytes. This buffer will be filled with storage key data by the ioctl. 2829 28304.91 KVM_S390_SET_SKEYS 2831 2832Capability: KVM_CAP_S390_SKEYS 2833Architectures: s390 2834Type: vm ioctl 2835Parameters: struct kvm_s390_skeys 2836Returns: 0 on success, negative value on error 2837 2838This ioctl is used to set guest storage key values on the s390 2839architecture. The ioctl takes parameters via the kvm_s390_skeys struct. 2840See section on KVM_S390_GET_SKEYS for struct definition. 2841 2842The start_gfn field is the number of the first guest frame whose storage keys 2843you want to set. 2844 2845The count field is the number of consecutive frames (starting from start_gfn) 2846whose storage keys to get. The count field must be at least 1 and the maximum 2847allowed value is defined as KVM_S390_SKEYS_ALLOC_MAX. Values outside this range 2848will cause the ioctl to return -EINVAL. 2849 2850The skeydata_addr field is the address to a buffer containing count bytes of 2851storage keys. Each byte in the buffer will be set as the storage key for a 2852single frame starting at start_gfn for count frames. 2853 2854Note: If any architecturally invalid key value is found in the given data then 2855the ioctl will return -EINVAL. 2856 28574.92 KVM_S390_IRQ 2858 2859Capability: KVM_CAP_S390_INJECT_IRQ 2860Architectures: s390 2861Type: vcpu ioctl 2862Parameters: struct kvm_s390_irq (in) 2863Returns: 0 on success, -1 on error 2864Errors: 2865 EINVAL: interrupt type is invalid 2866 type is KVM_S390_SIGP_STOP and flag parameter is invalid value 2867 type is KVM_S390_INT_EXTERNAL_CALL and code is bigger 2868 than the maximum of VCPUs 2869 EBUSY: type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped 2870 type is KVM_S390_SIGP_STOP and a stop irq is already pending 2871 type is KVM_S390_INT_EXTERNAL_CALL and an external call interrupt 2872 is already pending 2873 2874Allows to inject an interrupt to the guest. 2875 2876Using struct kvm_s390_irq as a parameter allows 2877to inject additional payload which is not 2878possible via KVM_S390_INTERRUPT. 2879 2880Interrupt parameters are passed via kvm_s390_irq: 2881 2882struct kvm_s390_irq { 2883 __u64 type; 2884 union { 2885 struct kvm_s390_io_info io; 2886 struct kvm_s390_ext_info ext; 2887 struct kvm_s390_pgm_info pgm; 2888 struct kvm_s390_emerg_info emerg; 2889 struct kvm_s390_extcall_info extcall; 2890 struct kvm_s390_prefix_info prefix; 2891 struct kvm_s390_stop_info stop; 2892 struct kvm_s390_mchk_info mchk; 2893 char reserved[64]; 2894 } u; 2895}; 2896 2897type can be one of the following: 2898 2899KVM_S390_SIGP_STOP - sigp stop; parameter in .stop 2900KVM_S390_PROGRAM_INT - program check; parameters in .pgm 2901KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix 2902KVM_S390_RESTART - restart; no parameters 2903KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters 2904KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters 2905KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg 2906KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall 2907KVM_S390_MCHK - machine check interrupt; parameters in .mchk 2908 2909 2910Note that the vcpu ioctl is asynchronous to vcpu execution. 2911 29124.94 KVM_S390_GET_IRQ_STATE 2913 2914Capability: KVM_CAP_S390_IRQ_STATE 2915Architectures: s390 2916Type: vcpu ioctl 2917Parameters: struct kvm_s390_irq_state (out) 2918Returns: >= number of bytes copied into buffer, 2919 -EINVAL if buffer size is 0, 2920 -ENOBUFS if buffer size is too small to fit all pending interrupts, 2921 -EFAULT if the buffer address was invalid 2922 2923This ioctl allows userspace to retrieve the complete state of all currently 2924pending interrupts in a single buffer. Use cases include migration 2925and introspection. The parameter structure contains the address of a 2926userspace buffer and its length: 2927 2928struct kvm_s390_irq_state { 2929 __u64 buf; 2930 __u32 flags; 2931 __u32 len; 2932 __u32 reserved[4]; 2933}; 2934 2935Userspace passes in the above struct and for each pending interrupt a 2936struct kvm_s390_irq is copied to the provided buffer. 2937 2938If -ENOBUFS is returned the buffer provided was too small and userspace 2939may retry with a bigger buffer. 2940 29414.95 KVM_S390_SET_IRQ_STATE 2942 2943Capability: KVM_CAP_S390_IRQ_STATE 2944Architectures: s390 2945Type: vcpu ioctl 2946Parameters: struct kvm_s390_irq_state (in) 2947Returns: 0 on success, 2948 -EFAULT if the buffer address was invalid, 2949 -EINVAL for an invalid buffer length (see below), 2950 -EBUSY if there were already interrupts pending, 2951 errors occurring when actually injecting the 2952 interrupt. See KVM_S390_IRQ. 2953 2954This ioctl allows userspace to set the complete state of all cpu-local 2955interrupts currently pending for the vcpu. It is intended for restoring 2956interrupt state after a migration. The input parameter is a userspace buffer 2957containing a struct kvm_s390_irq_state: 2958 2959struct kvm_s390_irq_state { 2960 __u64 buf; 2961 __u32 len; 2962 __u32 pad; 2963}; 2964 2965The userspace memory referenced by buf contains a struct kvm_s390_irq 2966for each interrupt to be injected into the guest. 2967If one of the interrupts could not be injected for some reason the 2968ioctl aborts. 2969 2970len must be a multiple of sizeof(struct kvm_s390_irq). It must be > 0 2971and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq), 2972which is the maximum number of possibly pending cpu-local interrupts. 2973 29744.96 KVM_SMI 2975 2976Capability: KVM_CAP_X86_SMM 2977Architectures: x86 2978Type: vcpu ioctl 2979Parameters: none 2980Returns: 0 on success, -1 on error 2981 2982Queues an SMI on the thread's vcpu. 2983 29844.97 KVM_CAP_PPC_MULTITCE 2985 2986Capability: KVM_CAP_PPC_MULTITCE 2987Architectures: ppc 2988Type: vm 2989 2990This capability means the kernel is capable of handling hypercalls 2991H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user 2992space. This significantly accelerates DMA operations for PPC KVM guests. 2993User space should expect that its handlers for these hypercalls 2994are not going to be called if user space previously registered LIOBN 2995in KVM (via KVM_CREATE_SPAPR_TCE or similar calls). 2996 2997In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest, 2998user space might have to advertise it for the guest. For example, 2999IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is 3000present in the "ibm,hypertas-functions" device-tree property. 3001 3002The hypercalls mentioned above may or may not be processed successfully 3003in the kernel based fast path. If they can not be handled by the kernel, 3004they will get passed on to user space. So user space still has to have 3005an implementation for these despite the in kernel acceleration. 3006 3007This capability is always enabled. 3008 30094.98 KVM_CREATE_SPAPR_TCE_64 3010 3011Capability: KVM_CAP_SPAPR_TCE_64 3012Architectures: powerpc 3013Type: vm ioctl 3014Parameters: struct kvm_create_spapr_tce_64 (in) 3015Returns: file descriptor for manipulating the created TCE table 3016 3017This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit 3018windows, described in 4.62 KVM_CREATE_SPAPR_TCE 3019 3020This capability uses extended struct in ioctl interface: 3021 3022/* for KVM_CAP_SPAPR_TCE_64 */ 3023struct kvm_create_spapr_tce_64 { 3024 __u64 liobn; 3025 __u32 page_shift; 3026 __u32 flags; 3027 __u64 offset; /* in pages */ 3028 __u64 size; /* in pages */ 3029}; 3030 3031The aim of extension is to support an additional bigger DMA window with 3032a variable page size. 3033KVM_CREATE_SPAPR_TCE_64 receives a 64bit window size, an IOMMU page shift and 3034a bus offset of the corresponding DMA window, @size and @offset are numbers 3035of IOMMU pages. 3036 3037@flags are not used at the moment. 3038 3039The rest of functionality is identical to KVM_CREATE_SPAPR_TCE. 3040 30414.99 KVM_REINJECT_CONTROL 3042 3043Capability: KVM_CAP_REINJECT_CONTROL 3044Architectures: x86 3045Type: vm ioctl 3046Parameters: struct kvm_reinject_control (in) 3047Returns: 0 on success, 3048 -EFAULT if struct kvm_reinject_control cannot be read, 3049 -ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier. 3050 3051i8254 (PIT) has two modes, reinject and !reinject. The default is reinject, 3052where KVM queues elapsed i8254 ticks and monitors completion of interrupt from 3053vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its 3054interrupt whenever there isn't a pending interrupt from i8254. 3055!reinject mode injects an interrupt as soon as a tick arrives. 3056 3057struct kvm_reinject_control { 3058 __u8 pit_reinject; 3059 __u8 reserved[31]; 3060}; 3061 3062pit_reinject = 0 (!reinject mode) is recommended, unless running an old 3063operating system that uses the PIT for timing (e.g. Linux 2.4.x). 3064 30654.100 KVM_PPC_CONFIGURE_V3_MMU 3066 3067Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3 3068Architectures: ppc 3069Type: vm ioctl 3070Parameters: struct kvm_ppc_mmuv3_cfg (in) 3071Returns: 0 on success, 3072 -EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read, 3073 -EINVAL if the configuration is invalid 3074 3075This ioctl controls whether the guest will use radix or HPT (hashed 3076page table) translation, and sets the pointer to the process table for 3077the guest. 3078 3079struct kvm_ppc_mmuv3_cfg { 3080 __u64 flags; 3081 __u64 process_table; 3082}; 3083 3084There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and 3085KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest 3086to use radix tree translation, and if clear, to use HPT translation. 3087KVM_PPC_MMUV3_GTSE, if set and if KVM permits it, configures the guest 3088to be able to use the global TLB and SLB invalidation instructions; 3089if clear, the guest may not use these instructions. 3090 3091The process_table field specifies the address and size of the guest 3092process table, which is in the guest's space. This field is formatted 3093as the second doubleword of the partition table entry, as defined in 3094the Power ISA V3.00, Book III section 5.7.6.1. 3095 30964.101 KVM_PPC_GET_RMMU_INFO 3097 3098Capability: KVM_CAP_PPC_RADIX_MMU 3099Architectures: ppc 3100Type: vm ioctl 3101Parameters: struct kvm_ppc_rmmu_info (out) 3102Returns: 0 on success, 3103 -EFAULT if struct kvm_ppc_rmmu_info cannot be written, 3104 -EINVAL if no useful information can be returned 3105 3106This ioctl returns a structure containing two things: (a) a list 3107containing supported radix tree geometries, and (b) a list that maps 3108page sizes to put in the "AP" (actual page size) field for the tlbie 3109(TLB invalidate entry) instruction. 3110 3111struct kvm_ppc_rmmu_info { 3112 struct kvm_ppc_radix_geom { 3113 __u8 page_shift; 3114 __u8 level_bits[4]; 3115 __u8 pad[3]; 3116 } geometries[8]; 3117 __u32 ap_encodings[8]; 3118}; 3119 3120The geometries[] field gives up to 8 supported geometries for the 3121radix page table, in terms of the log base 2 of the smallest page 3122size, and the number of bits indexed at each level of the tree, from 3123the PTE level up to the PGD level in that order. Any unused entries 3124will have 0 in the page_shift field. 3125 3126The ap_encodings gives the supported page sizes and their AP field 3127encodings, encoded with the AP value in the top 3 bits and the log 3128base 2 of the page size in the bottom 6 bits. 3129 31304.102 KVM_PPC_RESIZE_HPT_PREPARE 3131 3132Capability: KVM_CAP_SPAPR_RESIZE_HPT 3133Architectures: powerpc 3134Type: vm ioctl 3135Parameters: struct kvm_ppc_resize_hpt (in) 3136Returns: 0 on successful completion, 3137 >0 if a new HPT is being prepared, the value is an estimated 3138 number of milliseconds until preparation is complete 3139 -EFAULT if struct kvm_reinject_control cannot be read, 3140 -EINVAL if the supplied shift or flags are invalid 3141 -ENOMEM if unable to allocate the new HPT 3142 -ENOSPC if there was a hash collision when moving existing 3143 HPT entries to the new HPT 3144 -EIO on other error conditions 3145 3146Used to implement the PAPR extension for runtime resizing of a guest's 3147Hashed Page Table (HPT). Specifically this starts, stops or monitors 3148the preparation of a new potential HPT for the guest, essentially 3149implementing the H_RESIZE_HPT_PREPARE hypercall. 3150 3151If called with shift > 0 when there is no pending HPT for the guest, 3152this begins preparation of a new pending HPT of size 2^(shift) bytes. 3153It then returns a positive integer with the estimated number of 3154milliseconds until preparation is complete. 3155 3156If called when there is a pending HPT whose size does not match that 3157requested in the parameters, discards the existing pending HPT and 3158creates a new one as above. 3159 3160If called when there is a pending HPT of the size requested, will: 3161 * If preparation of the pending HPT is already complete, return 0 3162 * If preparation of the pending HPT has failed, return an error 3163 code, then discard the pending HPT. 3164 * If preparation of the pending HPT is still in progress, return an 3165 estimated number of milliseconds until preparation is complete. 3166 3167If called with shift == 0, discards any currently pending HPT and 3168returns 0 (i.e. cancels any in-progress preparation). 3169 3170flags is reserved for future expansion, currently setting any bits in 3171flags will result in an -EINVAL. 3172 3173Normally this will be called repeatedly with the same parameters until 3174it returns <= 0. The first call will initiate preparation, subsequent 3175ones will monitor preparation until it completes or fails. 3176 3177struct kvm_ppc_resize_hpt { 3178 __u64 flags; 3179 __u32 shift; 3180 __u32 pad; 3181}; 3182 31834.103 KVM_PPC_RESIZE_HPT_COMMIT 3184 3185Capability: KVM_CAP_SPAPR_RESIZE_HPT 3186Architectures: powerpc 3187Type: vm ioctl 3188Parameters: struct kvm_ppc_resize_hpt (in) 3189Returns: 0 on successful completion, 3190 -EFAULT if struct kvm_reinject_control cannot be read, 3191 -EINVAL if the supplied shift or flags are invalid 3192 -ENXIO is there is no pending HPT, or the pending HPT doesn't 3193 have the requested size 3194 -EBUSY if the pending HPT is not fully prepared 3195 -ENOSPC if there was a hash collision when moving existing 3196 HPT entries to the new HPT 3197 -EIO on other error conditions 3198 3199Used to implement the PAPR extension for runtime resizing of a guest's 3200Hashed Page Table (HPT). Specifically this requests that the guest be 3201transferred to working with the new HPT, essentially implementing the 3202H_RESIZE_HPT_COMMIT hypercall. 3203 3204This should only be called after KVM_PPC_RESIZE_HPT_PREPARE has 3205returned 0 with the same parameters. In other cases 3206KVM_PPC_RESIZE_HPT_COMMIT will return an error (usually -ENXIO or 3207-EBUSY, though others may be possible if the preparation was started, 3208but failed). 3209 3210This will have undefined effects on the guest if it has not already 3211placed itself in a quiescent state where no vcpu will make MMU enabled 3212memory accesses. 3213 3214On succsful completion, the pending HPT will become the guest's active 3215HPT and the previous HPT will be discarded. 3216 3217On failure, the guest will still be operating on its previous HPT. 3218 3219struct kvm_ppc_resize_hpt { 3220 __u64 flags; 3221 __u32 shift; 3222 __u32 pad; 3223}; 3224 32254.104 KVM_X86_GET_MCE_CAP_SUPPORTED 3226 3227Capability: KVM_CAP_MCE 3228Architectures: x86 3229Type: system ioctl 3230Parameters: u64 mce_cap (out) 3231Returns: 0 on success, -1 on error 3232 3233Returns supported MCE capabilities. The u64 mce_cap parameter 3234has the same format as the MSR_IA32_MCG_CAP register. Supported 3235capabilities will have the corresponding bits set. 3236 32374.105 KVM_X86_SETUP_MCE 3238 3239Capability: KVM_CAP_MCE 3240Architectures: x86 3241Type: vcpu ioctl 3242Parameters: u64 mcg_cap (in) 3243Returns: 0 on success, 3244 -EFAULT if u64 mcg_cap cannot be read, 3245 -EINVAL if the requested number of banks is invalid, 3246 -EINVAL if requested MCE capability is not supported. 3247 3248Initializes MCE support for use. The u64 mcg_cap parameter 3249has the same format as the MSR_IA32_MCG_CAP register and 3250specifies which capabilities should be enabled. The maximum 3251supported number of error-reporting banks can be retrieved when 3252checking for KVM_CAP_MCE. The supported capabilities can be 3253retrieved with KVM_X86_GET_MCE_CAP_SUPPORTED. 3254 32554.106 KVM_X86_SET_MCE 3256 3257Capability: KVM_CAP_MCE 3258Architectures: x86 3259Type: vcpu ioctl 3260Parameters: struct kvm_x86_mce (in) 3261Returns: 0 on success, 3262 -EFAULT if struct kvm_x86_mce cannot be read, 3263 -EINVAL if the bank number is invalid, 3264 -EINVAL if VAL bit is not set in status field. 3265 3266Inject a machine check error (MCE) into the guest. The input 3267parameter is: 3268 3269struct kvm_x86_mce { 3270 __u64 status; 3271 __u64 addr; 3272 __u64 misc; 3273 __u64 mcg_status; 3274 __u8 bank; 3275 __u8 pad1[7]; 3276 __u64 pad2[3]; 3277}; 3278 3279If the MCE being reported is an uncorrected error, KVM will 3280inject it as an MCE exception into the guest. If the guest 3281MCG_STATUS register reports that an MCE is in progress, KVM 3282causes an KVM_EXIT_SHUTDOWN vmexit. 3283 3284Otherwise, if the MCE is a corrected error, KVM will just 3285store it in the corresponding bank (provided this bank is 3286not holding a previously reported uncorrected error). 3287 32884.107 KVM_S390_GET_CMMA_BITS 3289 3290Capability: KVM_CAP_S390_CMMA_MIGRATION 3291Architectures: s390 3292Type: vm ioctl 3293Parameters: struct kvm_s390_cmma_log (in, out) 3294Returns: 0 on success, a negative value on error 3295 3296This ioctl is used to get the values of the CMMA bits on the s390 3297architecture. It is meant to be used in two scenarios: 3298- During live migration to save the CMMA values. Live migration needs 3299 to be enabled via the KVM_REQ_START_MIGRATION VM property. 3300- To non-destructively peek at the CMMA values, with the flag 3301 KVM_S390_CMMA_PEEK set. 3302 3303The ioctl takes parameters via the kvm_s390_cmma_log struct. The desired 3304values are written to a buffer whose location is indicated via the "values" 3305member in the kvm_s390_cmma_log struct. The values in the input struct are 3306also updated as needed. 3307Each CMMA value takes up one byte. 3308 3309struct kvm_s390_cmma_log { 3310 __u64 start_gfn; 3311 __u32 count; 3312 __u32 flags; 3313 union { 3314 __u64 remaining; 3315 __u64 mask; 3316 }; 3317 __u64 values; 3318}; 3319 3320start_gfn is the number of the first guest frame whose CMMA values are 3321to be retrieved, 3322 3323count is the length of the buffer in bytes, 3324 3325values points to the buffer where the result will be written to. 3326 3327If count is greater than KVM_S390_SKEYS_MAX, then it is considered to be 3328KVM_S390_SKEYS_MAX. KVM_S390_SKEYS_MAX is re-used for consistency with 3329other ioctls. 3330 3331The result is written in the buffer pointed to by the field values, and 3332the values of the input parameter are updated as follows. 3333 3334Depending on the flags, different actions are performed. The only 3335supported flag so far is KVM_S390_CMMA_PEEK. 3336 3337The default behaviour if KVM_S390_CMMA_PEEK is not set is: 3338start_gfn will indicate the first page frame whose CMMA bits were dirty. 3339It is not necessarily the same as the one passed as input, as clean pages 3340are skipped. 3341 3342count will indicate the number of bytes actually written in the buffer. 3343It can (and very often will) be smaller than the input value, since the 3344buffer is only filled until 16 bytes of clean values are found (which 3345are then not copied in the buffer). Since a CMMA migration block needs 3346the base address and the length, for a total of 16 bytes, we will send 3347back some clean data if there is some dirty data afterwards, as long as 3348the size of the clean data does not exceed the size of the header. This 3349allows to minimize the amount of data to be saved or transferred over 3350the network at the expense of more roundtrips to userspace. The next 3351invocation of the ioctl will skip over all the clean values, saving 3352potentially more than just the 16 bytes we found. 3353 3354If KVM_S390_CMMA_PEEK is set: 3355the existing storage attributes are read even when not in migration 3356mode, and no other action is performed; 3357 3358the output start_gfn will be equal to the input start_gfn, 3359 3360the output count will be equal to the input count, except if the end of 3361memory has been reached. 3362 3363In both cases: 3364the field "remaining" will indicate the total number of dirty CMMA values 3365still remaining, or 0 if KVM_S390_CMMA_PEEK is set and migration mode is 3366not enabled. 3367 3368mask is unused. 3369 3370values points to the userspace buffer where the result will be stored. 3371 3372This ioctl can fail with -ENOMEM if not enough memory can be allocated to 3373complete the task, with -ENXIO if CMMA is not enabled, with -EINVAL if 3374KVM_S390_CMMA_PEEK is not set but migration mode was not enabled, with 3375-EFAULT if the userspace address is invalid or if no page table is 3376present for the addresses (e.g. when using hugepages). 3377 33784.108 KVM_S390_SET_CMMA_BITS 3379 3380Capability: KVM_CAP_S390_CMMA_MIGRATION 3381Architectures: s390 3382Type: vm ioctl 3383Parameters: struct kvm_s390_cmma_log (in) 3384Returns: 0 on success, a negative value on error 3385 3386This ioctl is used to set the values of the CMMA bits on the s390 3387architecture. It is meant to be used during live migration to restore 3388the CMMA values, but there are no restrictions on its use. 3389The ioctl takes parameters via the kvm_s390_cmma_values struct. 3390Each CMMA value takes up one byte. 3391 3392struct kvm_s390_cmma_log { 3393 __u64 start_gfn; 3394 __u32 count; 3395 __u32 flags; 3396 union { 3397 __u64 remaining; 3398 __u64 mask; 3399 }; 3400 __u64 values; 3401}; 3402 3403start_gfn indicates the starting guest frame number, 3404 3405count indicates how many values are to be considered in the buffer, 3406 3407flags is not used and must be 0. 3408 3409mask indicates which PGSTE bits are to be considered. 3410 3411remaining is not used. 3412 3413values points to the buffer in userspace where to store the values. 3414 3415This ioctl can fail with -ENOMEM if not enough memory can be allocated to 3416complete the task, with -ENXIO if CMMA is not enabled, with -EINVAL if 3417the count field is too large (e.g. more than KVM_S390_CMMA_SIZE_MAX) or 3418if the flags field was not 0, with -EFAULT if the userspace address is 3419invalid, if invalid pages are written to (e.g. after the end of memory) 3420or if no page table is present for the addresses (e.g. when using 3421hugepages). 3422 34235. The kvm_run structure 3424------------------------ 3425 3426Application code obtains a pointer to the kvm_run structure by 3427mmap()ing a vcpu fd. From that point, application code can control 3428execution by changing fields in kvm_run prior to calling the KVM_RUN 3429ioctl, and obtain information about the reason KVM_RUN returned by 3430looking up structure members. 3431 3432struct kvm_run { 3433 /* in */ 3434 __u8 request_interrupt_window; 3435 3436Request that KVM_RUN return when it becomes possible to inject external 3437interrupts into the guest. Useful in conjunction with KVM_INTERRUPT. 3438 3439 __u8 immediate_exit; 3440 3441This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN 3442exits immediately, returning -EINTR. In the common scenario where a 3443signal is used to "kick" a VCPU out of KVM_RUN, this field can be used 3444to avoid usage of KVM_SET_SIGNAL_MASK, which has worse scalability. 3445Rather than blocking the signal outside KVM_RUN, userspace can set up 3446a signal handler that sets run->immediate_exit to a non-zero value. 3447 3448This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available. 3449 3450 __u8 padding1[6]; 3451 3452 /* out */ 3453 __u32 exit_reason; 3454 3455When KVM_RUN has returned successfully (return value 0), this informs 3456application code why KVM_RUN has returned. Allowable values for this 3457field are detailed below. 3458 3459 __u8 ready_for_interrupt_injection; 3460 3461If request_interrupt_window has been specified, this field indicates 3462an interrupt can be injected now with KVM_INTERRUPT. 3463 3464 __u8 if_flag; 3465 3466The value of the current interrupt flag. Only valid if in-kernel 3467local APIC is not used. 3468 3469 __u16 flags; 3470 3471More architecture-specific flags detailing state of the VCPU that may 3472affect the device's behavior. The only currently defined flag is 3473KVM_RUN_X86_SMM, which is valid on x86 machines and is set if the 3474VCPU is in system management mode. 3475 3476 /* in (pre_kvm_run), out (post_kvm_run) */ 3477 __u64 cr8; 3478 3479The value of the cr8 register. Only valid if in-kernel local APIC is 3480not used. Both input and output. 3481 3482 __u64 apic_base; 3483 3484The value of the APIC BASE msr. Only valid if in-kernel local 3485APIC is not used. Both input and output. 3486 3487 union { 3488 /* KVM_EXIT_UNKNOWN */ 3489 struct { 3490 __u64 hardware_exit_reason; 3491 } hw; 3492 3493If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown 3494reasons. Further architecture-specific information is available in 3495hardware_exit_reason. 3496 3497 /* KVM_EXIT_FAIL_ENTRY */ 3498 struct { 3499 __u64 hardware_entry_failure_reason; 3500 } fail_entry; 3501 3502If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due 3503to unknown reasons. Further architecture-specific information is 3504available in hardware_entry_failure_reason. 3505 3506 /* KVM_EXIT_EXCEPTION */ 3507 struct { 3508 __u32 exception; 3509 __u32 error_code; 3510 } ex; 3511 3512Unused. 3513 3514 /* KVM_EXIT_IO */ 3515 struct { 3516#define KVM_EXIT_IO_IN 0 3517#define KVM_EXIT_IO_OUT 1 3518 __u8 direction; 3519 __u8 size; /* bytes */ 3520 __u16 port; 3521 __u32 count; 3522 __u64 data_offset; /* relative to kvm_run start */ 3523 } io; 3524 3525If exit_reason is KVM_EXIT_IO, then the vcpu has 3526executed a port I/O instruction which could not be satisfied by kvm. 3527data_offset describes where the data is located (KVM_EXIT_IO_OUT) or 3528where kvm expects application code to place the data for the next 3529KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array. 3530 3531 /* KVM_EXIT_DEBUG */ 3532 struct { 3533 struct kvm_debug_exit_arch arch; 3534 } debug; 3535 3536If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event 3537for which architecture specific information is returned. 3538 3539 /* KVM_EXIT_MMIO */ 3540 struct { 3541 __u64 phys_addr; 3542 __u8 data[8]; 3543 __u32 len; 3544 __u8 is_write; 3545 } mmio; 3546 3547If exit_reason is KVM_EXIT_MMIO, then the vcpu has 3548executed a memory-mapped I/O instruction which could not be satisfied 3549by kvm. The 'data' member contains the written data if 'is_write' is 3550true, and should be filled by application code otherwise. 3551 3552The 'data' member contains, in its first 'len' bytes, the value as it would 3553appear if the VCPU performed a load or store of the appropriate width directly 3554to the byte array. 3555 3556NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and 3557 KVM_EXIT_EPR the corresponding 3558operations are complete (and guest state is consistent) only after userspace 3559has re-entered the kernel with KVM_RUN. The kernel side will first finish 3560incomplete operations and then check for pending signals. Userspace 3561can re-enter the guest with an unmasked signal pending to complete 3562pending operations. 3563 3564 /* KVM_EXIT_HYPERCALL */ 3565 struct { 3566 __u64 nr; 3567 __u64 args[6]; 3568 __u64 ret; 3569 __u32 longmode; 3570 __u32 pad; 3571 } hypercall; 3572 3573Unused. This was once used for 'hypercall to userspace'. To implement 3574such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390). 3575Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO. 3576 3577 /* KVM_EXIT_TPR_ACCESS */ 3578 struct { 3579 __u64 rip; 3580 __u32 is_write; 3581 __u32 pad; 3582 } tpr_access; 3583 3584To be documented (KVM_TPR_ACCESS_REPORTING). 3585 3586 /* KVM_EXIT_S390_SIEIC */ 3587 struct { 3588 __u8 icptcode; 3589 __u64 mask; /* psw upper half */ 3590 __u64 addr; /* psw lower half */ 3591 __u16 ipa; 3592 __u32 ipb; 3593 } s390_sieic; 3594 3595s390 specific. 3596 3597 /* KVM_EXIT_S390_RESET */ 3598#define KVM_S390_RESET_POR 1 3599#define KVM_S390_RESET_CLEAR 2 3600#define KVM_S390_RESET_SUBSYSTEM 4 3601#define KVM_S390_RESET_CPU_INIT 8 3602#define KVM_S390_RESET_IPL 16 3603 __u64 s390_reset_flags; 3604 3605s390 specific. 3606 3607 /* KVM_EXIT_S390_UCONTROL */ 3608 struct { 3609 __u64 trans_exc_code; 3610 __u32 pgm_code; 3611 } s390_ucontrol; 3612 3613s390 specific. A page fault has occurred for a user controlled virtual 3614machine (KVM_VM_S390_UNCONTROL) on it's host page table that cannot be 3615resolved by the kernel. 3616The program code and the translation exception code that were placed 3617in the cpu's lowcore are presented here as defined by the z Architecture 3618Principles of Operation Book in the Chapter for Dynamic Address Translation 3619(DAT) 3620 3621 /* KVM_EXIT_DCR */ 3622 struct { 3623 __u32 dcrn; 3624 __u32 data; 3625 __u8 is_write; 3626 } dcr; 3627 3628Deprecated - was used for 440 KVM. 3629 3630 /* KVM_EXIT_OSI */ 3631 struct { 3632 __u64 gprs[32]; 3633 } osi; 3634 3635MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch 3636hypercalls and exit with this exit struct that contains all the guest gprs. 3637 3638If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall. 3639Userspace can now handle the hypercall and when it's done modify the gprs as 3640necessary. Upon guest entry all guest GPRs will then be replaced by the values 3641in this struct. 3642 3643 /* KVM_EXIT_PAPR_HCALL */ 3644 struct { 3645 __u64 nr; 3646 __u64 ret; 3647 __u64 args[9]; 3648 } papr_hcall; 3649 3650This is used on 64-bit PowerPC when emulating a pSeries partition, 3651e.g. with the 'pseries' machine type in qemu. It occurs when the 3652guest does a hypercall using the 'sc 1' instruction. The 'nr' field 3653contains the hypercall number (from the guest R3), and 'args' contains 3654the arguments (from the guest R4 - R12). Userspace should put the 3655return code in 'ret' and any extra returned values in args[]. 3656The possible hypercalls are defined in the Power Architecture Platform 3657Requirements (PAPR) document available from www.power.org (free 3658developer registration required to access it). 3659 3660 /* KVM_EXIT_S390_TSCH */ 3661 struct { 3662 __u16 subchannel_id; 3663 __u16 subchannel_nr; 3664 __u32 io_int_parm; 3665 __u32 io_int_word; 3666 __u32 ipb; 3667 __u8 dequeued; 3668 } s390_tsch; 3669 3670s390 specific. This exit occurs when KVM_CAP_S390_CSS_SUPPORT has been enabled 3671and TEST SUBCHANNEL was intercepted. If dequeued is set, a pending I/O 3672interrupt for the target subchannel has been dequeued and subchannel_id, 3673subchannel_nr, io_int_parm and io_int_word contain the parameters for that 3674interrupt. ipb is needed for instruction parameter decoding. 3675 3676 /* KVM_EXIT_EPR */ 3677 struct { 3678 __u32 epr; 3679 } epr; 3680 3681On FSL BookE PowerPC chips, the interrupt controller has a fast patch 3682interrupt acknowledge path to the core. When the core successfully 3683delivers an interrupt, it automatically populates the EPR register with 3684the interrupt vector number and acknowledges the interrupt inside 3685the interrupt controller. 3686 3687In case the interrupt controller lives in user space, we need to do 3688the interrupt acknowledge cycle through it to fetch the next to be 3689delivered interrupt vector using this exit. 3690 3691It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an 3692external interrupt has just been delivered into the guest. User space 3693should put the acknowledged interrupt vector into the 'epr' field. 3694 3695 /* KVM_EXIT_SYSTEM_EVENT */ 3696 struct { 3697#define KVM_SYSTEM_EVENT_SHUTDOWN 1 3698#define KVM_SYSTEM_EVENT_RESET 2 3699#define KVM_SYSTEM_EVENT_CRASH 3 3700 __u32 type; 3701 __u64 flags; 3702 } system_event; 3703 3704If exit_reason is KVM_EXIT_SYSTEM_EVENT then the vcpu has triggered 3705a system-level event using some architecture specific mechanism (hypercall 3706or some special instruction). In case of ARM/ARM64, this is triggered using 3707HVC instruction based PSCI call from the vcpu. The 'type' field describes 3708the system-level event type. The 'flags' field describes architecture 3709specific flags for the system-level event. 3710 3711Valid values for 'type' are: 3712 KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the 3713 VM. Userspace is not obliged to honour this, and if it does honour 3714 this does not need to destroy the VM synchronously (ie it may call 3715 KVM_RUN again before shutdown finally occurs). 3716 KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM. 3717 As with SHUTDOWN, userspace can choose to ignore the request, or 3718 to schedule the reset to occur in the future and may call KVM_RUN again. 3719 KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest 3720 has requested a crash condition maintenance. Userspace can choose 3721 to ignore the request, or to gather VM memory core dump and/or 3722 reset/shutdown of the VM. 3723 3724 /* KVM_EXIT_IOAPIC_EOI */ 3725 struct { 3726 __u8 vector; 3727 } eoi; 3728 3729Indicates that the VCPU's in-kernel local APIC received an EOI for a 3730level-triggered IOAPIC interrupt. This exit only triggers when the 3731IOAPIC is implemented in userspace (i.e. KVM_CAP_SPLIT_IRQCHIP is enabled); 3732the userspace IOAPIC should process the EOI and retrigger the interrupt if 3733it is still asserted. Vector is the LAPIC interrupt vector for which the 3734EOI was received. 3735 3736 struct kvm_hyperv_exit { 3737#define KVM_EXIT_HYPERV_SYNIC 1 3738#define KVM_EXIT_HYPERV_HCALL 2 3739 __u32 type; 3740 union { 3741 struct { 3742 __u32 msr; 3743 __u64 control; 3744 __u64 evt_page; 3745 __u64 msg_page; 3746 } synic; 3747 struct { 3748 __u64 input; 3749 __u64 result; 3750 __u64 params[2]; 3751 } hcall; 3752 } u; 3753 }; 3754 /* KVM_EXIT_HYPERV */ 3755 struct kvm_hyperv_exit hyperv; 3756Indicates that the VCPU exits into userspace to process some tasks 3757related to Hyper-V emulation. 3758Valid values for 'type' are: 3759 KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about 3760Hyper-V SynIC state change. Notification is used to remap SynIC 3761event/message pages and to enable/disable SynIC messages/events processing 3762in userspace. 3763 3764 /* Fix the size of the union. */ 3765 char padding[256]; 3766 }; 3767 3768 /* 3769 * shared registers between kvm and userspace. 3770 * kvm_valid_regs specifies the register classes set by the host 3771 * kvm_dirty_regs specified the register classes dirtied by userspace 3772 * struct kvm_sync_regs is architecture specific, as well as the 3773 * bits for kvm_valid_regs and kvm_dirty_regs 3774 */ 3775 __u64 kvm_valid_regs; 3776 __u64 kvm_dirty_regs; 3777 union { 3778 struct kvm_sync_regs regs; 3779 char padding[1024]; 3780 } s; 3781 3782If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access 3783certain guest registers without having to call SET/GET_*REGS. Thus we can 3784avoid some system call overhead if userspace has to handle the exit. 3785Userspace can query the validity of the structure by checking 3786kvm_valid_regs for specific bits. These bits are architecture specific 3787and usually define the validity of a groups of registers. (e.g. one bit 3788 for general purpose registers) 3789 3790Please note that the kernel is allowed to use the kvm_run structure as the 3791primary storage for certain register types. Therefore, the kernel may use the 3792values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set. 3793 3794}; 3795 3796 3797 37986. Capabilities that can be enabled on vCPUs 3799-------------------------------------------- 3800 3801There are certain capabilities that change the behavior of the virtual CPU or 3802the virtual machine when enabled. To enable them, please see section 4.37. 3803Below you can find a list of capabilities and what their effect on the vCPU or 3804the virtual machine is when enabling them. 3805 3806The following information is provided along with the description: 3807 3808 Architectures: which instruction set architectures provide this ioctl. 3809 x86 includes both i386 and x86_64. 3810 3811 Target: whether this is a per-vcpu or per-vm capability. 3812 3813 Parameters: what parameters are accepted by the capability. 3814 3815 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) 3816 are not detailed, but errors with specific meanings are. 3817 3818 38196.1 KVM_CAP_PPC_OSI 3820 3821Architectures: ppc 3822Target: vcpu 3823Parameters: none 3824Returns: 0 on success; -1 on error 3825 3826This capability enables interception of OSI hypercalls that otherwise would 3827be treated as normal system calls to be injected into the guest. OSI hypercalls 3828were invented by Mac-on-Linux to have a standardized communication mechanism 3829between the guest and the host. 3830 3831When this capability is enabled, KVM_EXIT_OSI can occur. 3832 3833 38346.2 KVM_CAP_PPC_PAPR 3835 3836Architectures: ppc 3837Target: vcpu 3838Parameters: none 3839Returns: 0 on success; -1 on error 3840 3841This capability enables interception of PAPR hypercalls. PAPR hypercalls are 3842done using the hypercall instruction "sc 1". 3843 3844It also sets the guest privilege level to "supervisor" mode. Usually the guest 3845runs in "hypervisor" privilege mode with a few missing features. 3846 3847In addition to the above, it changes the semantics of SDR1. In this mode, the 3848HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the 3849HTAB invisible to the guest. 3850 3851When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur. 3852 3853 38546.3 KVM_CAP_SW_TLB 3855 3856Architectures: ppc 3857Target: vcpu 3858Parameters: args[0] is the address of a struct kvm_config_tlb 3859Returns: 0 on success; -1 on error 3860 3861struct kvm_config_tlb { 3862 __u64 params; 3863 __u64 array; 3864 __u32 mmu_type; 3865 __u32 array_len; 3866}; 3867 3868Configures the virtual CPU's TLB array, establishing a shared memory area 3869between userspace and KVM. The "params" and "array" fields are userspace 3870addresses of mmu-type-specific data structures. The "array_len" field is an 3871safety mechanism, and should be set to the size in bytes of the memory that 3872userspace has reserved for the array. It must be at least the size dictated 3873by "mmu_type" and "params". 3874 3875While KVM_RUN is active, the shared region is under control of KVM. Its 3876contents are undefined, and any modification by userspace results in 3877boundedly undefined behavior. 3878 3879On return from KVM_RUN, the shared region will reflect the current state of 3880the guest's TLB. If userspace makes any changes, it must call KVM_DIRTY_TLB 3881to tell KVM which entries have been changed, prior to calling KVM_RUN again 3882on this vcpu. 3883 3884For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV: 3885 - The "params" field is of type "struct kvm_book3e_206_tlb_params". 3886 - The "array" field points to an array of type "struct 3887 kvm_book3e_206_tlb_entry". 3888 - The array consists of all entries in the first TLB, followed by all 3889 entries in the second TLB. 3890 - Within a TLB, entries are ordered first by increasing set number. Within a 3891 set, entries are ordered by way (increasing ESEL). 3892 - The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1) 3893 where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value. 3894 - The tsize field of mas1 shall be set to 4K on TLB0, even though the 3895 hardware ignores this value for TLB0. 3896 38976.4 KVM_CAP_S390_CSS_SUPPORT 3898 3899Architectures: s390 3900Target: vcpu 3901Parameters: none 3902Returns: 0 on success; -1 on error 3903 3904This capability enables support for handling of channel I/O instructions. 3905 3906TEST PENDING INTERRUPTION and the interrupt portion of TEST SUBCHANNEL are 3907handled in-kernel, while the other I/O instructions are passed to userspace. 3908 3909When this capability is enabled, KVM_EXIT_S390_TSCH will occur on TEST 3910SUBCHANNEL intercepts. 3911 3912Note that even though this capability is enabled per-vcpu, the complete 3913virtual machine is affected. 3914 39156.5 KVM_CAP_PPC_EPR 3916 3917Architectures: ppc 3918Target: vcpu 3919Parameters: args[0] defines whether the proxy facility is active 3920Returns: 0 on success; -1 on error 3921 3922This capability enables or disables the delivery of interrupts through the 3923external proxy facility. 3924 3925When enabled (args[0] != 0), every time the guest gets an external interrupt 3926delivered, it automatically exits into user space with a KVM_EXIT_EPR exit 3927to receive the topmost interrupt vector. 3928 3929When disabled (args[0] == 0), behavior is as if this facility is unsupported. 3930 3931When this capability is enabled, KVM_EXIT_EPR can occur. 3932 39336.6 KVM_CAP_IRQ_MPIC 3934 3935Architectures: ppc 3936Parameters: args[0] is the MPIC device fd 3937 args[1] is the MPIC CPU number for this vcpu 3938 3939This capability connects the vcpu to an in-kernel MPIC device. 3940 39416.7 KVM_CAP_IRQ_XICS 3942 3943Architectures: ppc 3944Target: vcpu 3945Parameters: args[0] is the XICS device fd 3946 args[1] is the XICS CPU number (server ID) for this vcpu 3947 3948This capability connects the vcpu to an in-kernel XICS device. 3949 39506.8 KVM_CAP_S390_IRQCHIP 3951 3952Architectures: s390 3953Target: vm 3954Parameters: none 3955 3956This capability enables the in-kernel irqchip for s390. Please refer to 3957"4.24 KVM_CREATE_IRQCHIP" for details. 3958 39596.9 KVM_CAP_MIPS_FPU 3960 3961Architectures: mips 3962Target: vcpu 3963Parameters: args[0] is reserved for future use (should be 0). 3964 3965This capability allows the use of the host Floating Point Unit by the guest. It 3966allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is 3967done the KVM_REG_MIPS_FPR_* and KVM_REG_MIPS_FCR_* registers can be accessed 3968(depending on the current guest FPU register mode), and the Status.FR, 3969Config5.FRE bits are accessible via the KVM API and also from the guest, 3970depending on them being supported by the FPU. 3971 39726.10 KVM_CAP_MIPS_MSA 3973 3974Architectures: mips 3975Target: vcpu 3976Parameters: args[0] is reserved for future use (should be 0). 3977 3978This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest. 3979It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest. 3980Once this is done the KVM_REG_MIPS_VEC_* and KVM_REG_MIPS_MSA_* registers can be 3981accessed, and the Config5.MSAEn bit is accessible via the KVM API and also from 3982the guest. 3983 39847. Capabilities that can be enabled on VMs 3985------------------------------------------ 3986 3987There are certain capabilities that change the behavior of the virtual 3988machine when enabled. To enable them, please see section 4.37. Below 3989you can find a list of capabilities and what their effect on the VM 3990is when enabling them. 3991 3992The following information is provided along with the description: 3993 3994 Architectures: which instruction set architectures provide this ioctl. 3995 x86 includes both i386 and x86_64. 3996 3997 Parameters: what parameters are accepted by the capability. 3998 3999 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL) 4000 are not detailed, but errors with specific meanings are. 4001 4002 40037.1 KVM_CAP_PPC_ENABLE_HCALL 4004 4005Architectures: ppc 4006Parameters: args[0] is the sPAPR hcall number 4007 args[1] is 0 to disable, 1 to enable in-kernel handling 4008 4009This capability controls whether individual sPAPR hypercalls (hcalls) 4010get handled by the kernel or not. Enabling or disabling in-kernel 4011handling of an hcall is effective across the VM. On creation, an 4012initial set of hcalls are enabled for in-kernel handling, which 4013consists of those hcalls for which in-kernel handlers were implemented 4014before this capability was implemented. If disabled, the kernel will 4015not to attempt to handle the hcall, but will always exit to userspace 4016to handle it. Note that it may not make sense to enable some and 4017disable others of a group of related hcalls, but KVM does not prevent 4018userspace from doing that. 4019 4020If the hcall number specified is not one that has an in-kernel 4021implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL 4022error. 4023 40247.2 KVM_CAP_S390_USER_SIGP 4025 4026Architectures: s390 4027Parameters: none 4028 4029This capability controls which SIGP orders will be handled completely in user 4030space. With this capability enabled, all fast orders will be handled completely 4031in the kernel: 4032- SENSE 4033- SENSE RUNNING 4034- EXTERNAL CALL 4035- EMERGENCY SIGNAL 4036- CONDITIONAL EMERGENCY SIGNAL 4037 4038All other orders will be handled completely in user space. 4039 4040Only privileged operation exceptions will be checked for in the kernel (or even 4041in the hardware prior to interception). If this capability is not enabled, the 4042old way of handling SIGP orders is used (partially in kernel and user space). 4043 40447.3 KVM_CAP_S390_VECTOR_REGISTERS 4045 4046Architectures: s390 4047Parameters: none 4048Returns: 0 on success, negative value on error 4049 4050Allows use of the vector registers introduced with z13 processor, and 4051provides for the synchronization between host and user space. Will 4052return -EINVAL if the machine does not support vectors. 4053 40547.4 KVM_CAP_S390_USER_STSI 4055 4056Architectures: s390 4057Parameters: none 4058 4059This capability allows post-handlers for the STSI instruction. After 4060initial handling in the kernel, KVM exits to user space with 4061KVM_EXIT_S390_STSI to allow user space to insert further data. 4062 4063Before exiting to userspace, kvm handlers should fill in s390_stsi field of 4064vcpu->run: 4065struct { 4066 __u64 addr; 4067 __u8 ar; 4068 __u8 reserved; 4069 __u8 fc; 4070 __u8 sel1; 4071 __u16 sel2; 4072} s390_stsi; 4073 4074@addr - guest address of STSI SYSIB 4075@fc - function code 4076@sel1 - selector 1 4077@sel2 - selector 2 4078@ar - access register number 4079 4080KVM handlers should exit to userspace with rc = -EREMOTE. 4081 40827.5 KVM_CAP_SPLIT_IRQCHIP 4083 4084Architectures: x86 4085Parameters: args[0] - number of routes reserved for userspace IOAPICs 4086Returns: 0 on success, -1 on error 4087 4088Create a local apic for each processor in the kernel. This can be used 4089instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the 4090IOAPIC and PIC (and also the PIT, even though this has to be enabled 4091separately). 4092 4093This capability also enables in kernel routing of interrupt requests; 4094when KVM_CAP_SPLIT_IRQCHIP only routes of KVM_IRQ_ROUTING_MSI type are 4095used in the IRQ routing table. The first args[0] MSI routes are reserved 4096for the IOAPIC pins. Whenever the LAPIC receives an EOI for these routes, 4097a KVM_EXIT_IOAPIC_EOI vmexit will be reported to userspace. 4098 4099Fails if VCPU has already been created, or if the irqchip is already in the 4100kernel (i.e. KVM_CREATE_IRQCHIP has already been called). 4101 41027.6 KVM_CAP_S390_RI 4103 4104Architectures: s390 4105Parameters: none 4106 4107Allows use of runtime-instrumentation introduced with zEC12 processor. 4108Will return -EINVAL if the machine does not support runtime-instrumentation. 4109Will return -EBUSY if a VCPU has already been created. 4110 41117.7 KVM_CAP_X2APIC_API 4112 4113Architectures: x86 4114Parameters: args[0] - features that should be enabled 4115Returns: 0 on success, -EINVAL when args[0] contains invalid features 4116 4117Valid feature flags in args[0] are 4118 4119#define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0) 4120#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1) 4121 4122Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior of 4123KVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC, 4124allowing the use of 32-bit APIC IDs. See KVM_CAP_X2APIC_API in their 4125respective sections. 4126 4127KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK must be enabled for x2APIC to work 4128in logical mode or with more than 255 VCPUs. Otherwise, KVM treats 0xff 4129as a broadcast even in x2APIC mode in order to support physical x2APIC 4130without interrupt remapping. This is undesirable in logical mode, 4131where 0xff represents CPUs 0-7 in cluster 0. 4132 41337.8 KVM_CAP_S390_USER_INSTR0 4134 4135Architectures: s390 4136Parameters: none 4137 4138With this capability enabled, all illegal instructions 0x0000 (2 bytes) will 4139be intercepted and forwarded to user space. User space can use this 4140mechanism e.g. to realize 2-byte software breakpoints. The kernel will 4141not inject an operating exception for these instructions, user space has 4142to take care of that. 4143 4144This capability can be enabled dynamically even if VCPUs were already 4145created and are running. 4146 41477.9 KVM_CAP_S390_GS 4148 4149Architectures: s390 4150Parameters: none 4151Returns: 0 on success; -EINVAL if the machine does not support 4152 guarded storage; -EBUSY if a VCPU has already been created. 4153 4154Allows use of guarded storage for the KVM guest. 4155 41567.10 KVM_CAP_S390_AIS 4157 4158Architectures: s390 4159Parameters: none 4160 4161Allow use of adapter-interruption suppression. 4162Returns: 0 on success; -EBUSY if a VCPU has already been created. 4163 41647.11 KVM_CAP_PPC_SMT 4165 4166Architectures: ppc 4167Parameters: vsmt_mode, flags 4168 4169Enabling this capability on a VM provides userspace with a way to set 4170the desired virtual SMT mode (i.e. the number of virtual CPUs per 4171virtual core). The virtual SMT mode, vsmt_mode, must be a power of 2 4172between 1 and 8. On POWER8, vsmt_mode must also be no greater than 4173the number of threads per subcore for the host. Currently flags must 4174be 0. A successful call to enable this capability will result in 4175vsmt_mode being returned when the KVM_CAP_PPC_SMT capability is 4176subsequently queried for the VM. This capability is only supported by 4177HV KVM, and can only be set before any VCPUs have been created. 4178The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMT 4179modes are available. 4180 41817.12 KVM_CAP_PPC_FWNMI 4182 4183Architectures: ppc 4184Parameters: none 4185 4186With this capability a machine check exception in the guest address 4187space will cause KVM to exit the guest with NMI exit reason. This 4188enables QEMU to build error log and branch to guest kernel registered 4189machine check handling routine. Without this capability KVM will 4190branch to guests' 0x200 interrupt vector. 4191 41928. Other capabilities. 4193---------------------- 4194 4195This section lists capabilities that give information about other 4196features of the KVM implementation. 4197 41988.1 KVM_CAP_PPC_HWRNG 4199 4200Architectures: ppc 4201 4202This capability, if KVM_CHECK_EXTENSION indicates that it is 4203available, means that that the kernel has an implementation of the 4204H_RANDOM hypercall backed by a hardware random-number generator. 4205If present, the kernel H_RANDOM handler can be enabled for guest use 4206with the KVM_CAP_PPC_ENABLE_HCALL capability. 4207 42088.2 KVM_CAP_HYPERV_SYNIC 4209 4210Architectures: x86 4211This capability, if KVM_CHECK_EXTENSION indicates that it is 4212available, means that that the kernel has an implementation of the 4213Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is 4214used to support Windows Hyper-V based guest paravirt drivers(VMBus). 4215 4216In order to use SynIC, it has to be activated by setting this 4217capability via KVM_ENABLE_CAP ioctl on the vcpu fd. Note that this 4218will disable the use of APIC hardware virtualization even if supported 4219by the CPU, as it's incompatible with SynIC auto-EOI behavior. 4220 42218.3 KVM_CAP_PPC_RADIX_MMU 4222 4223Architectures: ppc 4224 4225This capability, if KVM_CHECK_EXTENSION indicates that it is 4226available, means that that the kernel can support guests using the 4227radix MMU defined in Power ISA V3.00 (as implemented in the POWER9 4228processor). 4229 42308.4 KVM_CAP_PPC_HASH_MMU_V3 4231 4232Architectures: ppc 4233 4234This capability, if KVM_CHECK_EXTENSION indicates that it is 4235available, means that that the kernel can support guests using the 4236hashed page table MMU defined in Power ISA V3.00 (as implemented in 4237the POWER9 processor), including in-memory segment tables. 4238 42398.5 KVM_CAP_MIPS_VZ 4240 4241Architectures: mips 4242 4243This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that 4244it is available, means that full hardware assisted virtualization capabilities 4245of the hardware are available for use through KVM. An appropriate 4246KVM_VM_MIPS_* type must be passed to KVM_CREATE_VM to create a VM which 4247utilises it. 4248 4249If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is 4250available, it means that the VM is using full hardware assisted virtualization 4251capabilities of the hardware. This is useful to check after creating a VM with 4252KVM_VM_MIPS_DEFAULT. 4253 4254The value returned by KVM_CHECK_EXTENSION should be compared against known 4255values (see below). All other values are reserved. This is to allow for the 4256possibility of other hardware assisted virtualization implementations which 4257may be incompatible with the MIPS VZ ASE. 4258 4259 0: The trap & emulate implementation is in use to run guest code in user 4260 mode. Guest virtual memory segments are rearranged to fit the guest in the 4261 user mode address space. 4262 4263 1: The MIPS VZ ASE is in use, providing full hardware assisted 4264 virtualization, including standard guest virtual memory segments. 4265 42668.6 KVM_CAP_MIPS_TE 4267 4268Architectures: mips 4269 4270This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that 4271it is available, means that the trap & emulate implementation is available to 4272run guest code in user mode, even if KVM_CAP_MIPS_VZ indicates that hardware 4273assisted virtualisation is also available. KVM_VM_MIPS_TE (0) must be passed 4274to KVM_CREATE_VM to create a VM which utilises it. 4275 4276If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is 4277available, it means that the VM is using trap & emulate. 4278 42798.7 KVM_CAP_MIPS_64BIT 4280 4281Architectures: mips 4282 4283This capability indicates the supported architecture type of the guest, i.e. the 4284supported register and address width. 4285 4286The values returned when this capability is checked by KVM_CHECK_EXTENSION on a 4287kvm VM handle correspond roughly to the CP0_Config.AT register field, and should 4288be checked specifically against known values (see below). All other values are 4289reserved. 4290 4291 0: MIPS32 or microMIPS32. 4292 Both registers and addresses are 32-bits wide. 4293 It will only be possible to run 32-bit guest code. 4294 4295 1: MIPS64 or microMIPS64 with access only to 32-bit compatibility segments. 4296 Registers are 64-bits wide, but addresses are 32-bits wide. 4297 64-bit guest code may run but cannot access MIPS64 memory segments. 4298 It will also be possible to run 32-bit guest code. 4299 4300 2: MIPS64 or microMIPS64 with access to all address segments. 4301 Both registers and addresses are 64-bits wide. 4302 It will be possible to run 64-bit or 32-bit guest code. 4303 43048.8 KVM_CAP_X86_GUEST_MWAIT 4305 4306Architectures: x86 4307 4308This capability indicates that guest using memory monotoring instructions 4309(MWAIT/MWAITX) to stop the virtual CPU will not cause a VM exit. As such time 4310spent while virtual CPU is halted in this way will then be accounted for as 4311guest running time on the host (as opposed to e.g. HLT). 4312 43138.9 KVM_CAP_ARM_USER_IRQ 4314 4315Architectures: arm, arm64 4316This capability, if KVM_CHECK_EXTENSION indicates that it is available, means 4317that if userspace creates a VM without an in-kernel interrupt controller, it 4318will be notified of changes to the output level of in-kernel emulated devices, 4319which can generate virtual interrupts, presented to the VM. 4320For such VMs, on every return to userspace, the kernel 4321updates the vcpu's run->s.regs.device_irq_level field to represent the actual 4322output level of the device. 4323 4324Whenever kvm detects a change in the device output level, kvm guarantees at 4325least one return to userspace before running the VM. This exit could either 4326be a KVM_EXIT_INTR or any other exit event, like KVM_EXIT_MMIO. This way, 4327userspace can always sample the device output level and re-compute the state of 4328the userspace interrupt controller. Userspace should always check the state 4329of run->s.regs.device_irq_level on every kvm exit. 4330The value in run->s.regs.device_irq_level can represent both level and edge 4331triggered interrupt signals, depending on the device. Edge triggered interrupt 4332signals will exit to userspace with the bit in run->s.regs.device_irq_level 4333set exactly once per edge signal. 4334 4335The field run->s.regs.device_irq_level is available independent of 4336run->kvm_valid_regs or run->kvm_dirty_regs bits. 4337 4338If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a 4339number larger than 0 indicating the version of this capability is implemented 4340and thereby which bits in in run->s.regs.device_irq_level can signal values. 4341 4342Currently the following bits are defined for the device_irq_level bitmap: 4343 4344 KVM_CAP_ARM_USER_IRQ >= 1: 4345 4346 KVM_ARM_DEV_EL1_VTIMER - EL1 virtual timer 4347 KVM_ARM_DEV_EL1_PTIMER - EL1 physical timer 4348 KVM_ARM_DEV_PMU - ARM PMU overflow interrupt signal 4349 4350Future versions of kvm may implement additional events. These will get 4351indicated by returning a higher number from KVM_CHECK_EXTENSION and will be 4352listed above. 4353 43548.10 KVM_CAP_PPC_SMT_POSSIBLE 4355 4356Architectures: ppc 4357 4358Querying this capability returns a bitmap indicating the possible 4359virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N 4360(counting from the right) is set, then a virtual SMT mode of 2^N is 4361available. 4362 43638.11 KVM_CAP_HYPERV_SYNIC2 4364 4365Architectures: x86 4366 4367This capability enables a newer version of Hyper-V Synthetic interrupt 4368controller (SynIC). The only difference with KVM_CAP_HYPERV_SYNIC is that KVM 4369doesn't clear SynIC message and event flags pages when they are enabled by 4370writing to the respective MSRs. 4371 43728.12 KVM_CAP_HYPERV_VP_INDEX 4373 4374Architectures: x86 4375 4376This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Its 4377value is used to denote the target vcpu for a SynIC interrupt. For 4378compatibilty, KVM initializes this msr to KVM's internal vcpu index. When this 4379capability is absent, userspace can still query this msr's value. 4380