Documentation/virtual/kvm/api.txt

   1 The Definitive KVM (Kernel-based Virtual Machine) API Documentation
   2 ===================================================================
   3
   4 1. General description
   5
   6 The kvm API is a set of ioctls that are issued to control various aspects
   7 of a virtual machine.  The ioctls belong to three classes
   8
   9  - System ioctls: These query and set global attributes which affect the
  10    whole kvm subsystem.  In addition a system ioctl is used to create
  11    virtual machines
  12
  13  - VM ioctls: These query and set attributes that affect an entire virtual
  14    machine, for example memory layout.  In addition a VM ioctl is used to
  15    create virtual cpus (vcpus).
  16
  17    Only run VM ioctls from the same process (address space) that was used
  18    to create the VM.
  19
  20  - vcpu ioctls: These query and set attributes that control the operation
  21    of a single virtual cpu.
  22
  23    Only run vcpu ioctls from the same thread that was used to create the
  24    vcpu.
  25
  26 2. File descriptors
  27
  28 The kvm API is centered around file descriptors.  An initial
  29 open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
  30 can be used to issue system ioctls.  A KVM_CREATE_VM ioctl on this
  31 handle will create a VM file descriptor which can be used to issue VM
  32 ioctls.  A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu
  33 and return a file descriptor pointing to it.  Finally, ioctls on a vcpu
  34 fd can be used to control the vcpu, including the important task of
  35 actually running guest code.
  36
  37 In general file descriptors can be migrated among processes by means
  38 of fork() and the SCM_RIGHTS facility of unix domain socket.  These
  39 kinds of tricks are explicitly not supported by kvm.  While they will
  40 not cause harm to the host, their actual behavior is not guaranteed by
  41 the API.  The only supported use is one virtual machine per process,
  42 and one vcpu per thread.
  43
  44 3. Extensions
  45
  46 As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
  47 incompatible change are allowed.  However, there is an extension
  48 facility that allows backward-compatible extensions to the API to be
  49 queried and used.
  50
  51 The extension mechanism is not based on on the Linux version number.
  52 Instead, kvm defines extension identifiers and a facility to query
  53 whether a particular extension identifier is available.  If it is, a
  54 set of ioctls is available for application use.
  55
  56 4. API description
  57
  58 This section describes ioctls that can be used to control kvm guests.
  59 For each ioctl, the following information is provided along with a
  60 description:
  61
  62   Capability: which KVM extension provides this ioctl.  Can be 'basic',
  63       which means that is will be provided by any kernel that supports
  64       API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which
  65       means availability needs to be checked with KVM_CHECK_EXTENSION
  66       (see section 4.4).
  67
  68   Architectures: which instruction set architectures provide this ioctl.
  69       x86 includes both i386 and x86_64.
  70
  71   Type: system, vm, or vcpu.
  72
  73   Parameters: what parameters are accepted by the ioctl.
  74
  75   Returns: the return value.  General error numbers (EBADF, ENOMEM, EINVAL)
  76       are not detailed, but errors with specific meanings are.
  77
  78 4.1 KVM_GET_API_VERSION
  79
  80 Capability: basic
  81 Architectures: all
  82 Type: system ioctl
  83 Parameters: none
  84 Returns: the constant KVM_API_VERSION (=12)
  85
  86 This identifies the API version as the stable kvm API. It is not
  87 expected that this number will change.  However, Linux 2.6.20 and
  88 2.6.21 report earlier versions; these are not documented and not
  89 supported.  Applications should refuse to run if KVM_GET_API_VERSION
  90 returns a value other than 12.  If this check passes, all ioctls
  91 described as 'basic' will be available.
  92
  93 4.2 KVM_CREATE_VM
  94
  95 Capability: basic
  96 Architectures: all
  97 Type: system ioctl
  98 Parameters: none
  99 Returns: a VM fd that can be used to control the new virtual machine.
 100
 101 The new VM has no virtual cpus and no memory.  An mmap() of a VM fd
 102 will access the virtual machine's physical address space; offset zero
 103 corresponds to guest physical address zero.  Use of mmap() on a VM fd
 104 is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is
 105 available.
 106
 107 4.3 KVM_GET_MSR_INDEX_LIST
 108
 109 Capability: basic
 110 Architectures: x86
 111 Type: system
 112 Parameters: struct kvm_msr_list (in/out)
 113 Returns: 0 on success; -1 on error
 114 Errors:
 115   E2BIG:     the msr index list is to be to fit in the array specified by
 116              the user.
 117
 118 struct kvm_msr_list {
 119         __u32 nmsrs; /* number of msrs in entries */
 120         __u32 indices[0];
 121 };
 122
 123 This ioctl returns the guest msrs that are supported.  The list varies
 124 by kvm version and host processor, but does not change otherwise.  The
 125 user fills in the size of the indices array in nmsrs, and in return
 126 kvm adjusts nmsrs to reflect the actual number of msrs and fills in
 127 the indices array with their numbers.
 128
 129 Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
 130 not returned in the MSR list, as different vcpus can have a different number
 131 of banks, as set via the KVM_X86_SETUP_MCE ioctl.
 132
 133 4.4 KVM_CHECK_EXTENSION
 134
 135 Capability: basic
 136 Architectures: all
 137 Type: system ioctl
 138 Parameters: extension identifier (KVM_CAP_*)
 139 Returns: 0 if unsupported; 1 (or some other positive integer) if supported
 140
 141 The API allows the application to query about extensions to the core
 142 kvm API.  Userspace passes an extension identifier (an integer) and
 143 receives an integer that describes the extension availability.
 144 Generally 0 means no and 1 means yes, but some extensions may report
 145 additional information in the integer return value.
 146
 147 4.5 KVM_GET_VCPU_MMAP_SIZE
 148
 149 Capability: basic
 150 Architectures: all
 151 Type: system ioctl
 152 Parameters: none
 153 Returns: size of vcpu mmap area, in bytes
 154
 155 The KVM_RUN ioctl (cf.) communicates with userspace via a shared
 156 memory region.  This ioctl returns the size of that region.  See the
 157 KVM_RUN documentation for details.
 158
 159 4.6 KVM_SET_MEMORY_REGION
 160
 161 Capability: basic
 162 Architectures: all
 163 Type: vm ioctl
 164 Parameters: struct kvm_memory_region (in)
 165 Returns: 0 on success, -1 on error
 166
 167 This ioctl is obsolete and has been removed.
 168
 169 4.7 KVM_CREATE_VCPU
 170
 171 Capability: basic
 172 Architectures: all
 173 Type: vm ioctl
 174 Parameters: vcpu id (apic id on x86)
 175 Returns: vcpu fd on success, -1 on error
 176
 177 This API adds a vcpu to a virtual machine.  The vcpu id is a small integer
 178 in the range [0, max_vcpus).
 179
 180 The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of
 181 the KVM_CHECK_EXTENSION ioctl() at run-time.
 182 The maximum possible value for max_vcpus can be retrieved using the
 183 KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.
 184
 185 If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
 186 cpus max.
 187 If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is
 188 same as the value returned from KVM_CAP_NR_VCPUS.
 189
 190 On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
 191 threads in one or more virtual CPU cores.  (This is because the
 192 hardware requires all the hardware threads in a CPU core to be in the
 193 same partition.)  The KVM_CAP_PPC_SMT capability indicates the number
 194 of vcpus per virtual core (vcore).  The vcore id is obtained by
 195 dividing the vcpu id by the number of vcpus per vcore.  The vcpus in a
 196 given vcore will always be in the same physical core as each other
 197 (though that might be a different physical core from time to time).
 198 Userspace can control the threading (SMT) mode of the guest by its
 199 allocation of vcpu ids.  For example, if userspace wants
 200 single-threaded guest vcpus, it should make all vcpu ids be a multiple
 201 of the number of vcpus per vcore.
 202
 203 On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
 204 threads in one or more virtual CPU cores.  (This is because the
 205 hardware requires all the hardware threads in a CPU core to be in the
 206 same partition.)  The KVM_CAP_PPC_SMT capability indicates the number
 207 of vcpus per virtual core (vcore).  The vcore id is obtained by
 208 dividing the vcpu id by the number of vcpus per vcore.  The vcpus in a
 209 given vcore will always be in the same physical core as each other
 210 (though that might be a different physical core from time to time).
 211 Userspace can control the threading (SMT) mode of the guest by its
 212 allocation of vcpu ids.  For example, if userspace wants
 213 single-threaded guest vcpus, it should make all vcpu ids be a multiple
 214 of the number of vcpus per vcore.
 215
 216 4.8 KVM_GET_DIRTY_LOG (vm ioctl)
 217
 218 Capability: basic
 219 Architectures: x86
 220 Type: vm ioctl
 221 Parameters: struct kvm_dirty_log (in/out)
 222 Returns: 0 on success, -1 on error
 223
 224 /* for KVM_GET_DIRTY_LOG */
 225 struct kvm_dirty_log {
 226         __u32 slot;
 227         __u32 padding;
 228         union {
 229                 void __user *dirty_bitmap; /* one bit per page */
 230                 __u64 padding;
 231         };
 232 };
 233
 234 Given a memory slot, return a bitmap containing any pages dirtied
 235 since the last call to this ioctl.  Bit 0 is the first page in the
 236 memory slot.  Ensure the entire structure is cleared to avoid padding
 237 issues.
 238
 239 4.9 KVM_SET_MEMORY_ALIAS
 240
 241 Capability: basic
 242 Architectures: x86
 243 Type: vm ioctl
 244 Parameters: struct kvm_memory_alias (in)
 245 Returns: 0 (success), -1 (error)
 246
 247 This ioctl is obsolete and has been removed.
 248
 249 4.10 KVM_RUN
 250
 251 Capability: basic
 252 Architectures: all
 253 Type: vcpu ioctl
 254 Parameters: none
 255 Returns: 0 on success, -1 on error
 256 Errors:
 257   EINTR:     an unmasked signal is pending
 258
 259 This ioctl is used to run a guest virtual cpu.  While there are no
 260 explicit parameters, there is an implicit parameter block that can be
 261 obtained by mmap()ing the vcpu fd at offset 0, with the size given by
 262 KVM_GET_VCPU_MMAP_SIZE.  The parameter block is formatted as a 'struct
 263 kvm_run' (see below).
 264
 265 4.11 KVM_GET_REGS
 266
 267 Capability: basic
 268 Architectures: all
 269 Type: vcpu ioctl
 270 Parameters: struct kvm_regs (out)
 271 Returns: 0 on success, -1 on error
 272
 273 Reads the general purpose registers from the vcpu.
 274
 275 /* x86 */
 276 struct kvm_regs {
 277         /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
 278         __u64 rax, rbx, rcx, rdx;
 279         __u64 rsi, rdi, rsp, rbp;
 280         __u64 r8,  r9,  r10, r11;
 281         __u64 r12, r13, r14, r15;
 282         __u64 rip, rflags;
 283 };
 284
 285 4.12 KVM_SET_REGS
 286
 287 Capability: basic
 288 Architectures: all
 289 Type: vcpu ioctl
 290 Parameters: struct kvm_regs (in)
 291 Returns: 0 on success, -1 on error
 292
 293 Writes the general purpose registers into the vcpu.
 294
 295 See KVM_GET_REGS for the data structure.
 296
 297 4.13 KVM_GET_SREGS
 298
 299 Capability: basic
 300 Architectures: x86, ppc
 301 Type: vcpu ioctl
 302 Parameters: struct kvm_sregs (out)
 303 Returns: 0 on success, -1 on error
 304
 305 Reads special registers from the vcpu.
 306
 307 /* x86 */
 308 struct kvm_sregs {
 309         struct kvm_segment cs, ds, es, fs, gs, ss;
 310         struct kvm_segment tr, ldt;
 311         struct kvm_dtable gdt, idt;
 312         __u64 cr0, cr2, cr3, cr4, cr8;
 313         __u64 efer;
 314         __u64 apic_base;
 315         __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
 316 };
 317
 318 /* ppc -- see arch/powerpc/include/asm/kvm.h */
 319
 320 interrupt_bitmap is a bitmap of pending external interrupts.  At most
 321 one bit may be set.  This interrupt has been acknowledged by the APIC
 322 but not yet injected into the cpu core.
 323
 324 4.14 KVM_SET_SREGS
 325
 326 Capability: basic
 327 Architectures: x86, ppc
 328 Type: vcpu ioctl
 329 Parameters: struct kvm_sregs (in)
 330 Returns: 0 on success, -1 on error
 331
 332 Writes special registers into the vcpu.  See KVM_GET_SREGS for the
 333 data structures.
 334
 335 4.15 KVM_TRANSLATE
 336
 337 Capability: basic
 338 Architectures: x86
 339 Type: vcpu ioctl
 340 Parameters: struct kvm_translation (in/out)
 341 Returns: 0 on success, -1 on error
 342
 343 Translates a virtual address according to the vcpu's current address
 344 translation mode.
 345
 346 struct kvm_translation {
 347         /* in */
 348         __u64 linear_address;
 349
 350         /* out */
 351         __u64 physical_address;
 352         __u8  valid;
 353         __u8  writeable;
 354         __u8  usermode;
 355         __u8  pad[5];
 356 };
 357
 358 4.16 KVM_INTERRUPT
 359
 360 Capability: basic
 361 Architectures: x86, ppc
 362 Type: vcpu ioctl
 363 Parameters: struct kvm_interrupt (in)
 364 Returns: 0 on success, -1 on error
 365
 366 Queues a hardware interrupt vector to be injected.  This is only
 367 useful if in-kernel local APIC or equivalent is not used.
 368
 369 /* for KVM_INTERRUPT */
 370 struct kvm_interrupt {
 371         /* in */
 372         __u32 irq;
 373 };
 374
 375 X86:
 376
 377 Note 'irq' is an interrupt vector, not an interrupt pin or line.
 378
 379 PPC:
 380
 381 Queues an external interrupt to be injected. This ioctl is overleaded
 382 with 3 different irq values:
 383
 384 a) KVM_INTERRUPT_SET
 385
 386   This injects an edge type external interrupt into the guest once it's ready
 387   to receive interrupts. When injected, the interrupt is done.
 388
 389 b) KVM_INTERRUPT_UNSET
 390
 391   This unsets any pending interrupt.
 392
 393   Only available with KVM_CAP_PPC_UNSET_IRQ.
 394
 395 c) KVM_INTERRUPT_SET_LEVEL
 396
 397   This injects a level type external interrupt into the guest context. The
 398   interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
 399   is triggered.
 400
 401   Only available with KVM_CAP_PPC_IRQ_LEVEL.
 402
 403 Note that any value for 'irq' other than the ones stated above is invalid
 404 and incurs unexpected behavior.
 405
 406 4.17 KVM_DEBUG_GUEST
 407
 408 Capability: basic
 409 Architectures: none
 410 Type: vcpu ioctl
 411 Parameters: none)
 412 Returns: -1 on error
 413
 414 Support for this has been removed.  Use KVM_SET_GUEST_DEBUG instead.
 415
 416 4.18 KVM_GET_MSRS
 417
 418 Capability: basic
 419 Architectures: x86
 420 Type: vcpu ioctl
 421 Parameters: struct kvm_msrs (in/out)
 422 Returns: 0 on success, -1 on error
 423
 424 Reads model-specific registers from the vcpu.  Supported msr indices can
 425 be obtained using KVM_GET_MSR_INDEX_LIST.
 426
 427 struct kvm_msrs {
 428         __u32 nmsrs; /* number of msrs in entries */
 429         __u32 pad;
 430
 431         struct kvm_msr_entry entries[0];
 432 };
 433
 434 struct kvm_msr_entry {
 435         __u32 index;
 436         __u32 reserved;
 437         __u64 data;
 438 };
 439
 440 Application code should set the 'nmsrs' member (which indicates the
 441 size of the entries array) and the 'index' member of each array entry.
 442 kvm will fill in the 'data' member.
 443
 444 4.19 KVM_SET_MSRS
 445
 446 Capability: basic
 447 Architectures: x86
 448 Type: vcpu ioctl
 449 Parameters: struct kvm_msrs (in)
 450 Returns: 0 on success, -1 on error
 451
 452 Writes model-specific registers to the vcpu.  See KVM_GET_MSRS for the
 453 data structures.
 454
 455 Application code should set the 'nmsrs' member (which indicates the
 456 size of the entries array), and the 'index' and 'data' members of each
 457 array entry.
 458
 459 4.20 KVM_SET_CPUID
 460
 461 Capability: basic
 462 Architectures: x86
 463 Type: vcpu ioctl
 464 Parameters: struct kvm_cpuid (in)
 465 Returns: 0 on success, -1 on error
 466
 467 Defines the vcpu responses to the cpuid instruction.  Applications
 468 should use the KVM_SET_CPUID2 ioctl if available.
 469
 470
 471 struct kvm_cpuid_entry {
 472         __u32 function;
 473         __u32 eax;
 474         __u32 ebx;
 475         __u32 ecx;
 476         __u32 edx;
 477         __u32 padding;
 478 };
 479
 480 /* for KVM_SET_CPUID */
 481 struct kvm_cpuid {
 482         __u32 nent;
 483         __u32 padding;
 484         struct kvm_cpuid_entry entries[0];
 485 };
 486
 487 4.21 KVM_SET_SIGNAL_MASK
 488
 489 Capability: basic
 490 Architectures: x86
 491 Type: vcpu ioctl
 492 Parameters: struct kvm_signal_mask (in)
 493 Returns: 0 on success, -1 on error
 494
 495 Defines which signals are blocked during execution of KVM_RUN.  This
 496 signal mask temporarily overrides the threads signal mask.  Any
 497 unblocked signal received (except SIGKILL and SIGSTOP, which retain
 498 their traditional behaviour) will cause KVM_RUN to return with -EINTR.
 499
 500 Note the signal will only be delivered if not blocked by the original
 501 signal mask.
 502
 503 /* for KVM_SET_SIGNAL_MASK */
 504 struct kvm_signal_mask {
 505         __u32 len;
 506         __u8  sigset[0];
 507 };
 508
 509 4.22 KVM_GET_FPU
 510
 511 Capability: basic
 512 Architectures: x86
 513 Type: vcpu ioctl
 514 Parameters: struct kvm_fpu (out)
 515 Returns: 0 on success, -1 on error
 516
 517 Reads the floating point state from the vcpu.
 518
 519 /* for KVM_GET_FPU and KVM_SET_FPU */
 520 struct kvm_fpu {
 521         __u8  fpr[8][16];
 522         __u16 fcw;
 523         __u16 fsw;
 524         __u8  ftwx;  /* in fxsave format */
 525         __u8  pad1;
 526         __u16 last_opcode;
 527         __u64 last_ip;
 528         __u64 last_dp;
 529         __u8  xmm[16][16];
 530         __u32 mxcsr;
 531         __u32 pad2;
 532 };
 533
 534 4.23 KVM_SET_FPU
 535
 536 Capability: basic
 537 Architectures: x86
 538 Type: vcpu ioctl
 539 Parameters: struct kvm_fpu (in)
 540 Returns: 0 on success, -1 on error
 541
 542 Writes the floating point state to the vcpu.
 543
 544 /* for KVM_GET_FPU and KVM_SET_FPU */
 545 struct kvm_fpu {
 546         __u8  fpr[8][16];
 547         __u16 fcw;
 548         __u16 fsw;
 549         __u8  ftwx;  /* in fxsave format */
 550         __u8  pad1;
 551         __u16 last_opcode;
 552         __u64 last_ip;
 553         __u64 last_dp;
 554         __u8  xmm[16][16];
 555         __u32 mxcsr;
 556         __u32 pad2;
 557 };
 558
 559 4.24 KVM_CREATE_IRQCHIP
 560
 561 Capability: KVM_CAP_IRQCHIP
 562 Architectures: x86, ia64
 563 Type: vm ioctl
 564 Parameters: none
 565 Returns: 0 on success, -1 on error
 566
 567 Creates an interrupt controller model in the kernel.  On x86, creates a virtual
 568 ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a
 569 local APIC.  IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23
 570 only go to the IOAPIC.  On ia64, a IOSAPIC is created.
 571
 572 4.25 KVM_IRQ_LINE
 573
 574 Capability: KVM_CAP_IRQCHIP
 575 Architectures: x86, ia64
 576 Type: vm ioctl
 577 Parameters: struct kvm_irq_level
 578 Returns: 0 on success, -1 on error
 579
 580 Sets the level of a GSI input to the interrupt controller model in the kernel.
 581 Requires that an interrupt controller model has been previously created with
 582 KVM_CREATE_IRQCHIP.  Note that edge-triggered interrupts require the level
 583 to be set to 1 and then back to 0.
 584
 585 struct kvm_irq_level {
 586         union {
 587                 __u32 irq;     /* GSI */
 588                 __s32 status;  /* not used for KVM_IRQ_LEVEL */
 589         };
 590         __u32 level;           /* 0 or 1 */
 591 };
 592
 593 4.26 KVM_GET_IRQCHIP
 594
 595 Capability: KVM_CAP_IRQCHIP
 596 Architectures: x86, ia64
 597 Type: vm ioctl
 598 Parameters: struct kvm_irqchip (in/out)
 599 Returns: 0 on success, -1 on error
 600
 601 Reads the state of a kernel interrupt controller created with
 602 KVM_CREATE_IRQCHIP into a buffer provided by the caller.
 603
 604 struct kvm_irqchip {
 605         __u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
 606         __u32 pad;
 607         union {
 608                 char dummy[512];  /* reserving space */
 609                 struct kvm_pic_state pic;
 610                 struct kvm_ioapic_state ioapic;
 611         } chip;
 612 };
 613
 614 4.27 KVM_SET_IRQCHIP
 615
 616 Capability: KVM_CAP_IRQCHIP
 617 Architectures: x86, ia64
 618 Type: vm ioctl
 619 Parameters: struct kvm_irqchip (in)
 620 Returns: 0 on success, -1 on error
 621
 622 Sets the state of a kernel interrupt controller created with
 623 KVM_CREATE_IRQCHIP from a buffer provided by the caller.
 624
 625 struct kvm_irqchip {
 626         __u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
 627         __u32 pad;
 628         union {
 629                 char dummy[512];  /* reserving space */
 630                 struct kvm_pic_state pic;
 631                 struct kvm_ioapic_state ioapic;
 632         } chip;
 633 };
 634
 635 4.28 KVM_XEN_HVM_CONFIG
 636
 637 Capability: KVM_CAP_XEN_HVM
 638 Architectures: x86
 639 Type: vm ioctl
 640 Parameters: struct kvm_xen_hvm_config (in)
 641 Returns: 0 on success, -1 on error
 642
 643 Sets the MSR that the Xen HVM guest uses to initialize its hypercall
 644 page, and provides the starting address and size of the hypercall
 645 blobs in userspace.  When the guest writes the MSR, kvm copies one
 646 page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
 647 memory.
 648
 649 struct kvm_xen_hvm_config {
 650         __u32 flags;
 651         __u32 msr;
 652         __u64 blob_addr_32;
 653         __u64 blob_addr_64;
 654         __u8 blob_size_32;
 655         __u8 blob_size_64;
 656         __u8 pad2[30];
 657 };
 658
 659 4.29 KVM_GET_CLOCK
 660
 661 Capability: KVM_CAP_ADJUST_CLOCK
 662 Architectures: x86
 663 Type: vm ioctl
 664 Parameters: struct kvm_clock_data (out)
 665 Returns: 0 on success, -1 on error
 666
 667 Gets the current timestamp of kvmclock as seen by the current guest. In
 668 conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
 669 such as migration.
 670
 671 struct kvm_clock_data {
 672         __u64 clock;  /* kvmclock current value */
 673         __u32 flags;
 674         __u32 pad[9];
 675 };
 676
 677 4.30 KVM_SET_CLOCK
 678
 679 Capability: KVM_CAP_ADJUST_CLOCK
 680 Architectures: x86
 681 Type: vm ioctl
 682 Parameters: struct kvm_clock_data (in)
 683 Returns: 0 on success, -1 on error
 684
 685 Sets the current timestamp of kvmclock to the value specified in its parameter.
 686 In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
 687 such as migration.
 688
 689 struct kvm_clock_data {
 690         __u64 clock;  /* kvmclock current value */
 691         __u32 flags;
 692         __u32 pad[9];
 693 };
 694
 695 4.31 KVM_GET_VCPU_EVENTS
 696
 697 Capability: KVM_CAP_VCPU_EVENTS
 698 Extended by: KVM_CAP_INTR_SHADOW
 699 Architectures: x86
 700 Type: vm ioctl
 701 Parameters: struct kvm_vcpu_event (out)
 702 Returns: 0 on success, -1 on error
 703
 704 Gets currently pending exceptions, interrupts, and NMIs as well as related
 705 states of the vcpu.
 706
 707 struct kvm_vcpu_events {
 708         struct {
 709                 __u8 injected;
 710                 __u8 nr;
 711                 __u8 has_error_code;
 712                 __u8 pad;
 713                 __u32 error_code;
 714         } exception;
 715         struct {
 716                 __u8 injected;
 717                 __u8 nr;
 718                 __u8 soft;
 719                 __u8 shadow;
 720         } interrupt;
 721         struct {
 722                 __u8 injected;
 723                 __u8 pending;
 724                 __u8 masked;
 725                 __u8 pad;
 726         } nmi;
 727         __u32 sipi_vector;
 728         __u32 flags;
 729 };
 730
 731 KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
 732 interrupt.shadow contains a valid state. Otherwise, this field is undefined.
 733
 734 4.32 KVM_SET_VCPU_EVENTS
 735
 736 Capability: KVM_CAP_VCPU_EVENTS
 737 Extended by: KVM_CAP_INTR_SHADOW
 738 Architectures: x86
 739 Type: vm ioctl
 740 Parameters: struct kvm_vcpu_event (in)
 741 Returns: 0 on success, -1 on error
 742
 743 Set pending exceptions, interrupts, and NMIs as well as related states of the
 744 vcpu.
 745
 746 See KVM_GET_VCPU_EVENTS for the data structure.
 747
 748 Fields that may be modified asynchronously by running VCPUs can be excluded
 749 from the update. These fields are nmi.pending and sipi_vector. Keep the
 750 corresponding bits in the flags field cleared to suppress overwriting the
 751 current in-kernel state. The bits are:
 752
 753 KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
 754 KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
 755
 756 If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
 757 the flags field to signal that interrupt.shadow contains a valid state and
 758 shall be written into the VCPU.
 759
 760 4.33 KVM_GET_DEBUGREGS
 761
 762 Capability: KVM_CAP_DEBUGREGS
 763 Architectures: x86
 764 Type: vm ioctl
 765 Parameters: struct kvm_debugregs (out)
 766 Returns: 0 on success, -1 on error
 767
 768 Reads debug registers from the vcpu.
 769
 770 struct kvm_debugregs {
 771         __u64 db[4];
 772         __u64 dr6;
 773         __u64 dr7;
 774         __u64 flags;
 775         __u64 reserved[9];
 776 };
 777
 778 4.34 KVM_SET_DEBUGREGS
 779
 780 Capability: KVM_CAP_DEBUGREGS
 781 Architectures: x86
 782 Type: vm ioctl
 783 Parameters: struct kvm_debugregs (in)
 784 Returns: 0 on success, -1 on error
 785
 786 Writes debug registers into the vcpu.
 787
 788 See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
 789 yet and must be cleared on entry.
 790
 791 4.35 KVM_SET_USER_MEMORY_REGION
 792
 793 Capability: KVM_CAP_USER_MEM
 794 Architectures: all
 795 Type: vm ioctl
 796 Parameters: struct kvm_userspace_memory_region (in)
 797 Returns: 0 on success, -1 on error
 798
 799 struct kvm_userspace_memory_region {
 800         __u32 slot;
 801         __u32 flags;
 802         __u64 guest_phys_addr;
 803         __u64 memory_size; /* bytes */
 804         __u64 userspace_addr; /* start of the userspace allocated memory */
 805 };
 806
 807 /* for kvm_memory_region::flags */
 808 #define KVM_MEM_LOG_DIRTY_PAGES  1UL
 809
 810 This ioctl allows the user to create or modify a guest physical memory
 811 slot.  When changing an existing slot, it may be moved in the guest
 812 physical memory space, or its flags may be modified.  It may not be
 813 resized.  Slots may not overlap in guest physical address space.
 814
 815 Memory for the region is taken starting at the address denoted by the
 816 field userspace_addr, which must point at user addressable memory for
 817 the entire memory slot size.  Any object may back this memory, including
 818 anonymous memory, ordinary files, and hugetlbfs.
 819
 820 It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
 821 be identical.  This allows large pages in the guest to be backed by large
 822 pages in the host.
 823
 824 The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which
 825 instructs kvm to keep track of writes to memory within the slot.  See
 826 the KVM_GET_DIRTY_LOG ioctl.
 827
 828 When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory
 829 region are automatically reflected into the guest.  For example, an mmap()
 830 that affects the region will be made visible immediately.  Another example
 831 is madvise(MADV_DROP).
 832
 833 It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
 834 The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
 835 allocation and is deprecated.
 836
 837 4.36 KVM_SET_TSS_ADDR
 838
 839 Capability: KVM_CAP_SET_TSS_ADDR
 840 Architectures: x86
 841 Type: vm ioctl
 842 Parameters: unsigned long tss_address (in)
 843 Returns: 0 on success, -1 on error
 844
 845 This ioctl defines the physical address of a three-page region in the guest
 846 physical address space.  The region must be within the first 4GB of the
 847 guest physical address space and must not conflict with any memory slot
 848 or any mmio address.  The guest may malfunction if it accesses this memory
 849 region.
 850
 851 This ioctl is required on Intel-based hosts.  This is needed on Intel hardware
 852 because of a quirk in the virtualization implementation (see the internals
 853 documentation when it pops into existence).
 854
 855 4.37 KVM_ENABLE_CAP
 856
 857 Capability: KVM_CAP_ENABLE_CAP
 858 Architectures: ppc
 859 Type: vcpu ioctl
 860 Parameters: struct kvm_enable_cap (in)
 861 Returns: 0 on success; -1 on error
 862
 863 +Not all extensions are enabled by default. Using this ioctl the application
 864 can enable an extension, making it available to the guest.
 865
 866 On systems that do not support this ioctl, it always fails. On systems that
 867 do support it, it only works for extensions that are supported for enablement.
 868
 869 To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
 870 be used.
 871
 872 struct kvm_enable_cap {
 873        /* in */
 874        __u32 cap;
 875
 876 The capability that is supposed to get enabled.
 877
 878        __u32 flags;
 879
 880 A bitfield indicating future enhancements. Has to be 0 for now.
 881
 882        __u64 args[4];
 883
 884 Arguments for enabling a feature. If a feature needs initial values to
 885 function properly, this is the place to put them.
 886
 887        __u8  pad[64];
 888 };
 889
 890 4.38 KVM_GET_MP_STATE
 891
 892 Capability: KVM_CAP_MP_STATE
 893 Architectures: x86, ia64
 894 Type: vcpu ioctl
 895 Parameters: struct kvm_mp_state (out)
 896 Returns: 0 on success; -1 on error
 897
 898 struct kvm_mp_state {
 899         __u32 mp_state;
 900 };
 901
 902 Returns the vcpu's current "multiprocessing state" (though also valid on
 903 uniprocessor guests).
 904
 905 Possible values are:
 906
 907  - KVM_MP_STATE_RUNNABLE:        the vcpu is currently running
 908  - KVM_MP_STATE_UNINITIALIZED:   the vcpu is an application processor (AP)
 909                                  which has not yet received an INIT signal
 910  - KVM_MP_STATE_INIT_RECEIVED:   the vcpu has received an INIT signal, and is
 911                                  now ready for a SIPI
 912  - KVM_MP_STATE_HALTED:          the vcpu has executed a HLT instruction and
 913                                  is waiting for an interrupt
 914  - KVM_MP_STATE_SIPI_RECEIVED:   the vcpu has just received a SIPI (vector
 915                                  accessible via KVM_GET_VCPU_EVENTS)
 916
 917 This ioctl is only useful after KVM_CREATE_IRQCHIP.  Without an in-kernel
 918 irqchip, the multiprocessing state must be maintained by userspace.
 919
 920 4.39 KVM_SET_MP_STATE
 921
 922 Capability: KVM_CAP_MP_STATE
 923 Architectures: x86, ia64
 924 Type: vcpu ioctl
 925 Parameters: struct kvm_mp_state (in)
 926 Returns: 0 on success; -1 on error
 927
 928 Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
 929 arguments.
 930
 931 This ioctl is only useful after KVM_CREATE_IRQCHIP.  Without an in-kernel
 932 irqchip, the multiprocessing state must be maintained by userspace.
 933
 934 4.40 KVM_SET_IDENTITY_MAP_ADDR
 935
 936 Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
 937 Architectures: x86
 938 Type: vm ioctl
 939 Parameters: unsigned long identity (in)
 940 Returns: 0 on success, -1 on error
 941
 942 This ioctl defines the physical address of a one-page region in the guest
 943 physical address space.  The region must be within the first 4GB of the
 944 guest physical address space and must not conflict with any memory slot
 945 or any mmio address.  The guest may malfunction if it accesses this memory
 946 region.
 947
 948 This ioctl is required on Intel-based hosts.  This is needed on Intel hardware
 949 because of a quirk in the virtualization implementation (see the internals
 950 documentation when it pops into existence).
 951
 952 4.41 KVM_SET_BOOT_CPU_ID
 953
 954 Capability: KVM_CAP_SET_BOOT_CPU_ID
 955 Architectures: x86, ia64
 956 Type: vm ioctl
 957 Parameters: unsigned long vcpu_id
 958 Returns: 0 on success, -1 on error
 959
 960 Define which vcpu is the Bootstrap Processor (BSP).  Values are the same
 961 as the vcpu id in KVM_CREATE_VCPU.  If this ioctl is not called, the default
 962 is vcpu 0.
 963
 964 4.42 KVM_GET_XSAVE
 965
 966 Capability: KVM_CAP_XSAVE
 967 Architectures: x86
 968 Type: vcpu ioctl
 969 Parameters: struct kvm_xsave (out)
 970 Returns: 0 on success, -1 on error
 971
 972 struct kvm_xsave {
 973         __u32 region[1024];
 974 };
 975
 976 This ioctl would copy current vcpu's xsave struct to the userspace.
 977
 978 4.43 KVM_SET_XSAVE
 979
 980 Capability: KVM_CAP_XSAVE
 981 Architectures: x86
 982 Type: vcpu ioctl
 983 Parameters: struct kvm_xsave (in)
 984 Returns: 0 on success, -1 on error
 985
 986 struct kvm_xsave {
 987         __u32 region[1024];
 988 };
 989
 990 This ioctl would copy userspace's xsave struct to the kernel.
 991
 992 4.44 KVM_GET_XCRS
 993
 994 Capability: KVM_CAP_XCRS
 995 Architectures: x86
 996 Type: vcpu ioctl
 997 Parameters: struct kvm_xcrs (out)
 998 Returns: 0 on success, -1 on error
 999
