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 The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned
1104 as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC
1105 support.  Instead it is reported via
1106
1107   ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)
1108
1109 if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the
1110 feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
1111
1112 4.47 KVM_PPC_GET_PVINFO
1113
1114 Capability: KVM_CAP_PPC_GET_PVINFO
1115 Architectures: ppc
1116 Type: vm ioctl
1117 Parameters: struct kvm_ppc_pvinfo (out)
1118 Returns: 0 on success, !0 on error
1119
1120 struct kvm_ppc_pvinfo {
1121         __u32 flags;
1122         __u32 hcall[4];
1123         __u8  pad[108];
1124 };
1125
1126 This ioctl fetches PV specific information that need to be passed to the guest
1127 using the device tree or other means from vm context.
1128
1129 For now the only implemented piece of information distributed here is an array
1130 of 4 instructions that make up a hypercall.
1131
1132 If any additional field gets added to this structure later on, a bit for that
1133 additional piece of information will be set in the flags bitmap.
1134
1135 4.48 KVM_ASSIGN_PCI_DEVICE
1136
1137 Capability: KVM_CAP_DEVICE_ASSIGNMENT
1138 Architectures: x86 ia64
1139 Type: vm ioctl
1140 Parameters: struct kvm_assigned_pci_dev (in)
1141 Returns: 0 on success, -1 on error
1142
1143 Assigns a host PCI device to the VM.
1144
1145 struct kvm_assigned_pci_dev {
1146         __u32 assigned_dev_id;
1147         __u32 busnr;
1148         __u32 devfn;
1149         __u32 flags;
1150         __u32 segnr;
1151         union {
1152                 __u32 reserved[11];
1153         };
1154 };
1155
1156 The PCI device is specified by the triple segnr, busnr, and devfn.
1157 Identification in succeeding service requests is done via assigned_dev_id. The
1158 following flags are specified:
1159
1160 /* Depends on KVM_CAP_IOMMU */
1161 #define KVM_DEV_ASSIGN_ENABLE_IOMMU     (1 << 0)
1162
1163 The KVM_DEV_ASSIGN_ENABLE_IOMMU flag is a mandatory option to ensure
1164 isolation of the device.  Usages not specifying this flag are deprecated.
1165
1166 Only PCI header type 0 devices with PCI BAR resources are supported by
1167 device assignment.  The user requesting this ioctl must have read/write
1168 access to the PCI sysfs resource files associated with the device.
1169
1170 4.49 KVM_DEASSIGN_PCI_DEVICE
1171
1172 Capability: KVM_CAP_DEVICE_DEASSIGNMENT
1173 Architectures: x86 ia64
1174 Type: vm ioctl
1175 Parameters: struct kvm_assigned_pci_dev (in)
1176 Returns: 0 on success, -1 on error
1177
1178 Ends PCI device assignment, releasing all associated resources.
1179
1180 See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is
1181 used in kvm_assigned_pci_dev to identify the device.
1182
1183 4.50 KVM_ASSIGN_DEV_IRQ
1184
1185 Capability: KVM_CAP_ASSIGN_DEV_IRQ
1186 Architectures: x86 ia64
1187 Type: vm ioctl
1188 Parameters: struct kvm_assigned_irq (in)
1189 Returns: 0 on success, -1 on error
1190
1191 Assigns an IRQ to a passed-through device.
1192
1193 struct kvm_assigned_irq {
1194         __u32 assigned_dev_id;
1195         __u32 host_irq; /* ignored (legacy field) */
1196         __u32 guest_irq;
1197         __u32 flags;
1198         union {
1199                 __u32 reserved[12];
1200         };
1201 };
1202
1203 The following flags are defined:
1204
1205 #define KVM_DEV_IRQ_HOST_INTX    (1 << 0)
1206 #define KVM_DEV_IRQ_HOST_MSI     (1 << 1)
1207 #define KVM_DEV_IRQ_HOST_MSIX    (1 << 2)
1208
1209 #define KVM_DEV_IRQ_GUEST_INTX   (1 << 8)
1210 #define KVM_DEV_IRQ_GUEST_MSI    (1 << 9)
1211 #define KVM_DEV_IRQ_GUEST_MSIX   (1 << 10)
1212
1213 It is not valid to specify multiple types per host or guest IRQ. However, the
1214 IRQ type of host and guest can differ or can even be null.
1215
1216 4.51 KVM_DEASSIGN_DEV_IRQ
1217
1218 Capability: KVM_CAP_ASSIGN_DEV_IRQ
1219 Architectures: x86 ia64
1220 Type: vm ioctl
1221 Parameters: struct kvm_assigned_irq (in)
1222 Returns: 0 on success, -1 on error
1223
1224 Ends an IRQ assignment to a passed-through device.
1225
1226 See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1227 by assigned_dev_id, flags must correspond to the IRQ type specified on
1228 KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed.
1229
1230 4.52 KVM_SET_GSI_ROUTING
1231
1232 Capability: KVM_CAP_IRQ_ROUTING
1233 Architectures: x86 ia64
1234 Type: vm ioctl
1235 Parameters: struct kvm_irq_routing (in)
1236 Returns: 0 on success, -1 on error
1237
1238 Sets the GSI routing table entries, overwriting any previously set entries.
1239
1240 struct kvm_irq_routing {
1241         __u32 nr;
1242         __u32 flags;
1243         struct kvm_irq_routing_entry entries[0];
1244 };
1245
1246 No flags are specified so far, the corresponding field must be set to zero.
1247
1248 struct kvm_irq_routing_entry {
1249         __u32 gsi;
1250         __u32 type;
1251         __u32 flags;
1252         __u32 pad;
1253         union {
1254                 struct kvm_irq_routing_irqchip irqchip;
1255                 struct kvm_irq_routing_msi msi;
1256                 __u32 pad[8];
1257         } u;
1258 };
1259
1260 /* gsi routing entry types */
1261 #define KVM_IRQ_ROUTING_IRQCHIP 1
1262 #define KVM_IRQ_ROUTING_MSI 2
1263
1264 No flags are specified so far, the corresponding field must be set to zero.
1265
1266 struct kvm_irq_routing_irqchip {
1267         __u32 irqchip;
1268         __u32 pin;
1269 };
1270
1271 struct kvm_irq_routing_msi {
1272         __u32 address_lo;
1273         __u32 address_hi;
1274         __u32 data;
1275         __u32 pad;
1276 };
1277
1278 4.53 KVM_ASSIGN_SET_MSIX_NR
1279
1280 Capability: KVM_CAP_DEVICE_MSIX
1281 Architectures: x86 ia64
1282 Type: vm ioctl
1283 Parameters: struct kvm_assigned_msix_nr (in)
1284 Returns: 0 on success, -1 on error
1285
1286 Set the number of MSI-X interrupts for an assigned device. The number is
1287 reset again by terminating the MSI-X assignment of the device via
1288 KVM_DEASSIGN_DEV_IRQ. Calling this service more than once at any earlier
1289 point will fail.
1290
1291 struct kvm_assigned_msix_nr {
1292         __u32 assigned_dev_id;
1293         __u16 entry_nr;
1294         __u16 padding;
1295 };
1296
1297 #define KVM_MAX_MSIX_PER_DEV            256
1298
1299 4.54 KVM_ASSIGN_SET_MSIX_ENTRY
1300
1301 Capability: KVM_CAP_DEVICE_MSIX
1302 Architectures: x86 ia64
1303 Type: vm ioctl
1304 Parameters: struct kvm_assigned_msix_entry (in)
1305 Returns: 0 on success, -1 on error
1306
1307 Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1308 the GSI vector to zero means disabling the interrupt.
1309
1310 struct kvm_assigned_msix_entry {
1311         __u32 assigned_dev_id;
1312         __u32 gsi;
1313         __u16 entry; /* The index of entry in the MSI-X table */
1314         __u16 padding[3];
1315 };
1316
1317 4.54 KVM_SET_TSC_KHZ
1318
1319 Capability: KVM_CAP_TSC_CONTROL
1320 Architectures: x86
1321 Type: vcpu ioctl
1322 Parameters: virtual tsc_khz
1323 Returns: 0 on success, -1 on error
1324
1325 Specifies the tsc frequency for the virtual machine. The unit of the
1326 frequency is KHz.
1327
1328 4.55 KVM_GET_TSC_KHZ
1329
1330 Capability: KVM_CAP_GET_TSC_KHZ
1331 Architectures: x86
1332 Type: vcpu ioctl
1333 Parameters: none
1334 Returns: virtual tsc-khz on success, negative value on error
1335
1336 Returns the tsc frequency of the guest. The unit of the return value is
1337 KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
1338 error.
1339
1340 4.56 KVM_GET_LAPIC
1341
1342 Capability: KVM_CAP_IRQCHIP
1343 Architectures: x86
1344 Type: vcpu ioctl
1345 Parameters: struct kvm_lapic_state (out)
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 Reads the Local APIC registers and copies them into the input argument.  The
1354 data format and layout are the same as documented in the architecture manual.
1355
1356 4.57 KVM_SET_LAPIC
1357
1358 Capability: KVM_CAP_IRQCHIP
1359 Architectures: x86
1360 Type: vcpu ioctl
1361 Parameters: struct kvm_lapic_state (in)
1362 Returns: 0 on success, -1 on error
1363
1364 #define KVM_APIC_REG_SIZE 0x400
1365 struct kvm_lapic_state {
1366         char regs[KVM_APIC_REG_SIZE];
1367 };
1368
1369 Copies the input argument into the the Local APIC registers.  The data format
1370 and layout are the same as documented in the architecture manual.
1371
1372 4.58 KVM_IOEVENTFD
1373
1374 Capability: KVM_CAP_IOEVENTFD
1375 Architectures: all
1376 Type: vm ioctl
1377 Parameters: struct kvm_ioeventfd (in)
1378 Returns: 0 on success, !0 on error
1379
1380 This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
1381 within the guest.  A guest write in the registered address will signal the
1382 provided event instead of triggering an exit.
1383
1384 struct kvm_ioeventfd {
1385         __u64 datamatch;
1386         __u64 addr;        /* legal pio/mmio address */
1387         __u32 len;         /* 1, 2, 4, or 8 bytes    */
1388         __s32 fd;
1389         __u32 flags;
1390         __u8  pad[36];
1391 };
1392
1393 The following flags are defined:
1394
1395 #define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
1396 #define KVM_IOEVENTFD_FLAG_PIO       (1 << kvm_ioeventfd_flag_nr_pio)
1397 #define KVM_IOEVENTFD_FLAG_DEASSIGN  (1 << kvm_ioeventfd_flag_nr_deassign)
1398
1399 If datamatch flag is set, the event will be signaled only if the written value
1400 to the registered address is equal to datamatch in struct kvm_ioeventfd.
1401
1402 4.62 KVM_CREATE_SPAPR_TCE
1403
1404 Capability: KVM_CAP_SPAPR_TCE
1405 Architectures: powerpc
1406 Type: vm ioctl
1407 Parameters: struct kvm_create_spapr_tce (in)
1408 Returns: file descriptor for manipulating the created TCE table
1409
1410 This creates a virtual TCE (translation control entry) table, which
1411 is an IOMMU for PAPR-style virtual I/O.  It is used to translate
1412 logical addresses used in virtual I/O into guest physical addresses,
1413 and provides a scatter/gather capability for PAPR virtual I/O.
1414
1415 /* for KVM_CAP_SPAPR_TCE */
1416 struct kvm_create_spapr_tce {
1417         __u64 liobn;
1418         __u32 window_size;
1419 };
1420
1421 The liobn field gives the logical IO bus number for which to create a
1422 TCE table.  The window_size field specifies the size of the DMA window
1423 which this TCE table will translate - the table will contain one 64
1424 bit TCE entry for every 4kiB of the DMA window.
1425
1426 When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
1427 table has been created using this ioctl(), the kernel will handle it
1428 in real mode, updating the TCE table.  H_PUT_TCE calls for other
1429 liobns will cause a vm exit and must be handled by userspace.
1430
1431 The return value is a file descriptor which can be passed to mmap(2)
1432 to map the created TCE table into userspace.  This lets userspace read
1433 the entries written by kernel-handled H_PUT_TCE calls, and also lets
1434 userspace update the TCE table directly which is useful in some
1435 circumstances.
1436
1437 4.63 KVM_ALLOCATE_RMA
1438
1439 Capability: KVM_CAP_PPC_RMA
1440 Architectures: powerpc
1441 Type: vm ioctl
1442 Parameters: struct kvm_allocate_rma (out)
1443 Returns: file descriptor for mapping the allocated RMA
1444
1445 This allocates a Real Mode Area (RMA) from the pool allocated at boot
1446 time by the kernel.  An RMA is a physically-contiguous, aligned region
1447 of memory used on older POWER processors to provide the memory which
1448 will be accessed by real-mode (MMU off) accesses in a KVM guest.
1449 POWER processors support a set of sizes for the RMA that usually
1450 includes 64MB, 128MB, 256MB and some larger powers of two.
1451
1452 /* for KVM_ALLOCATE_RMA */
1453 struct kvm_allocate_rma {
1454         __u64 rma_size;
1455 };
1456
1457 The return value is a file descriptor which can be passed to mmap(2)
1458 to map the allocated RMA into userspace.  The mapped area can then be
1459 passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the
1460 RMA for a virtual machine.  The size of the RMA in bytes (which is
1461 fixed at host kernel boot time) is returned in the rma_size field of
1462 the argument structure.
1463
1464 The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl
1465 is supported; 2 if the processor requires all virtual machines to have
1466 an RMA, or 1 if the processor can use an RMA but doesn't require it,
1467 because it supports the Virtual RMA (VRMA) facility.
1468
1469 5. The kvm_run structure
1470
1471 Application code obtains a pointer to the kvm_run structure by
1472 mmap()ing a vcpu fd.  From that point, application code can control
1473 execution by changing fields in kvm_run prior to calling the KVM_RUN
1474 ioctl, and obtain information about the reason KVM_RUN returned by
1475 looking up structure members.
1476
1477 struct kvm_run {
1478         /* in */
1479         __u8 request_interrupt_window;
1480
1481 Request that KVM_RUN return when it becomes possible to inject external
1482 interrupts into the guest.  Useful in conjunction with KVM_INTERRUPT.
1483
1484         __u8 padding1[7];
1485
1486         /* out */
1487         __u32 exit_reason;
1488
1489 When KVM_RUN has returned successfully (return value 0), this informs
1490 application code why KVM_RUN has returned.  Allowable values for this
1491 field are detailed below.
1492
1493         __u8 ready_for_interrupt_injection;
1494
1495 If request_interrupt_window has been specified, this field indicates
1496 an interrupt can be injected now with KVM_INTERRUPT.
1497
1498         __u8 if_flag;
1499
1500 The value of the current interrupt flag.  Only valid if in-kernel
1501 local APIC is not used.
1502
1503         __u8 padding2[2];
1504
1505         /* in (pre_kvm_run), out (post_kvm_run) */
1506         __u64 cr8;
1507
1508 The value of the cr8 register.  Only valid if in-kernel local APIC is
1509 not used.  Both input and output.
1510
1511         __u64 apic_base;
1512
1513 The value of the APIC BASE msr.  Only valid if in-kernel local
1514 APIC is not used.  Both input and output.
1515
1516         union {
1517                 /* KVM_EXIT_UNKNOWN */
1518                 struct {
1519                         __u64 hardware_exit_reason;
1520                 } hw;
1521
1522 If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
1523 reasons.  Further architecture-specific information is available in
1524 hardware_exit_reason.
1525
1526                 /* KVM_EXIT_FAIL_ENTRY */
1527                 struct {
1528                         __u64 hardware_entry_failure_reason;
1529                 } fail_entry;
1530
1531 If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
1532 to unknown reasons.  Further architecture-specific information is
1533 available in hardware_entry_failure_reason.
1534
1535                 /* KVM_EXIT_EXCEPTION */
1536                 struct {
1537                         __u32 exception;
1538                         __u32 error_code;
1539                 } ex;
1540
1541 Unused.
1542
1543                 /* KVM_EXIT_IO */
1544                 struct {
1545 #define KVM_EXIT_IO_IN  0
1546 #define KVM_EXIT_IO_OUT 1
1547                         __u8 direction;
1548                         __u8 size; /* bytes */
1549                         __u16 port;
1550                         __u32 count;
1551                         __u64 data_offset; /* relative to kvm_run start */
1552                 } io;
1553
1554 If exit_reason is KVM_EXIT_IO, then the vcpu has
1555 executed a port I/O instruction which could not be satisfied by kvm.
1556 data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
1557 where kvm expects application code to place the data for the next
1558 KVM_RUN invocation (KVM_EXIT_IO_IN).  Data format is a packed array.
1559
1560                 struct {
1561                         struct kvm_debug_exit_arch arch;
1562                 } debug;
1563
1564 Unused.
1565
1566                 /* KVM_EXIT_MMIO */
1567                 struct {
1568                         __u64 phys_addr;
1569                         __u8  data[8];
1570                         __u32 len;
1571                         __u8  is_write;
1572                 } mmio;
1573
1574 If exit_reason is KVM_EXIT_MMIO, then the vcpu has
1575 executed a memory-mapped I/O instruction which could not be satisfied
1576 by kvm.  The 'data' member contains the written data if 'is_write' is
1577 true, and should be filled by application code otherwise.
1578
1579 NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO and KVM_EXIT_OSI, the corresponding
1580 operations are complete (and guest state is consistent) only after userspace
1581 has re-entered the kernel with KVM_RUN.  The kernel side will first finish
1582 incomplete operations and then check for pending signals.  Userspace
1583 can re-enter the guest with an unmasked signal pending to complete
1584 pending operations.
1585
1586                 /* KVM_EXIT_HYPERCALL */
1587                 struct {
1588                         __u64 nr;
1589                         __u64 args[6];
1590                         __u64 ret;
1591                         __u32 longmode;
1592                         __u32 pad;
1593                 } hypercall;
1594
1595 Unused.  This was once used for 'hypercall to userspace'.  To implement
1596 such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
1597 Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
1598
1599                 /* KVM_EXIT_TPR_ACCESS */
1600                 struct {
1601                         __u64 rip;
1602                         __u32 is_write;
1603                         __u32 pad;
1604                 } tpr_access;
1605
1606 To be documented (KVM_TPR_ACCESS_REPORTING).
1607
1608                 /* KVM_EXIT_S390_SIEIC */
1609                 struct {
1610                         __u8 icptcode;
1611                         __u64 mask; /* psw upper half */
1612                         __u64 addr; /* psw lower half */
1613                         __u16 ipa;
1614                         __u32 ipb;
1615                 } s390_sieic;
1616
1617 s390 specific.
1618
1619                 /* KVM_EXIT_S390_RESET */
1620 #define KVM_S390_RESET_POR       1
1621 #define KVM_S390_RESET_CLEAR     2
1622 #define KVM_S390_RESET_SUBSYSTEM 4
1623 #define KVM_S390_RESET_CPU_INIT  8
1624 #define KVM_S390_RESET_IPL       16
1625                 __u64 s390_reset_flags;
1626
1627 s390 specific.
1628
1629                 /* KVM_EXIT_DCR */
1630                 struct {
1631                         __u32 dcrn;
1632                         __u32 data;
1633                         __u8  is_write;
1634                 } dcr;
1635
1636 powerpc specific.
1637
1638                 /* KVM_EXIT_OSI */
1639                 struct {
1640                         __u64 gprs[32];
1641                 } osi;
1642
1643 MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
1644 hypercalls and exit with this exit struct that contains all the guest gprs.
1645
1646 If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
1647 Userspace can now handle the hypercall and when it's done modify the gprs as
1648 necessary. Upon guest entry all guest GPRs will then be replaced by the values
1649 in this struct.
1650
1651                 /* KVM_EXIT_PAPR_HCALL */
1652                 struct {
1653                         __u64 nr;
1654                         __u64 ret;
1655                         __u64 args[9];
1656                 } papr_hcall;
1657
1658 This is used on 64-bit PowerPC when emulating a pSeries partition,
1659 e.g. with the 'pseries' machine type in qemu.  It occurs when the
1660 guest does a hypercall using the 'sc 1' instruction.  The 'nr' field
1661 contains the hypercall number (from the guest R3), and 'args' contains
1662 the arguments (from the guest R4 - R12).  Userspace should put the
1663 return code in 'ret' and any extra returned values in args[].
1664 The possible hypercalls are defined in the Power Architecture Platform
1665 Requirements (PAPR) document available from www.power.org (free
1666 developer registration required to access it).
1667
1668                 /* Fix the size of the union. */
1669                 char padding[256];
1670         };
1671 };
1672
1673 6. Capabilities that can be enabled
1674
1675 There are certain capabilities that change the behavior of the virtual CPU when
1676 enabled. To enable them, please see section 4.37. Below you can find a list of
1677 capabilities and what their effect on the vCPU is when enabling them.
1678
1679 The following information is provided along with the description:
1680
1681   Architectures: which instruction set architectures provide this ioctl.
1682       x86 includes both i386 and x86_64.
1683
1684   Parameters: what parameters are accepted by the capability.
1685
1686   Returns: the return value.  General error numbers (EBADF, ENOMEM, EINVAL)
1687       are not detailed, but errors with specific meanings are.
1688
1689 6.1 KVM_CAP_PPC_OSI
1690
1691 Architectures: ppc
1692 Parameters: none
1693 Returns: 0 on success; -1 on error
1694
1695 This capability enables interception of OSI hypercalls that otherwise would
1696 be treated as normal system calls to be injected into the guest. OSI hypercalls
1697 were invented by Mac-on-Linux to have a standardized communication mechanism
1698 between the guest and the host.
1699
1700 When this capability is enabled, KVM_EXIT_OSI can occur.
1701
1702 6.2 KVM_CAP_PPC_PAPR
1703
1704 Architectures: ppc
1705 Parameters: none
1706 Returns: 0 on success; -1 on error
1707
1708 This capability enables interception of PAPR hypercalls. PAPR hypercalls are
1709 done using the hypercall instruction "sc 1".
1710
1711 It also sets the guest privilege level to "supervisor" mode. Usually the guest
1712 runs in "hypervisor" privilege mode with a few missing features.
1713
1714 In addition to the above, it changes the semantics of SDR1. In this mode, the
1715 HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
1716 HTAB invisible to the guest.
1717
1718 When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.