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