1000 struct kvm_xcr {
1001         __u32 xcr;
1002         __u32 reserved;
1003         __u64 value;
1004 };
1005
1006 struct kvm_xcrs {
1007         __u32 nr_xcrs;
1008         __u32 flags;
1009         struct kvm_xcr xcrs[KVM_MAX_XCRS];
1010         __u64 padding[16];
1011 };
1012
1013 This ioctl would copy current vcpu's xcrs to the userspace.
1014
1015 4.45 KVM_SET_XCRS
1016
1017 Capability: KVM_CAP_XCRS
1018 Architectures: x86
1019 Type: vcpu ioctl
1020 Parameters: struct kvm_xcrs (in)
1021 Returns: 0 on success, -1 on error
1022
1023 struct kvm_xcr {
1024         __u32 xcr;
1025         __u32 reserved;
1026         __u64 value;
1027 };
1028
1029 struct kvm_xcrs {
1030         __u32 nr_xcrs;
1031         __u32 flags;
1032         struct kvm_xcr xcrs[KVM_MAX_XCRS];
1033         __u64 padding[16];
1034 };
1035
1036 This ioctl would set vcpu's xcr to the value userspace specified.
1037
1038 4.46 KVM_GET_SUPPORTED_CPUID
1039
1040 Capability: KVM_CAP_EXT_CPUID
1041 Architectures: x86
1042 Type: system ioctl
1043 Parameters: struct kvm_cpuid2 (in/out)
1044 Returns: 0 on success, -1 on error
1045
1046 struct kvm_cpuid2 {
1047         __u32 nent;
1048         __u32 padding;
1049         struct kvm_cpuid_entry2 entries[0];
1050 };
1051
1052 #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX 1
1053 #define KVM_CPUID_FLAG_STATEFUL_FUNC    2
1054 #define KVM_CPUID_FLAG_STATE_READ_NEXT  4
1055
1056 struct kvm_cpuid_entry2 {
1057         __u32 function;
1058         __u32 index;
1059         __u32 flags;
1060         __u32 eax;
1061         __u32 ebx;
1062         __u32 ecx;
1063         __u32 edx;
1064         __u32 padding[3];
1065 };
1066
1067 This ioctl returns x86 cpuid features which are supported by both the hardware
1068 and kvm.  Userspace can use the information returned by this ioctl to
1069 construct cpuid information (for KVM_SET_CPUID2) that is consistent with
1070 hardware, kernel, and userspace capabilities, and with user requirements (for
1071 example, the user may wish to constrain cpuid to emulate older hardware,
1072 or for feature consistency across a cluster).
1073
1074 Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1075 with the 'nent' field indicating the number of entries in the variable-size
1076 array 'entries'.  If the number of entries is too low to describe the cpu
1077 capabilities, an error (E2BIG) is returned.  If the number is too high,
1078 the 'nent' field is adjusted and an error (ENOMEM) is returned.  If the
1079 number is just right, the 'nent' field is adjusted to the number of valid
1080 entries in the 'entries' array, which is then filled.
1081
1082 The entries returned are the host cpuid as returned by the cpuid instruction,
1083 with unknown or unsupported features masked out.  Some features (for example,
1084 x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1085 emulate them efficiently. The fields in each entry are defined as follows:
1086
1087   function: the eax value used to obtain the entry
1088   index: the ecx value used to obtain the entry (for entries that are
1089          affected by ecx)
1090   flags: an OR of zero or more of the following:
1091         KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
1092            if the index field is valid
1093         KVM_CPUID_FLAG_STATEFUL_FUNC:
1094            if cpuid for this function returns different values for successive
1095            invocations; there will be several entries with the same function,
1096            all with this flag set
1097         KVM_CPUID_FLAG_STATE_READ_NEXT:
1098            for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
1099            the first entry to be read by a cpu
1100    eax, ebx, ecx, edx: the values returned by the cpuid instruction for
1101          this function/index combination
1102
1103 4.47 KVM_PPC_GET_PVINFO
1104
1105 Capability: KVM_CAP_PPC_GET_PVINFO
1106 Architectures: ppc
1107 Type: vm ioctl
1108 Parameters: struct kvm_ppc_pvinfo (out)
1109 Returns: 0 on success, !0 on error
1110
1111 struct kvm_ppc_pvinfo {
1112         __u32 flags;
1113         __u32 hcall[4];
1114         __u8  pad[108];
1115 };
1116
1117 This ioctl fetches PV specific information that need to be passed to the guest
1118 using the device tree or other means from vm context.
1119
1120 For now the only implemented piece of information distributed here is an array
1121 of 4 instructions that make up a hypercall.
1122
1123 If any additional field gets added to this structure later on, a bit for that
1124 additional piece of information will be set in the flags bitmap.
1125
1126 4.48 KVM_ASSIGN_PCI_DEVICE
1127
1128 Capability: KVM_CAP_DEVICE_ASSIGNMENT
1129 Architectures: x86 ia64
1130 Type: vm ioctl
1131 Parameters: struct kvm_assigned_pci_dev (in)
1132 Returns: 0 on success, -1 on error
1133
1134 Assigns a host PCI device to the VM.
1135
1136 struct kvm_assigned_pci_dev {
1137         __u32 assigned_dev_id;
1138         __u32 busnr;
1139         __u32 devfn;
1140         __u32 flags;
1141         __u32 segnr;
1142         union {
1143                 __u32 reserved[11];
1144         };
1145 };
1146
1147 The PCI device is specified by the triple segnr, busnr, and devfn.
1148 Identification in succeeding service requests is done via assigned_dev_id. The
1149 following flags are specified:
1150
1151 /* Depends on KVM_CAP_IOMMU */
1152 #define KVM_DEV_ASSIGN_ENABLE_IOMMU     (1 << 0)
1153
1154 4.49 KVM_DEASSIGN_PCI_DEVICE
1155
1156 Capability: KVM_CAP_DEVICE_DEASSIGNMENT
1157 Architectures: x86 ia64
1158 Type: vm ioctl
1159 Parameters: struct kvm_assigned_pci_dev (in)
1160 Returns: 0 on success, -1 on error
1161
1162 Ends PCI device assignment, releasing all associated resources.
1163
1164 See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is
1165 used in kvm_assigned_pci_dev to identify the device.
1166
1167 4.50 KVM_ASSIGN_DEV_IRQ
1168
1169 Capability: KVM_CAP_ASSIGN_DEV_IRQ
1170 Architectures: x86 ia64
1171 Type: vm ioctl
1172 Parameters: struct kvm_assigned_irq (in)
1173 Returns: 0 on success, -1 on error
1174
1175 Assigns an IRQ to a passed-through device.
1176
1177 struct kvm_assigned_irq {
1178         __u32 assigned_dev_id;
1179         __u32 host_irq; /* ignored (legacy field) */
1180         __u32 guest_irq;
1181         __u32 flags;
1182         union {
1183                 __u32 reserved[12];
1184         };
1185 };
1186
1187 The following flags are defined:
1188
1189 #define KVM_DEV_IRQ_HOST_INTX    (1 << 0)
1190 #define KVM_DEV_IRQ_HOST_MSI     (1 << 1)
1191 #define KVM_DEV_IRQ_HOST_MSIX    (1 << 2)
1192
1193 #define KVM_DEV_IRQ_GUEST_INTX   (1 << 8)
1194 #define KVM_DEV_IRQ_GUEST_MSI    (1 << 9)
1195 #define KVM_DEV_IRQ_GUEST_MSIX   (1 << 10)
1196
1197 It is not valid to specify multiple types per host or guest IRQ. However, the
1198 IRQ type of host and guest can differ or can even be null.
1199
1200 4.51 KVM_DEASSIGN_DEV_IRQ
1201
1202 Capability: KVM_CAP_ASSIGN_DEV_IRQ
1203 Architectures: x86 ia64
1204 Type: vm ioctl
1205 Parameters: struct kvm_assigned_irq (in)
1206 Returns: 0 on success, -1 on error
1207
1208 Ends an IRQ assignment to a passed-through device.
1209
1210 See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1211 by assigned_dev_id, flags must correspond to the IRQ type specified on
1212 KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed.
1213
1214 4.52 KVM_SET_GSI_ROUTING
1215
1216 Capability: KVM_CAP_IRQ_ROUTING
1217 Architectures: x86 ia64
1218 Type: vm ioctl
1219 Parameters: struct kvm_irq_routing (in)
1220 Returns: 0 on success, -1 on error
1221
1222 Sets the GSI routing table entries, overwriting any previously set entries.
1223
1224 struct kvm_irq_routing {
1225         __u32 nr;
1226         __u32 flags;
1227         struct kvm_irq_routing_entry entries[0];
1228 };
1229
1230 No flags are specified so far, the corresponding field must be set to zero.
1231
1232 struct kvm_irq_routing_entry {
1233         __u32 gsi;
1234         __u32 type;
1235         __u32 flags;
1236         __u32 pad;
1237         union {
1238                 struct kvm_irq_routing_irqchip irqchip;
1239                 struct kvm_irq_routing_msi msi;
1240                 __u32 pad[8];
1241         } u;
1242 };
1243
1244 /* gsi routing entry types */
1245 #define KVM_IRQ_ROUTING_IRQCHIP 1
1246 #define KVM_IRQ_ROUTING_MSI 2
1247
1248 No flags are specified so far, the corresponding field must be set to zero.
1249
1250 struct kvm_irq_routing_irqchip {
1251         __u32 irqchip;
1252         __u32 pin;
1253 };
1254
1255 struct kvm_irq_routing_msi {
1256         __u32 address_lo;
1257         __u32 address_hi;
1258         __u32 data;
1259         __u32 pad;
1260 };
1261
1262 4.53 KVM_ASSIGN_SET_MSIX_NR
1263
1264 Capability: KVM_CAP_DEVICE_MSIX
1265 Architectures: x86 ia64
1266 Type: vm ioctl
1267 Parameters: struct kvm_assigned_msix_nr (in)
1268 Returns: 0 on success, -1 on error
1269
1270 Set the number of MSI-X interrupts for an assigned device. The number is
1271 reset again by terminating the MSI-X assignment of the device via
1272 KVM_DEASSIGN_DEV_IRQ. Calling this service more than once at any earlier
1273 point will fail.
1274
1275 struct kvm_assigned_msix_nr {
1276         __u32 assigned_dev_id;
1277         __u16 entry_nr;
1278         __u16 padding;
1279 };
1280
1281 #define KVM_MAX_MSIX_PER_DEV            256
1282
1283 4.54 KVM_ASSIGN_SET_MSIX_ENTRY
1284
1285 Capability: KVM_CAP_DEVICE_MSIX
1286 Architectures: x86 ia64
1287 Type: vm ioctl
1288 Parameters: struct kvm_assigned_msix_entry (in)
1289 Returns: 0 on success, -1 on error
1290
1291 Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1292 the GSI vector to zero means disabling the interrupt.
1293
1294 struct kvm_assigned_msix_entry {
1295         __u32 assigned_dev_id;
1296         __u32 gsi;
1297         __u16 entry; /* The index of entry in the MSI-X table */
1298         __u16 padding[3];
1299 };
1300
1301 4.54 KVM_SET_TSC_KHZ
1302
1303 Capability: KVM_CAP_TSC_CONTROL
1304 Architectures: x86
1305 Type: vcpu ioctl
1306 Parameters: virtual tsc_khz
1307 Returns: 0 on success, -1 on error
1308
1309 Specifies the tsc frequency for the virtual machine. The unit of the
1310 frequency is KHz.
1311
1312 4.55 KVM_GET_TSC_KHZ
1313
1314 Capability: KVM_CAP_GET_TSC_KHZ
1315 Architectures: x86
1316 Type: vcpu ioctl
1317 Parameters: none
1318 Returns: virtual tsc-khz on success, negative value on error
1319
1320 Returns the tsc frequency of the guest. The unit of the return value is
1321 KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
1322 error.
1323
1324 4.56 KVM_GET_LAPIC
1325
1326 Capability: KVM_CAP_IRQCHIP
1327 Architectures: x86
1328 Type: vcpu ioctl
1329 Parameters: struct kvm_lapic_state (out)
1330 Returns: 0 on success, -1 on error
1331
1332 #define KVM_APIC_REG_SIZE 0x400
1333 struct kvm_lapic_state {
1334         char regs[KVM_APIC_REG_SIZE];
1335 };
1336
1337 Reads the Local APIC registers and copies them into the input argument.  The
1338 data format and layout are the same as documented in the architecture manual.
1339
1340 4.57 KVM_SET_LAPIC
1341
1342 Capability: KVM_CAP_IRQCHIP
1343 Architectures: x86
1344 Type: vcpu ioctl
1345 Parameters: struct kvm_lapic_state (in)
1346 Returns: 0 on success, -1 on error
1347
1348 #define KVM_APIC_REG_SIZE 0x400
1349 struct kvm_lapic_state {
1350         char regs[KVM_APIC_REG_SIZE];
1351 };
1352
1353 Copies the input argument into the the Local APIC registers.  The data format
1354 and layout are the same as documented in the architecture manual.
1355
1356 4.58 KVM_IOEVENTFD
1357
1358 Capability: KVM_CAP_IOEVENTFD
1359 Architectures: all
1360 Type: vm ioctl
1361 Parameters: struct kvm_ioeventfd (in)
1362 Returns: 0 on success, !0 on error
1363
1364 This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
1365 within the guest.  A guest write in the registered address will signal the
1366 provided event instead of triggering an exit.
1367
1368 struct kvm_ioeventfd {
1369         __u64 datamatch;
1370         __u64 addr;        /* legal pio/mmio address */
1371         __u32 len;         /* 1, 2, 4, or 8 bytes    */
1372         __s32 fd;
1373         __u32 flags;
1374         __u8  pad[36];
1375 };
1376
1377 The following flags are defined:
1378
1379 #define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
1380 #define KVM_IOEVENTFD_FLAG_PIO       (1 << kvm_ioeventfd_flag_nr_pio)
1381 #define KVM_IOEVENTFD_FLAG_DEASSIGN  (1 << kvm_ioeventfd_flag_nr_deassign)
1382
1383 If datamatch flag is set, the event will be signaled only if the written value
1384 to the registered address is equal to datamatch in struct kvm_ioeventfd.
1385
1386 4.62 KVM_CREATE_SPAPR_TCE
1387
1388 Capability: KVM_CAP_SPAPR_TCE
1389 Architectures: powerpc
1390 Type: vm ioctl
1391 Parameters: struct kvm_create_spapr_tce (in)
1392 Returns: file descriptor for manipulating the created TCE table
1393
1394 This creates a virtual TCE (translation control entry) table, which
1395 is an IOMMU for PAPR-style virtual I/O.  It is used to translate
1396 logical addresses used in virtual I/O into guest physical addresses,
1397 and provides a scatter/gather capability for PAPR virtual I/O.
1398
1399 /* for KVM_CAP_SPAPR_TCE */
1400 struct kvm_create_spapr_tce {
1401         __u64 liobn;
1402         __u32 window_size;
1403 };
1404
1405 The liobn field gives the logical IO bus number for which to create a
1406 TCE table.  The window_size field specifies the size of the DMA window
1407 which this TCE table will translate - the table will contain one 64
1408 bit TCE entry for every 4kiB of the DMA window.
1409
1410 When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
1411 table has been created using this ioctl(), the kernel will handle it
1412 in real mode, updating the TCE table.  H_PUT_TCE calls for other
1413 liobns will cause a vm exit and must be handled by userspace.
1414
1415 The return value is a file descriptor which can be passed to mmap(2)
1416 to map the created TCE table into userspace.  This lets userspace read
1417 the entries written by kernel-handled H_PUT_TCE calls, and also lets
1418 userspace update the TCE table directly which is useful in some
1419 circumstances.
1420
1421 4.63 KVM_ALLOCATE_RMA
1422
1423 Capability: KVM_CAP_PPC_RMA
1424 Architectures: powerpc
1425 Type: vm ioctl
1426 Parameters: struct kvm_allocate_rma (out)
1427 Returns: file descriptor for mapping the allocated RMA
1428
1429 This allocates a Real Mode Area (RMA) from the pool allocated at boot
1430 time by the kernel.  An RMA is a physically-contiguous, aligned region
1431 of memory used on older POWER processors to provide the memory which
1432 will be accessed by real-mode (MMU off) accesses in a KVM guest.
1433 POWER processors support a set of sizes for the RMA that usually
1434 includes 64MB, 128MB, 256MB and some larger powers of two.
1435
1436 /* for KVM_ALLOCATE_RMA */
1437 struct kvm_allocate_rma {
1438         __u64 rma_size;
1439 };
1440
1441 The return value is a file descriptor which can be passed to mmap(2)
1442 to map the allocated RMA into userspace.  The mapped area can then be
1443 passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the
1444 RMA for a virtual machine.  The size of the RMA in bytes (which is
1445 fixed at host kernel boot time) is returned in the rma_size field of
1446 the argument structure.
1447
1448 The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl
1449 is supported; 2 if the processor requires all virtual machines to have
1450 an RMA, or 1 if the processor can use an RMA but doesn't require it,
1451 because it supports the Virtual RMA (VRMA) facility.
1452
1453 5. The kvm_run structure
1454
1455 Application code obtains a pointer to the kvm_run structure by
1456 mmap()ing a vcpu fd.  From that point, application code can control
1457 execution by changing fields in kvm_run prior to calling the KVM_RUN
1458 ioctl, and obtain information about the reason KVM_RUN returned by
1459 looking up structure members.
1460
1461 struct kvm_run {
1462         /* in */
1463         __u8 request_interrupt_window;
1464
1465 Request that KVM_RUN return when it becomes possible to inject external
1466 interrupts into the guest.  Useful in conjunction with KVM_INTERRUPT.
1467
1468         __u8 padding1[7];
1469
1470         /* out */
1471         __u32 exit_reason;
1472
1473 When KVM_RUN has returned successfully (return value 0), this informs
1474 application code why KVM_RUN has returned.  Allowable values for this
1475 field are detailed below.
1476
1477         __u8 ready_for_interrupt_injection;
1478
1479 If request_interrupt_window has been specified, this field indicates
1480 an interrupt can be injected now with KVM_INTERRUPT.
1481
1482         __u8 if_flag;
1483
1484 The value of the current interrupt flag.  Only valid if in-kernel
1485 local APIC is not used.
1486
1487         __u8 padding2[2];
1488
1489         /* in (pre_kvm_run), out (post_kvm_run) */
1490         __u64 cr8;
1491
1492 The value of the cr8 register.  Only valid if in-kernel local APIC is
1493 not used.  Both input and output.
1494
1495         __u64 apic_base;
1496
1497 The value of the APIC BASE msr.  Only valid if in-kernel local
1498 APIC is not used.  Both input and output.
1499
1500         union {
1501                 /* KVM_EXIT_UNKNOWN */
1502                 struct {
1503                         __u64 hardware_exit_reason;
1504                 } hw;
1505
1506 If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
1507 reasons.  Further architecture-specific information is available in
1508 hardware_exit_reason.
1509
1510                 /* KVM_EXIT_FAIL_ENTRY */
1511                 struct {
1512                         __u64 hardware_entry_failure_reason;
1513                 } fail_entry;
1514
1515 If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
1516 to unknown reasons.  Further architecture-specific information is
1517 available in hardware_entry_failure_reason.
1518
1519                 /* KVM_EXIT_EXCEPTION */
1520                 struct {
1521                         __u32 exception;
1522                         __u32 error_code;
1523                 } ex;
1524
1525 Unused.
1526
1527                 /* KVM_EXIT_IO */
1528                 struct {
1529 #define KVM_EXIT_IO_IN  0
1530 #define KVM_EXIT_IO_OUT 1
1531                         __u8 direction;
1532                         __u8 size; /* bytes */
1533                         __u16 port;
1534                         __u32 count;
1535                         __u64 data_offset; /* relative to kvm_run start */
1536                 } io;
1537
1538 If exit_reason is KVM_EXIT_IO, then the vcpu has
1539 executed a port I/O instruction which could not be satisfied by kvm.
1540 data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
1541 where kvm expects application code to place the data for the next
1542 KVM_RUN invocation (KVM_EXIT_IO_IN).  Data format is a packed array.
1543
1544                 struct {
1545                         struct kvm_debug_exit_arch arch;
1546                 } debug;
1547
1548 Unused.
1549
1550                 /* KVM_EXIT_MMIO */
1551                 struct {
1552                         __u64 phys_addr;
1553                         __u8  data[8];
1554                         __u32 len;
1555                         __u8  is_write;
1556                 } mmio;
1557
1558 If exit_reason is KVM_EXIT_MMIO, then the vcpu has
1559 executed a memory-mapped I/O instruction which could not be satisfied
1560 by kvm.  The 'data' member contains the written data if 'is_write' is
1561 true, and should be filled by application code otherwise.
1562
1563 NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO and KVM_EXIT_OSI, the corresponding
1564 operations are complete (and guest state is consistent) only after userspace
1565 has re-entered the kernel with KVM_RUN.  The kernel side will first finish
1566 incomplete operations and then check for pending signals.  Userspace
1567 can re-enter the guest with an unmasked signal pending to complete
1568 pending operations.
1569
1570                 /* KVM_EXIT_HYPERCALL */
1571                 struct {
1572                         __u64 nr;
1573                         __u64 args[6];
1574                         __u64 ret;
1575                         __u32 longmode;
1576                         __u32 pad;
1577                 } hypercall;
1578
1579 Unused.  This was once used for 'hypercall to userspace'.  To implement
1580 such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
1581 Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
1582
1583                 /* KVM_EXIT_TPR_ACCESS */
1584                 struct {
1585                         __u64 rip;
1586                         __u32 is_write;
1587                         __u32 pad;
1588                 } tpr_access;
1589
1590 To be documented (KVM_TPR_ACCESS_REPORTING).
1591
1592                 /* KVM_EXIT_S390_SIEIC */
1593                 struct {
1594                         __u8 icptcode;
1595                         __u64 mask; /* psw upper half */
1596                         __u64 addr; /* psw lower half */
1597                         __u16 ipa;
1598                         __u32 ipb;
1599                 } s390_sieic;
1600
1601 s390 specific.
1602
1603                 /* KVM_EXIT_S390_RESET */
1604 #define KVM_S390_RESET_POR       1
1605 #define KVM_S390_RESET_CLEAR     2
1606 #define KVM_S390_RESET_SUBSYSTEM 4
1607 #define KVM_S390_RESET_CPU_INIT  8
1608 #define KVM_S390_RESET_IPL       16
1609                 __u64 s390_reset_flags;
1610
1611 s390 specific.
1612
1613                 /* KVM_EXIT_DCR */
1614                 struct {
1615                         __u32 dcrn;
1616                         __u32 data;
1617                         __u8  is_write;
1618                 } dcr;
1619
1620 powerpc specific.
1621
1622                 /* KVM_EXIT_OSI */
1623                 struct {
1624                         __u64 gprs[32];
1625                 } osi;
1626
1627 MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
1628 hypercalls and exit with this exit struct that contains all the guest gprs.
1629
1630 If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
1631 Userspace can now handle the hypercall and when it's done modify the gprs as
1632 necessary. Upon guest entry all guest GPRs will then be replaced by the values
1633 in this struct.
1634
1635                 /* KVM_EXIT_PAPR_HCALL */
1636                 struct {
1637                         __u64 nr;
1638                         __u64 ret;
1639                         __u64 args[9];
1640                 } papr_hcall;
1641
1642 This is used on 64-bit PowerPC when emulating a pSeries partition,
1643 e.g. with the 'pseries' machine type in qemu.  It occurs when the
1644 guest does a hypercall using the 'sc 1' instruction.  The 'nr' field
1645 contains the hypercall number (from the guest R3), and 'args' contains
1646 the arguments (from the guest R4 - R12).  Userspace should put the
1647 return code in 'ret' and any extra returned values in args[].
1648 The possible hypercalls are defined in the Power Architecture Platform
1649 Requirements (PAPR) document available from www.power.org (free
1650 developer registration required to access it).
1651
1652                 /* Fix the size of the union. */
1653                 char padding[256];
1654         };
1655 };
1656
1657 6. Capabilities that can be enabled
1658
1659 There are certain capabilities that change the behavior of the virtual CPU when
1660 enabled. To enable them, please see section 4.37. Below you can find a list of
1661 capabilities and what their effect on the vCPU is when enabling them.
1662
1663 The following information is provided along with the description:
1664
1665   Architectures: which instruction set architectures provide this ioctl.
1666       x86 includes both i386 and x86_64.
1667
1668   Parameters: what parameters are accepted by the capability.
1669
1670   Returns: the return value.  General error numbers (EBADF, ENOMEM, EINVAL)
1671       are not detailed, but errors with specific meanings are.
1672
1673 6.1 KVM_CAP_PPC_OSI
1674
1675 Architectures: ppc
1676 Parameters: none
1677 Returns: 0 on success; -1 on error
1678
1679 This capability enables interception of OSI hypercalls that otherwise would
1680 be treated as normal system calls to be injected into the guest. OSI hypercalls
1681 were invented by Mac-on-Linux to have a standardized communication mechanism
1682 between the guest and the host.
1683
1684 When this capability is enabled, KVM_EXIT_OSI can occur.
1685
1686 6.2 KVM_CAP_PPC_PAPR
1687
1688 Architectures: ppc
1689 Parameters: none
1690 Returns: 0 on success; -1 on error
1691
1692 This capability enables interception of PAPR hypercalls. PAPR hypercalls are
1693 done using the hypercall instruction "sc 1".
1694
1695 It also sets the guest privilege level to "supervisor" mode. Usually the guest
1696 runs in "hypervisor" privilege mode with a few missing features.
1697
1698 In addition to the above, it changes the semantics of SDR1. In this mode, the
1699 HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
1700 HTAB invisible to the guest.
1701
1702 When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.