linux/Documentation/virtual/kvm/api.txt
<<
>>
Prefs
   1The Definitive KVM (Kernel-based Virtual Machine) API Documentation
   2===================================================================
   3
   41. General description
   5----------------------
   6
   7The kvm API is a set of ioctls that are issued to control various aspects
   8of a virtual machine.  The ioctls belong to three classes
   9
  10 - System ioctls: These query and set global attributes which affect the
  11   whole kvm subsystem.  In addition a system ioctl is used to create
  12   virtual machines
  13
  14 - VM ioctls: These query and set attributes that affect an entire virtual
  15   machine, for example memory layout.  In addition a VM ioctl is used to
  16   create virtual cpus (vcpus).
  17
  18   Only run VM ioctls from the same process (address space) that was used
  19   to create the VM.
  20
  21 - vcpu ioctls: These query and set attributes that control the operation
  22   of a single virtual cpu.
  23
  24   Only run vcpu ioctls from the same thread that was used to create the
  25   vcpu.
  26
  27
  282. File descriptors
  29-------------------
  30
  31The kvm API is centered around file descriptors.  An initial
  32open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
  33can be used to issue system ioctls.  A KVM_CREATE_VM ioctl on this
  34handle will create a VM file descriptor which can be used to issue VM
  35ioctls.  A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu
  36and return a file descriptor pointing to it.  Finally, ioctls on a vcpu
  37fd can be used to control the vcpu, including the important task of
  38actually running guest code.
  39
  40In general file descriptors can be migrated among processes by means
  41of fork() and the SCM_RIGHTS facility of unix domain socket.  These
  42kinds of tricks are explicitly not supported by kvm.  While they will
  43not cause harm to the host, their actual behavior is not guaranteed by
  44the API.  The only supported use is one virtual machine per process,
  45and one vcpu per thread.
  46
  47
  483. Extensions
  49-------------
  50
  51As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
  52incompatible change are allowed.  However, there is an extension
  53facility that allows backward-compatible extensions to the API to be
  54queried and used.
  55
  56The extension mechanism is not based on on the Linux version number.
  57Instead, kvm defines extension identifiers and a facility to query
  58whether a particular extension identifier is available.  If it is, a
  59set of ioctls is available for application use.
  60
  61
  624. API description
  63------------------
  64
  65This section describes ioctls that can be used to control kvm guests.
  66For each ioctl, the following information is provided along with a
  67description:
  68
  69  Capability: which KVM extension provides this ioctl.  Can be 'basic',
  70      which means that is will be provided by any kernel that supports
  71      API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which
  72      means availability needs to be checked with KVM_CHECK_EXTENSION
  73      (see section 4.4).
  74
  75  Architectures: which instruction set architectures provide this ioctl.
  76      x86 includes both i386 and x86_64.
  77
  78  Type: system, vm, or vcpu.
  79
  80  Parameters: what parameters are accepted by the ioctl.
  81
  82  Returns: the return value.  General error numbers (EBADF, ENOMEM, EINVAL)
  83      are not detailed, but errors with specific meanings are.
  84
  85
  864.1 KVM_GET_API_VERSION
  87
  88Capability: basic
  89Architectures: all
  90Type: system ioctl
  91Parameters: none
  92Returns: the constant KVM_API_VERSION (=12)
  93
  94This identifies the API version as the stable kvm API. It is not
  95expected that this number will change.  However, Linux 2.6.20 and
  962.6.21 report earlier versions; these are not documented and not
  97supported.  Applications should refuse to run if KVM_GET_API_VERSION
  98returns a value other than 12.  If this check passes, all ioctls
  99described as 'basic' will be available.
 100
 101
 1024.2 KVM_CREATE_VM
 103
 104Capability: basic
 105Architectures: all
 106Type: system ioctl
 107Parameters: machine type identifier (KVM_VM_*)
 108Returns: a VM fd that can be used to control the new virtual machine.
 109
 110The new VM has no virtual cpus and no memory.  An mmap() of a VM fd
 111will access the virtual machine's physical address space; offset zero
 112corresponds to guest physical address zero.  Use of mmap() on a VM fd
 113is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is
 114available.
 115You most certainly want to use 0 as machine type.
 116
 117In order to create user controlled virtual machines on S390, check
 118KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as
 119privileged user (CAP_SYS_ADMIN).
 120
 121
 1224.3 KVM_GET_MSR_INDEX_LIST
 123
 124Capability: basic
 125Architectures: x86
 126Type: system
 127Parameters: struct kvm_msr_list (in/out)
 128Returns: 0 on success; -1 on error
 129Errors:
 130  E2BIG:     the msr index list is to be to fit in the array specified by
 131             the user.
 132
 133struct kvm_msr_list {
 134        __u32 nmsrs; /* number of msrs in entries */
 135        __u32 indices[0];
 136};
 137
 138This ioctl returns the guest msrs that are supported.  The list varies
 139by kvm version and host processor, but does not change otherwise.  The
 140user fills in the size of the indices array in nmsrs, and in return
 141kvm adjusts nmsrs to reflect the actual number of msrs and fills in
 142the indices array with their numbers.
 143
 144Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
 145not returned in the MSR list, as different vcpus can have a different number
 146of banks, as set via the KVM_X86_SETUP_MCE ioctl.
 147
 148
 1494.4 KVM_CHECK_EXTENSION
 150
 151Capability: basic
 152Architectures: all
 153Type: system ioctl
 154Parameters: extension identifier (KVM_CAP_*)
 155Returns: 0 if unsupported; 1 (or some other positive integer) if supported
 156
 157The API allows the application to query about extensions to the core
 158kvm API.  Userspace passes an extension identifier (an integer) and
 159receives an integer that describes the extension availability.
 160Generally 0 means no and 1 means yes, but some extensions may report
 161additional information in the integer return value.
 162
 163
 1644.5 KVM_GET_VCPU_MMAP_SIZE
 165
 166Capability: basic
 167Architectures: all
 168Type: system ioctl
 169Parameters: none
 170Returns: size of vcpu mmap area, in bytes
 171
 172The KVM_RUN ioctl (cf.) communicates with userspace via a shared
 173memory region.  This ioctl returns the size of that region.  See the
 174KVM_RUN documentation for details.
 175
 176
 1774.6 KVM_SET_MEMORY_REGION
 178
 179Capability: basic
 180Architectures: all
 181Type: vm ioctl
 182Parameters: struct kvm_memory_region (in)
 183Returns: 0 on success, -1 on error
 184
 185This ioctl is obsolete and has been removed.
 186
 187
 1884.7 KVM_CREATE_VCPU
 189
 190Capability: basic
 191Architectures: all
 192Type: vm ioctl
 193Parameters: vcpu id (apic id on x86)
 194Returns: vcpu fd on success, -1 on error
 195
 196This API adds a vcpu to a virtual machine.  The vcpu id is a small integer
 197in the range [0, max_vcpus).
 198
 199The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of
 200the KVM_CHECK_EXTENSION ioctl() at run-time.
 201The maximum possible value for max_vcpus can be retrieved using the
 202KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.
 203
 204If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
 205cpus max.
 206If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is
 207same as the value returned from KVM_CAP_NR_VCPUS.
 208
 209On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
 210threads in one or more virtual CPU cores.  (This is because the
 211hardware requires all the hardware threads in a CPU core to be in the
 212same partition.)  The KVM_CAP_PPC_SMT capability indicates the number
 213of vcpus per virtual core (vcore).  The vcore id is obtained by
 214dividing the vcpu id by the number of vcpus per vcore.  The vcpus in a
 215given vcore will always be in the same physical core as each other
 216(though that might be a different physical core from time to time).
 217Userspace can control the threading (SMT) mode of the guest by its
 218allocation of vcpu ids.  For example, if userspace wants
 219single-threaded guest vcpus, it should make all vcpu ids be a multiple
 220of the number of vcpus per vcore.
 221
 222For virtual cpus that have been created with S390 user controlled virtual
 223machines, the resulting vcpu fd can be memory mapped at page offset
 224KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtual
 225cpu's hardware control block.
 226
 227
 2284.8 KVM_GET_DIRTY_LOG (vm ioctl)
 229
 230Capability: basic
 231Architectures: x86
 232Type: vm ioctl
 233Parameters: struct kvm_dirty_log (in/out)
 234Returns: 0 on success, -1 on error
 235
 236/* for KVM_GET_DIRTY_LOG */
 237struct kvm_dirty_log {
 238        __u32 slot;
 239        __u32 padding;
 240        union {
 241                void __user *dirty_bitmap; /* one bit per page */
 242                __u64 padding;
 243        };
 244};
 245
 246Given a memory slot, return a bitmap containing any pages dirtied
 247since the last call to this ioctl.  Bit 0 is the first page in the
 248memory slot.  Ensure the entire structure is cleared to avoid padding
 249issues.
 250
 251
 2524.9 KVM_SET_MEMORY_ALIAS
 253
 254Capability: basic
 255Architectures: x86
 256Type: vm ioctl
 257Parameters: struct kvm_memory_alias (in)
 258Returns: 0 (success), -1 (error)
 259
 260This ioctl is obsolete and has been removed.
 261
 262
 2634.10 KVM_RUN
 264
 265Capability: basic
 266Architectures: all
 267Type: vcpu ioctl
 268Parameters: none
 269Returns: 0 on success, -1 on error
 270Errors:
 271  EINTR:     an unmasked signal is pending
 272
 273This ioctl is used to run a guest virtual cpu.  While there are no
 274explicit parameters, there is an implicit parameter block that can be
 275obtained by mmap()ing the vcpu fd at offset 0, with the size given by
 276KVM_GET_VCPU_MMAP_SIZE.  The parameter block is formatted as a 'struct
 277kvm_run' (see below).
 278
 279
 2804.11 KVM_GET_REGS
 281
 282Capability: basic
 283Architectures: all except ARM, arm64
 284Type: vcpu ioctl
 285Parameters: struct kvm_regs (out)
 286Returns: 0 on success, -1 on error
 287
 288Reads the general purpose registers from the vcpu.
 289
 290/* x86 */
 291struct kvm_regs {
 292        /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
 293        __u64 rax, rbx, rcx, rdx;
 294        __u64 rsi, rdi, rsp, rbp;
 295        __u64 r8,  r9,  r10, r11;
 296        __u64 r12, r13, r14, r15;
 297        __u64 rip, rflags;
 298};
 299
 300
 3014.12 KVM_SET_REGS
 302
 303Capability: basic
 304Architectures: all except ARM, arm64
 305Type: vcpu ioctl
 306Parameters: struct kvm_regs (in)
 307Returns: 0 on success, -1 on error
 308
 309Writes the general purpose registers into the vcpu.
 310
 311See KVM_GET_REGS for the data structure.
 312
 313
 3144.13 KVM_GET_SREGS
 315
 316Capability: basic
 317Architectures: x86, ppc
 318Type: vcpu ioctl
 319Parameters: struct kvm_sregs (out)
 320Returns: 0 on success, -1 on error
 321
 322Reads special registers from the vcpu.
 323
 324/* x86 */
 325struct kvm_sregs {
 326        struct kvm_segment cs, ds, es, fs, gs, ss;
 327        struct kvm_segment tr, ldt;
 328        struct kvm_dtable gdt, idt;
 329        __u64 cr0, cr2, cr3, cr4, cr8;
 330        __u64 efer;
 331        __u64 apic_base;
 332        __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
 333};
 334
 335/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */
 336
 337interrupt_bitmap is a bitmap of pending external interrupts.  At most
 338one bit may be set.  This interrupt has been acknowledged by the APIC
 339but not yet injected into the cpu core.
 340
 341
 3424.14 KVM_SET_SREGS
 343
 344Capability: basic
 345Architectures: x86, ppc
 346Type: vcpu ioctl
 347Parameters: struct kvm_sregs (in)
 348Returns: 0 on success, -1 on error
 349
 350Writes special registers into the vcpu.  See KVM_GET_SREGS for the
 351data structures.
 352
 353
 3544.15 KVM_TRANSLATE
 355
 356Capability: basic
 357Architectures: x86
 358Type: vcpu ioctl
 359Parameters: struct kvm_translation (in/out)
 360Returns: 0 on success, -1 on error
 361
 362Translates a virtual address according to the vcpu's current address
 363translation mode.
 364
 365struct kvm_translation {
 366        /* in */
 367        __u64 linear_address;
 368
 369        /* out */
 370        __u64 physical_address;
 371        __u8  valid;
 372        __u8  writeable;
 373        __u8  usermode;
 374        __u8  pad[5];
 375};
 376
 377
 3784.16 KVM_INTERRUPT
 379
 380Capability: basic
 381Architectures: x86, ppc
 382Type: vcpu ioctl
 383Parameters: struct kvm_interrupt (in)
 384Returns: 0 on success, -1 on error
 385
 386Queues a hardware interrupt vector to be injected.  This is only
 387useful if in-kernel local APIC or equivalent is not used.
 388
 389/* for KVM_INTERRUPT */
 390struct kvm_interrupt {
 391        /* in */
 392        __u32 irq;
 393};
 394
 395X86:
 396
 397Note 'irq' is an interrupt vector, not an interrupt pin or line.
 398
 399PPC:
 400
 401Queues an external interrupt to be injected. This ioctl is overleaded
 402with 3 different irq values:
 403
 404a) KVM_INTERRUPT_SET
 405
 406  This injects an edge type external interrupt into the guest once it's ready
 407  to receive interrupts. When injected, the interrupt is done.
 408
 409b) KVM_INTERRUPT_UNSET
 410
 411  This unsets any pending interrupt.
 412
 413  Only available with KVM_CAP_PPC_UNSET_IRQ.
 414
 415c) KVM_INTERRUPT_SET_LEVEL
 416
 417  This injects a level type external interrupt into the guest context. The
 418  interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
 419  is triggered.
 420
 421  Only available with KVM_CAP_PPC_IRQ_LEVEL.
 422
 423Note that any value for 'irq' other than the ones stated above is invalid
 424and incurs unexpected behavior.
 425
 426
 4274.17 KVM_DEBUG_GUEST
 428
 429Capability: basic
 430Architectures: none
 431Type: vcpu ioctl
 432Parameters: none)
 433Returns: -1 on error
 434
 435Support for this has been removed.  Use KVM_SET_GUEST_DEBUG instead.
 436
 437
 4384.18 KVM_GET_MSRS
 439
 440Capability: basic
 441Architectures: x86
 442Type: vcpu ioctl
 443Parameters: struct kvm_msrs (in/out)
 444Returns: 0 on success, -1 on error
 445
 446Reads model-specific registers from the vcpu.  Supported msr indices can
 447be obtained using KVM_GET_MSR_INDEX_LIST.
 448
 449struct kvm_msrs {
 450        __u32 nmsrs; /* number of msrs in entries */
 451        __u32 pad;
 452
 453        struct kvm_msr_entry entries[0];
 454};
 455
 456struct kvm_msr_entry {
 457        __u32 index;
 458        __u32 reserved;
 459        __u64 data;
 460};
 461
 462Application code should set the 'nmsrs' member (which indicates the
 463size of the entries array) and the 'index' member of each array entry.
 464kvm will fill in the 'data' member.
 465
 466
 4674.19 KVM_SET_MSRS
 468
 469Capability: basic
 470Architectures: x86
 471Type: vcpu ioctl
 472Parameters: struct kvm_msrs (in)
 473Returns: 0 on success, -1 on error
 474
 475Writes model-specific registers to the vcpu.  See KVM_GET_MSRS for the
 476data structures.
 477
 478Application code should set the 'nmsrs' member (which indicates the
 479size of the entries array), and the 'index' and 'data' members of each
 480array entry.
 481
 482
 4834.20 KVM_SET_CPUID
 484
 485Capability: basic
 486Architectures: x86
 487Type: vcpu ioctl
 488Parameters: struct kvm_cpuid (in)
 489Returns: 0 on success, -1 on error
 490
 491Defines the vcpu responses to the cpuid instruction.  Applications
 492should use the KVM_SET_CPUID2 ioctl if available.
 493
 494
 495struct kvm_cpuid_entry {
 496        __u32 function;
 497        __u32 eax;
 498        __u32 ebx;
 499        __u32 ecx;
 500        __u32 edx;
 501        __u32 padding;
 502};
 503
 504/* for KVM_SET_CPUID */
 505struct kvm_cpuid {
 506        __u32 nent;
 507        __u32 padding;
 508        struct kvm_cpuid_entry entries[0];
 509};
 510
 511
 5124.21 KVM_SET_SIGNAL_MASK
 513
 514Capability: basic
 515Architectures: x86
 516Type: vcpu ioctl
 517Parameters: struct kvm_signal_mask (in)
 518Returns: 0 on success, -1 on error
 519
 520Defines which signals are blocked during execution of KVM_RUN.  This
 521signal mask temporarily overrides the threads signal mask.  Any
 522unblocked signal received (except SIGKILL and SIGSTOP, which retain
 523their traditional behaviour) will cause KVM_RUN to return with -EINTR.
 524
 525Note the signal will only be delivered if not blocked by the original
 526signal mask.
 527
 528/* for KVM_SET_SIGNAL_MASK */
 529struct kvm_signal_mask {
 530        __u32 len;
 531        __u8  sigset[0];
 532};
 533
 534
 5354.22 KVM_GET_FPU
 536
 537Capability: basic
 538Architectures: x86
 539Type: vcpu ioctl
 540Parameters: struct kvm_fpu (out)
 541Returns: 0 on success, -1 on error
 542
 543Reads the floating point state from the vcpu.
 544
 545/* for KVM_GET_FPU and KVM_SET_FPU */
 546struct kvm_fpu {
 547        __u8  fpr[8][16];
 548        __u16 fcw;
 549        __u16 fsw;
 550        __u8  ftwx;  /* in fxsave format */
 551        __u8  pad1;
 552        __u16 last_opcode;
 553        __u64 last_ip;
 554        __u64 last_dp;
 555        __u8  xmm[16][16];
 556        __u32 mxcsr;
 557        __u32 pad2;
 558};
 559
 560
 5614.23 KVM_SET_FPU
 562
 563Capability: basic
 564Architectures: x86
 565Type: vcpu ioctl
 566Parameters: struct kvm_fpu (in)
 567Returns: 0 on success, -1 on error
 568
 569Writes the floating point state to the vcpu.
 570
 571/* for KVM_GET_FPU and KVM_SET_FPU */
 572struct kvm_fpu {
 573        __u8  fpr[8][16];
 574        __u16 fcw;
 575        __u16 fsw;
 576        __u8  ftwx;  /* in fxsave format */
 577        __u8  pad1;
 578        __u16 last_opcode;
 579        __u64 last_ip;
 580        __u64 last_dp;
 581        __u8  xmm[16][16];
 582        __u32 mxcsr;
 583        __u32 pad2;
 584};
 585
 586
 5874.24 KVM_CREATE_IRQCHIP
 588
 589Capability: KVM_CAP_IRQCHIP
 590Architectures: x86, ia64, ARM, arm64
 591Type: vm ioctl
 592Parameters: none
 593Returns: 0 on success, -1 on error
 594
 595Creates an interrupt controller model in the kernel.  On x86, creates a virtual
 596ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a
 597local APIC.  IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23
 598only go to the IOAPIC.  On ia64, a IOSAPIC is created. On ARM/arm64, a GIC is
 599created.
 600
 601
 6024.25 KVM_IRQ_LINE
 603
 604Capability: KVM_CAP_IRQCHIP
 605Architectures: x86, ia64, arm, arm64
 606Type: vm ioctl
 607Parameters: struct kvm_irq_level
 608Returns: 0 on success, -1 on error
 609
 610Sets the level of a GSI input to the interrupt controller model in the kernel.
 611On some architectures it is required that an interrupt controller model has
 612been previously created with KVM_CREATE_IRQCHIP.  Note that edge-triggered
 613interrupts require the level to be set to 1 and then back to 0.
 614
 615ARM/arm64 can signal an interrupt either at the CPU level, or at the
 616in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to
 617use PPIs designated for specific cpus.  The irq field is interpreted
 618like this:
 619
 620 \xC2\xA0bits:  | 31 ... 24 | 23  ... 16 | 15    ...    0 |
 621  field: | irq_type  | vcpu_index |     irq_id     |
 622
 623The irq_type field has the following values:
 624- irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
 625- irq_type[1]: in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)
 626               (the vcpu_index field is ignored)
 627- irq_type[2]: in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)
 628
 629(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
 630
 631In both cases, level is used to raise/lower the line.
 632
 633struct kvm_irq_level {
 634        union {
 635                __u32 irq;     /* GSI */
 636                __s32 status;  /* not used for KVM_IRQ_LEVEL */
 637        };
 638        __u32 level;           /* 0 or 1 */
 639};
 640
 641
 6424.26 KVM_GET_IRQCHIP
 643
 644Capability: KVM_CAP_IRQCHIP
 645Architectures: x86, ia64
 646Type: vm ioctl
 647Parameters: struct kvm_irqchip (in/out)
 648Returns: 0 on success, -1 on error
 649
 650Reads the state of a kernel interrupt controller created with
 651KVM_CREATE_IRQCHIP into a buffer provided by the caller.
 652
 653struct kvm_irqchip {
 654        __u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
 655        __u32 pad;
 656        union {
 657                char dummy[512];  /* reserving space */
 658                struct kvm_pic_state pic;
 659                struct kvm_ioapic_state ioapic;
 660        } chip;
 661};
 662
 663
 6644.27 KVM_SET_IRQCHIP
 665
 666Capability: KVM_CAP_IRQCHIP
 667Architectures: x86, ia64
 668Type: vm ioctl
 669Parameters: struct kvm_irqchip (in)
 670Returns: 0 on success, -1 on error
 671
 672Sets the state of a kernel interrupt controller created with
 673KVM_CREATE_IRQCHIP from a buffer provided by the caller.
 674
 675struct kvm_irqchip {
 676        __u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
 677        __u32 pad;
 678        union {
 679                char dummy[512];  /* reserving space */
 680                struct kvm_pic_state pic;
 681                struct kvm_ioapic_state ioapic;
 682        } chip;
 683};
 684
 685
 6864.28 KVM_XEN_HVM_CONFIG
 687
 688Capability: KVM_CAP_XEN_HVM
 689Architectures: x86
 690Type: vm ioctl
 691Parameters: struct kvm_xen_hvm_config (in)
 692Returns: 0 on success, -1 on error
 693
 694Sets the MSR that the Xen HVM guest uses to initialize its hypercall
 695page, and provides the starting address and size of the hypercall
 696blobs in userspace.  When the guest writes the MSR, kvm copies one
 697page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
 698memory.
 699
 700struct kvm_xen_hvm_config {
 701        __u32 flags;
 702        __u32 msr;
 703        __u64 blob_addr_32;
 704        __u64 blob_addr_64;
 705        __u8 blob_size_32;
 706        __u8 blob_size_64;
 707        __u8 pad2[30];
 708};
 709
 710
 7114.29 KVM_GET_CLOCK
 712
 713Capability: KVM_CAP_ADJUST_CLOCK
 714Architectures: x86
 715Type: vm ioctl
 716Parameters: struct kvm_clock_data (out)
 717Returns: 0 on success, -1 on error
 718
 719Gets the current timestamp of kvmclock as seen by the current guest. In
 720conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
 721such as migration.
 722
 723struct kvm_clock_data {
 724        __u64 clock;  /* kvmclock current value */
 725        __u32 flags;
 726        __u32 pad[9];
 727};
 728
 729
 7304.30 KVM_SET_CLOCK
 731
 732Capability: KVM_CAP_ADJUST_CLOCK
 733Architectures: x86
 734Type: vm ioctl
 735Parameters: struct kvm_clock_data (in)
 736Returns: 0 on success, -1 on error
 737
 738Sets the current timestamp of kvmclock to the value specified in its parameter.
 739In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
 740such as migration.
 741
 742struct kvm_clock_data {
 743        __u64 clock;  /* kvmclock current value */
 744        __u32 flags;
 745        __u32 pad[9];
 746};
 747
 748
 7494.31 KVM_GET_VCPU_EVENTS
 750
 751Capability: KVM_CAP_VCPU_EVENTS
 752Extended by: KVM_CAP_INTR_SHADOW
 753Architectures: x86
 754Type: vm ioctl
 755Parameters: struct kvm_vcpu_event (out)
 756Returns: 0 on success, -1 on error
 757
 758Gets currently pending exceptions, interrupts, and NMIs as well as related
 759states of the vcpu.
 760
 761struct kvm_vcpu_events {
 762        struct {
 763                __u8 injected;
 764                __u8 nr;
 765                __u8 has_error_code;
 766                __u8 pad;
 767                __u32 error_code;
 768        } exception;
 769        struct {
 770                __u8 injected;
 771                __u8 nr;
 772                __u8 soft;
 773                __u8 shadow;
 774        } interrupt;
 775        struct {
 776                __u8 injected;
 777                __u8 pending;
 778                __u8 masked;
 779                __u8 pad;
 780        } nmi;
 781        __u32 sipi_vector;
 782        __u32 flags;
 783};
 784
 785KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
 786interrupt.shadow contains a valid state. Otherwise, this field is undefined.
 787
 788
 7894.32 KVM_SET_VCPU_EVENTS
 790
 791Capability: KVM_CAP_VCPU_EVENTS
 792Extended by: KVM_CAP_INTR_SHADOW
 793Architectures: x86
 794Type: vm ioctl
 795Parameters: struct kvm_vcpu_event (in)
 796Returns: 0 on success, -1 on error
 797
 798Set pending exceptions, interrupts, and NMIs as well as related states of the
 799vcpu.
 800
 801See KVM_GET_VCPU_EVENTS for the data structure.
 802
 803Fields that may be modified asynchronously by running VCPUs can be excluded
 804from the update. These fields are nmi.pending and sipi_vector. Keep the
 805corresponding bits in the flags field cleared to suppress overwriting the
 806current in-kernel state. The bits are:
 807
 808KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
 809KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
 810
 811If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
 812the flags field to signal that interrupt.shadow contains a valid state and
 813shall be written into the VCPU.
 814
 815
 8164.33 KVM_GET_DEBUGREGS
 817
 818Capability: KVM_CAP_DEBUGREGS
 819Architectures: x86
 820Type: vm ioctl
 821Parameters: struct kvm_debugregs (out)
 822Returns: 0 on success, -1 on error
 823
 824Reads debug registers from the vcpu.
 825
 826struct kvm_debugregs {
 827        __u64 db[4];
 828        __u64 dr6;
 829        __u64 dr7;
 830        __u64 flags;
 831        __u64 reserved[9];
 832};
 833
 834
 8354.34 KVM_SET_DEBUGREGS
 836
 837Capability: KVM_CAP_DEBUGREGS
 838Architectures: x86
 839Type: vm ioctl
 840Parameters: struct kvm_debugregs (in)
 841Returns: 0 on success, -1 on error
 842
 843Writes debug registers into the vcpu.
 844
 845See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
 846yet and must be cleared on entry.
 847
 848
 8494.35 KVM_SET_USER_MEMORY_REGION
 850
 851Capability: KVM_CAP_USER_MEM
 852Architectures: all
 853Type: vm ioctl
 854Parameters: struct kvm_userspace_memory_region (in)
 855Returns: 0 on success, -1 on error
 856
 857struct kvm_userspace_memory_region {
 858        __u32 slot;
 859        __u32 flags;
 860        __u64 guest_phys_addr;
 861        __u64 memory_size; /* bytes */
 862        __u64 userspace_addr; /* start of the userspace allocated memory */
 863};
 864
 865/* for kvm_memory_region::flags */
 866#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
 867#define KVM_MEM_READONLY        (1UL << 1)
 868
 869This ioctl allows the user to create or modify a guest physical memory
 870slot.  When changing an existing slot, it may be moved in the guest
 871physical memory space, or its flags may be modified.  It may not be
 872resized.  Slots may not overlap in guest physical address space.
 873
 874Memory for the region is taken starting at the address denoted by the
 875field userspace_addr, which must point at user addressable memory for
 876the entire memory slot size.  Any object may back this memory, including
 877anonymous memory, ordinary files, and hugetlbfs.
 878
 879It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
 880be identical.  This allows large pages in the guest to be backed by large
 881pages in the host.
 882
 883The flags field supports two flags: KVM_MEM_LOG_DIRTY_PAGES and
 884KVM_MEM_READONLY.  The former can be set to instruct KVM to keep track of
 885writes to memory within the slot.  See KVM_GET_DIRTY_LOG ioctl to know how to
 886use it.  The latter can be set, if KVM_CAP_READONLY_MEM capability allows it,
 887to make a new slot read-only.  In this case, writes to this memory will be
 888posted to userspace as KVM_EXIT_MMIO exits.
 889
 890When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of
 891the memory region are automatically reflected into the guest.  For example, an
 892mmap() that affects the region will be made visible immediately.  Another
 893example is madvise(MADV_DROP).
 894
 895It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
 896The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
 897allocation and is deprecated.
 898
 899
 9004.36 KVM_SET_TSS_ADDR
 901
 902Capability: KVM_CAP_SET_TSS_ADDR
 903Architectures: x86
 904Type: vm ioctl
 905Parameters: unsigned long tss_address (in)
 906Returns: 0 on success, -1 on error
 907
 908This ioctl defines the physical address of a three-page region in the guest
 909physical address space.  The region must be within the first 4GB of the
 910guest physical address space and must not conflict with any memory slot
 911or any mmio address.  The guest may malfunction if it accesses this memory
 912region.
 913
 914This ioctl is required on Intel-based hosts.  This is needed on Intel hardware
 915because of a quirk in the virtualization implementation (see the internals
 916documentation when it pops into existence).
 917
 918
 9194.37 KVM_ENABLE_CAP
 920
 921Capability: KVM_CAP_ENABLE_CAP
 922Architectures: ppc, s390
 923Type: vcpu ioctl
 924Parameters: struct kvm_enable_cap (in)
 925Returns: 0 on success; -1 on error
 926
 927+Not all extensions are enabled by default. Using this ioctl the application
 928can enable an extension, making it available to the guest.
 929
 930On systems that do not support this ioctl, it always fails. On systems that
 931do support it, it only works for extensions that are supported for enablement.
 932
 933To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
 934be used.
 935
 936struct kvm_enable_cap {
 937       /* in */
 938       __u32 cap;
 939
 940The capability that is supposed to get enabled.
 941
 942       __u32 flags;
 943
 944A bitfield indicating future enhancements. Has to be 0 for now.
 945
 946       __u64 args[4];
 947
 948Arguments for enabling a feature. If a feature needs initial values to
 949function properly, this is the place to put them.
 950
 951       __u8  pad[64];
 952};
 953
 954
 9554.38 KVM_GET_MP_STATE
 956
 957Capability: KVM_CAP_MP_STATE
 958Architectures: x86, ia64
 959Type: vcpu ioctl
 960Parameters: struct kvm_mp_state (out)
 961Returns: 0 on success; -1 on error
 962
 963struct kvm_mp_state {
 964        __u32 mp_state;
 965};
 966
 967Returns the vcpu's current "multiprocessing state" (though also valid on
 968uniprocessor guests).
 969
 970Possible values are:
 971
 972 - KVM_MP_STATE_RUNNABLE:        the vcpu is currently running
 973 - KVM_MP_STATE_UNINITIALIZED:   the vcpu is an application processor (AP)
 974                                 which has not yet received an INIT signal
 975 - KVM_MP_STATE_INIT_RECEIVED:   the vcpu has received an INIT signal, and is
 976                                 now ready for a SIPI
 977 - KVM_MP_STATE_HALTED:          the vcpu has executed a HLT instruction and
 978                                 is waiting for an interrupt
 979 - KVM_MP_STATE_SIPI_RECEIVED:   the vcpu has just received a SIPI (vector
 980                                 accessible via KVM_GET_VCPU_EVENTS)
 981
 982This ioctl is only useful after KVM_CREATE_IRQCHIP.  Without an in-kernel
 983irqchip, the multiprocessing state must be maintained by userspace.
 984
 985
 9864.39 KVM_SET_MP_STATE
 987
 988Capability: KVM_CAP_MP_STATE
 989Architectures: x86, ia64
 990Type: vcpu ioctl
 991Parameters: struct kvm_mp_state (in)
 992Returns: 0 on success; -1 on error
 993
 994Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
 995arguments.
 996
 997This ioctl is only useful after KVM_CREATE_IRQCHIP.  Without an in-kernel
 998irqchip, the multiprocessing state must be maintained by userspace.
 999
1000
10014.40 KVM_SET_IDENTITY_MAP_ADDR
1002
1003Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
1004Architectures: x86
1005Type: vm ioctl
1006Parameters: unsigned long identity (in)
1007Returns: 0 on success, -1 on error
1008
1009This ioctl defines the physical address of a one-page region in the guest
1010physical address space.  The region must be within the first 4GB of the
1011guest physical address space and must not conflict with any memory slot
1012or any mmio address.  The guest may malfunction if it accesses this memory
1013region.
1014
1015This ioctl is required on Intel-based hosts.  This is needed on Intel hardware
1016because of a quirk in the virtualization implementation (see the internals
1017documentation when it pops into existence).
1018
1019
10204.41 KVM_SET_BOOT_CPU_ID
1021
1022Capability: KVM_CAP_SET_BOOT_CPU_ID
1023Architectures: x86, ia64
1024Type: vm ioctl
1025Parameters: unsigned long vcpu_id
1026Returns: 0 on success, -1 on error
1027
1028Define which vcpu is the Bootstrap Processor (BSP).  Values are the same
1029as the vcpu id in KVM_CREATE_VCPU.  If this ioctl is not called, the default
1030is vcpu 0.
1031
1032
10334.42 KVM_GET_XSAVE
1034
1035Capability: KVM_CAP_XSAVE
1036Architectures: x86
1037Type: vcpu ioctl
1038Parameters: struct kvm_xsave (out)
1039Returns: 0 on success, -1 on error
1040
1041struct kvm_xsave {
1042        __u32 region[1024];
1043};
1044
1045This ioctl would copy current vcpu's xsave struct to the userspace.
1046
1047
10484.43 KVM_SET_XSAVE
1049
1050Capability: KVM_CAP_XSAVE
1051Architectures: x86
1052Type: vcpu ioctl
1053Parameters: struct kvm_xsave (in)
1054Returns: 0 on success, -1 on error
1055
1056struct kvm_xsave {
1057        __u32 region[1024];
1058};
1059
1060This ioctl would copy userspace's xsave struct to the kernel.
1061
1062
10634.44 KVM_GET_XCRS
1064
1065Capability: KVM_CAP_XCRS
1066Architectures: x86
1067Type: vcpu ioctl
1068Parameters: struct kvm_xcrs (out)
1069Returns: 0 on success, -1 on error
1070
1071struct kvm_xcr {
1072        __u32 xcr;
1073        __u32 reserved;
1074        __u64 value;
1075};
1076
1077struct kvm_xcrs {
1078        __u32 nr_xcrs;
1079        __u32 flags;
1080        struct kvm_xcr xcrs[KVM_MAX_XCRS];
1081        __u64 padding[16];
1082};
1083
1084This ioctl would copy current vcpu's xcrs to the userspace.
1085
1086
10874.45 KVM_SET_XCRS
1088
1089Capability: KVM_CAP_XCRS
1090Architectures: x86
1091Type: vcpu ioctl
1092Parameters: struct kvm_xcrs (in)
1093Returns: 0 on success, -1 on error
1094
1095struct kvm_xcr {
1096        __u32 xcr;
1097        __u32 reserved;
1098        __u64 value;
1099};
1100
1101struct kvm_xcrs {
1102        __u32 nr_xcrs;
1103        __u32 flags;
1104        struct kvm_xcr xcrs[KVM_MAX_XCRS];
1105        __u64 padding[16];
1106};
1107
1108This ioctl would set vcpu's xcr to the value userspace specified.
1109
1110
11114.46 KVM_GET_SUPPORTED_CPUID
1112
1113Capability: KVM_CAP_EXT_CPUID
1114Architectures: x86
1115Type: system ioctl
1116Parameters: struct kvm_cpuid2 (in/out)
1117Returns: 0 on success, -1 on error
1118
1119struct kvm_cpuid2 {
1120        __u32 nent;
1121        __u32 padding;
1122        struct kvm_cpuid_entry2 entries[0];
1123};
1124
1125#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX 1
1126#define KVM_CPUID_FLAG_STATEFUL_FUNC    2
1127#define KVM_CPUID_FLAG_STATE_READ_NEXT  4
1128
1129struct kvm_cpuid_entry2 {
1130        __u32 function;
1131        __u32 index;
1132        __u32 flags;
1133        __u32 eax;
1134        __u32 ebx;
1135        __u32 ecx;
1136        __u32 edx;
1137        __u32 padding[3];
1138};
1139
1140This ioctl returns x86 cpuid features which are supported by both the hardware
1141and kvm.  Userspace can use the information returned by this ioctl to
1142construct cpuid information (for KVM_SET_CPUID2) that is consistent with
1143hardware, kernel, and userspace capabilities, and with user requirements (for
1144example, the user may wish to constrain cpuid to emulate older hardware,
1145or for feature consistency across a cluster).
1146
1147Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1148with the 'nent' field indicating the number of entries in the variable-size
1149array 'entries'.  If the number of entries is too low to describe the cpu
1150capabilities, an error (E2BIG) is returned.  If the number is too high,
1151the 'nent' field is adjusted and an error (ENOMEM) is returned.  If the
1152number is just right, the 'nent' field is adjusted to the number of valid
1153entries in the 'entries' array, which is then filled.
1154
1155The entries returned are the host cpuid as returned by the cpuid instruction,
1156with unknown or unsupported features masked out.  Some features (for example,
1157x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1158emulate them efficiently. The fields in each entry are defined as follows:
1159
1160  function: the eax value used to obtain the entry
1161  index: the ecx value used to obtain the entry (for entries that are
1162         affected by ecx)
1163  flags: an OR of zero or more of the following:
1164        KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
1165           if the index field is valid
1166        KVM_CPUID_FLAG_STATEFUL_FUNC:
1167           if cpuid for this function returns different values for successive
1168           invocations; there will be several entries with the same function,
1169           all with this flag set
1170        KVM_CPUID_FLAG_STATE_READ_NEXT:
1171           for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
1172           the first entry to be read by a cpu
1173   eax, ebx, ecx, edx: the values returned by the cpuid instruction for
1174         this function/index combination
1175
1176The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned
1177as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC
1178support.  Instead it is reported via
1179
1180  ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)
1181
1182if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the
1183feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
1184
1185
11864.47 KVM_PPC_GET_PVINFO
1187
1188Capability: KVM_CAP_PPC_GET_PVINFO
1189Architectures: ppc
1190Type: vm ioctl
1191Parameters: struct kvm_ppc_pvinfo (out)
1192Returns: 0 on success, !0 on error
1193
1194struct kvm_ppc_pvinfo {
1195        __u32 flags;
1196        __u32 hcall[4];
1197        __u8  pad[108];
1198};
1199
1200This ioctl fetches PV specific information that need to be passed to the guest
1201using the device tree or other means from vm context.
1202
1203The hcall array defines 4 instructions that make up a hypercall.
1204
1205If any additional field gets added to this structure later on, a bit for that
1206additional piece of information will be set in the flags bitmap.
1207
1208The flags bitmap is defined as:
1209
1210   /* the host supports the ePAPR idle hcall
1211   #define KVM_PPC_PVINFO_FLAGS_EV_IDLE   (1<<0)
1212
12134.48 KVM_ASSIGN_PCI_DEVICE
1214
1215Capability: KVM_CAP_DEVICE_ASSIGNMENT
1216Architectures: x86 ia64
1217Type: vm ioctl
1218Parameters: struct kvm_assigned_pci_dev (in)
1219Returns: 0 on success, -1 on error
1220
1221Assigns a host PCI device to the VM.
1222
1223struct kvm_assigned_pci_dev {
1224        __u32 assigned_dev_id;
1225        __u32 busnr;
1226        __u32 devfn;
1227        __u32 flags;
1228        __u32 segnr;
1229        union {
1230                __u32 reserved[11];
1231        };
1232};
1233
1234The PCI device is specified by the triple segnr, busnr, and devfn.
1235Identification in succeeding service requests is done via assigned_dev_id. The
1236following flags are specified:
1237
1238/* Depends on KVM_CAP_IOMMU */
1239#define KVM_DEV_ASSIGN_ENABLE_IOMMU     (1 << 0)
1240/* The following two depend on KVM_CAP_PCI_2_3 */
1241#define KVM_DEV_ASSIGN_PCI_2_3          (1 << 1)
1242#define KVM_DEV_ASSIGN_MASK_INTX        (1 << 2)
1243
1244If KVM_DEV_ASSIGN_PCI_2_3 is set, the kernel will manage legacy INTx interrupts
1245via the PCI-2.3-compliant device-level mask, thus enable IRQ sharing with other
1246assigned devices or host devices. KVM_DEV_ASSIGN_MASK_INTX specifies the
1247guest's view on the INTx mask, see KVM_ASSIGN_SET_INTX_MASK for details.
1248
1249The KVM_DEV_ASSIGN_ENABLE_IOMMU flag is a mandatory option to ensure
1250isolation of the device.  Usages not specifying this flag are deprecated.
1251
1252Only PCI header type 0 devices with PCI BAR resources are supported by
1253device assignment.  The user requesting this ioctl must have read/write
1254access to the PCI sysfs resource files associated with the device.
1255
1256
12574.49 KVM_DEASSIGN_PCI_DEVICE
1258
1259Capability: KVM_CAP_DEVICE_DEASSIGNMENT
1260Architectures: x86 ia64
1261Type: vm ioctl
1262Parameters: struct kvm_assigned_pci_dev (in)
1263Returns: 0 on success, -1 on error
1264
1265Ends PCI device assignment, releasing all associated resources.
1266
1267See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is
1268used in kvm_assigned_pci_dev to identify the device.
1269
1270
12714.50 KVM_ASSIGN_DEV_IRQ
1272
1273Capability: KVM_CAP_ASSIGN_DEV_IRQ
1274Architectures: x86 ia64
1275Type: vm ioctl
1276Parameters: struct kvm_assigned_irq (in)
1277Returns: 0 on success, -1 on error
1278
1279Assigns an IRQ to a passed-through device.
1280
1281struct kvm_assigned_irq {
1282        __u32 assigned_dev_id;
1283        __u32 host_irq; /* ignored (legacy field) */
1284        __u32 guest_irq;
1285        __u32 flags;
1286        union {
1287                __u32 reserved[12];
1288        };
1289};
1290
1291The following flags are defined:
1292
1293#define KVM_DEV_IRQ_HOST_INTX    (1 << 0)
1294#define KVM_DEV_IRQ_HOST_MSI     (1 << 1)
1295#define KVM_DEV_IRQ_HOST_MSIX    (1 << 2)
1296
1297#define KVM_DEV_IRQ_GUEST_INTX   (1 << 8)
1298#define KVM_DEV_IRQ_GUEST_MSI    (1 << 9)
1299#define KVM_DEV_IRQ_GUEST_MSIX   (1 << 10)
1300
1301It is not valid to specify multiple types per host or guest IRQ. However, the
1302IRQ type of host and guest can differ or can even be null.
1303
1304
13054.51 KVM_DEASSIGN_DEV_IRQ
1306
1307Capability: KVM_CAP_ASSIGN_DEV_IRQ
1308Architectures: x86 ia64
1309Type: vm ioctl
1310Parameters: struct kvm_assigned_irq (in)
1311Returns: 0 on success, -1 on error
1312
1313Ends an IRQ assignment to a passed-through device.
1314
1315See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1316by assigned_dev_id, flags must correspond to the IRQ type specified on
1317KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed.
1318
1319
13204.52 KVM_SET_GSI_ROUTING
1321
1322Capability: KVM_CAP_IRQ_ROUTING
1323Architectures: x86 ia64
1324Type: vm ioctl
1325Parameters: struct kvm_irq_routing (in)
1326Returns: 0 on success, -1 on error
1327
1328Sets the GSI routing table entries, overwriting any previously set entries.
1329
1330struct kvm_irq_routing {
1331        __u32 nr;
1332        __u32 flags;
1333        struct kvm_irq_routing_entry entries[0];
1334};
1335
1336No flags are specified so far, the corresponding field must be set to zero.
1337
1338struct kvm_irq_routing_entry {
1339        __u32 gsi;
1340        __u32 type;
1341        __u32 flags;
1342        __u32 pad;
1343        union {
1344                struct kvm_irq_routing_irqchip irqchip;
1345                struct kvm_irq_routing_msi msi;
1346                __u32 pad[8];
1347        } u;
1348};
1349
1350/* gsi routing entry types */
1351#define KVM_IRQ_ROUTING_IRQCHIP 1
1352#define KVM_IRQ_ROUTING_MSI 2
1353
1354No flags are specified so far, the corresponding field must be set to zero.
1355
1356struct kvm_irq_routing_irqchip {
1357        __u32 irqchip;
1358        __u32 pin;
1359};
1360
1361struct kvm_irq_routing_msi {
1362        __u32 address_lo;
1363        __u32 address_hi;
1364        __u32 data;
1365        __u32 pad;
1366};
1367
1368
13694.53 KVM_ASSIGN_SET_MSIX_NR
1370
1371Capability: KVM_CAP_DEVICE_MSIX
1372Architectures: x86 ia64
1373Type: vm ioctl
1374Parameters: struct kvm_assigned_msix_nr (in)
1375Returns: 0 on success, -1 on error
1376
1377Set the number of MSI-X interrupts for an assigned device. The number is
1378reset again by terminating the MSI-X assignment of the device via
1379KVM_DEASSIGN_DEV_IRQ. Calling this service more than once at any earlier
1380point will fail.
1381
1382struct kvm_assigned_msix_nr {
1383        __u32 assigned_dev_id;
1384        __u16 entry_nr;
1385        __u16 padding;
1386};
1387
1388#define KVM_MAX_MSIX_PER_DEV            256
1389
1390
13914.54 KVM_ASSIGN_SET_MSIX_ENTRY
1392
1393Capability: KVM_CAP_DEVICE_MSIX
1394Architectures: x86 ia64
1395Type: vm ioctl
1396Parameters: struct kvm_assigned_msix_entry (in)
1397Returns: 0 on success, -1 on error
1398
1399Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1400the GSI vector to zero means disabling the interrupt.
1401
1402struct kvm_assigned_msix_entry {
1403        __u32 assigned_dev_id;
1404        __u32 gsi;
1405        __u16 entry; /* The index of entry in the MSI-X table */
1406        __u16 padding[3];
1407};
1408
1409
14104.55 KVM_SET_TSC_KHZ
1411
1412Capability: KVM_CAP_TSC_CONTROL
1413Architectures: x86
1414Type: vcpu ioctl
1415Parameters: virtual tsc_khz
1416Returns: 0 on success, -1 on error
1417
1418Specifies the tsc frequency for the virtual machine. The unit of the
1419frequency is KHz.
1420
1421
14224.56 KVM_GET_TSC_KHZ
1423
1424Capability: KVM_CAP_GET_TSC_KHZ
1425Architectures: x86
1426Type: vcpu ioctl
1427Parameters: none
1428Returns: virtual tsc-khz on success, negative value on error
1429
1430Returns the tsc frequency of the guest. The unit of the return value is
1431KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
1432error.
1433
1434
14354.57 KVM_GET_LAPIC
1436
1437Capability: KVM_CAP_IRQCHIP
1438Architectures: x86
1439Type: vcpu ioctl
1440Parameters: struct kvm_lapic_state (out)
1441Returns: 0 on success, -1 on error
1442
1443#define KVM_APIC_REG_SIZE 0x400
1444struct kvm_lapic_state {
1445        char regs[KVM_APIC_REG_SIZE];
1446};
1447
1448Reads the Local APIC registers and copies them into the input argument.  The
1449data format and layout are the same as documented in the architecture manual.
1450
1451
14524.58 KVM_SET_LAPIC
1453
1454Capability: KVM_CAP_IRQCHIP
1455Architectures: x86
1456Type: vcpu ioctl
1457Parameters: struct kvm_lapic_state (in)
1458Returns: 0 on success, -1 on error
1459
1460#define KVM_APIC_REG_SIZE 0x400
1461struct kvm_lapic_state {
1462        char regs[KVM_APIC_REG_SIZE];
1463};
1464
1465Copies the input argument into the the Local APIC registers.  The data format
1466and layout are the same as documented in the architecture manual.
1467
1468
14694.59 KVM_IOEVENTFD
1470
1471Capability: KVM_CAP_IOEVENTFD
1472Architectures: all
1473Type: vm ioctl
1474Parameters: struct kvm_ioeventfd (in)
1475Returns: 0 on success, !0 on error
1476
1477This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
1478within the guest.  A guest write in the registered address will signal the
1479provided event instead of triggering an exit.
1480
1481struct kvm_ioeventfd {
1482        __u64 datamatch;
1483        __u64 addr;        /* legal pio/mmio address */
1484        __u32 len;         /* 1, 2, 4, or 8 bytes    */
1485        __s32 fd;
1486        __u32 flags;
1487        __u8  pad[36];
1488};
1489
1490For the special case of virtio-ccw devices on s390, the ioevent is matched
1491to a subchannel/virtqueue tuple instead.
1492
1493The following flags are defined:
1494
1495#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
1496#define KVM_IOEVENTFD_FLAG_PIO       (1 << kvm_ioeventfd_flag_nr_pio)
1497#define KVM_IOEVENTFD_FLAG_DEASSIGN  (1 << kvm_ioeventfd_flag_nr_deassign)
1498#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \
1499        (1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify)
1500
1501If datamatch flag is set, the event will be signaled only if the written value
1502to the registered address is equal to datamatch in struct kvm_ioeventfd.
1503
1504For virtio-ccw devices, addr contains the subchannel id and datamatch the
1505virtqueue index.
1506
1507
15084.60 KVM_DIRTY_TLB
1509
1510Capability: KVM_CAP_SW_TLB
1511Architectures: ppc
1512Type: vcpu ioctl
1513Parameters: struct kvm_dirty_tlb (in)
1514Returns: 0 on success, -1 on error
1515
1516struct kvm_dirty_tlb {
1517        __u64 bitmap;
1518        __u32 num_dirty;
1519};
1520
1521This must be called whenever userspace has changed an entry in the shared
1522TLB, prior to calling KVM_RUN on the associated vcpu.
1523
1524The "bitmap" field is the userspace address of an array.  This array
1525consists of a number of bits, equal to the total number of TLB entries as
1526determined by the last successful call to KVM_CONFIG_TLB, rounded up to the
1527nearest multiple of 64.
1528
1529Each bit corresponds to one TLB entry, ordered the same as in the shared TLB
1530array.
1531
1532The array is little-endian: the bit 0 is the least significant bit of the
1533first byte, bit 8 is the least significant bit of the second byte, etc.
1534This avoids any complications with differing word sizes.
1535
1536The "num_dirty" field is a performance hint for KVM to determine whether it
1537should skip processing the bitmap and just invalidate everything.  It must
1538be set to the number of set bits in the bitmap.
1539
1540
15414.61 KVM_ASSIGN_SET_INTX_MASK
1542
1543Capability: KVM_CAP_PCI_2_3
1544Architectures: x86
1545Type: vm ioctl
1546Parameters: struct kvm_assigned_pci_dev (in)
1547Returns: 0 on success, -1 on error
1548
1549Allows userspace to mask PCI INTx interrupts from the assigned device.  The
1550kernel will not deliver INTx interrupts to the guest between setting and
1551clearing of KVM_ASSIGN_SET_INTX_MASK via this interface.  This enables use of
1552and emulation of PCI 2.3 INTx disable command register behavior.
1553
1554This may be used for both PCI 2.3 devices supporting INTx disable natively and
1555older devices lacking this support. Userspace is responsible for emulating the
1556read value of the INTx disable bit in the guest visible PCI command register.
1557When modifying the INTx disable state, userspace should precede updating the
1558physical device command register by calling this ioctl to inform the kernel of
1559the new intended INTx mask state.
1560
1561Note that the kernel uses the device INTx disable bit to internally manage the
1562device interrupt state for PCI 2.3 devices.  Reads of this register may
1563therefore not match the expected value.  Writes should always use the guest
1564intended INTx disable value rather than attempting to read-copy-update the
1565current physical device state.  Races between user and kernel updates to the
1566INTx disable bit are handled lazily in the kernel.  It's possible the device
1567may generate unintended interrupts, but they will not be injected into the
1568guest.
1569
1570See KVM_ASSIGN_DEV_IRQ for the data structure.  The target device is specified
1571by assigned_dev_id.  In the flags field, only KVM_DEV_ASSIGN_MASK_INTX is
1572evaluated.
1573
1574
15754.62 KVM_CREATE_SPAPR_TCE
1576
1577Capability: KVM_CAP_SPAPR_TCE
1578Architectures: powerpc
1579Type: vm ioctl
1580Parameters: struct kvm_create_spapr_tce (in)
1581Returns: file descriptor for manipulating the created TCE table
1582
1583This creates a virtual TCE (translation control entry) table, which
1584is an IOMMU for PAPR-style virtual I/O.  It is used to translate
1585logical addresses used in virtual I/O into guest physical addresses,
1586and provides a scatter/gather capability for PAPR virtual I/O.
1587
1588/* for KVM_CAP_SPAPR_TCE */
1589struct kvm_create_spapr_tce {
1590        __u64 liobn;
1591        __u32 window_size;
1592};
1593
1594The liobn field gives the logical IO bus number for which to create a
1595TCE table.  The window_size field specifies the size of the DMA window
1596which this TCE table will translate - the table will contain one 64
1597bit TCE entry for every 4kiB of the DMA window.
1598
1599When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
1600table has been created using this ioctl(), the kernel will handle it
1601in real mode, updating the TCE table.  H_PUT_TCE calls for other
1602liobns will cause a vm exit and must be handled by userspace.
1603
1604The return value is a file descriptor which can be passed to mmap(2)
1605to map the created TCE table into userspace.  This lets userspace read
1606the entries written by kernel-handled H_PUT_TCE calls, and also lets
1607userspace update the TCE table directly which is useful in some
1608circumstances.
1609
1610
16114.63 KVM_ALLOCATE_RMA
1612
1613Capability: KVM_CAP_PPC_RMA
1614Architectures: powerpc
1615Type: vm ioctl
1616Parameters: struct kvm_allocate_rma (out)
1617Returns: file descriptor for mapping the allocated RMA
1618
1619This allocates a Real Mode Area (RMA) from the pool allocated at boot
1620time by the kernel.  An RMA is a physically-contiguous, aligned region
1621of memory used on older POWER processors to provide the memory which
1622will be accessed by real-mode (MMU off) accesses in a KVM guest.
1623POWER processors support a set of sizes for the RMA that usually
1624includes 64MB, 128MB, 256MB and some larger powers of two.
1625
1626/* for KVM_ALLOCATE_RMA */
1627struct kvm_allocate_rma {
1628        __u64 rma_size;
1629};
1630
1631The return value is a file descriptor which can be passed to mmap(2)
1632to map the allocated RMA into userspace.  The mapped area can then be
1633passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the
1634RMA for a virtual machine.  The size of the RMA in bytes (which is
1635fixed at host kernel boot time) is returned in the rma_size field of
1636the argument structure.
1637
1638The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl
1639is supported; 2 if the processor requires all virtual machines to have
1640an RMA, or 1 if the processor can use an RMA but doesn't require it,
1641because it supports the Virtual RMA (VRMA) facility.
1642
1643
16444.64 KVM_NMI
1645
1646Capability: KVM_CAP_USER_NMI
1647Architectures: x86
1648Type: vcpu ioctl
1649Parameters: none
1650Returns: 0 on success, -1 on error
1651
1652Queues an NMI on the thread's vcpu.  Note this is well defined only
1653when KVM_CREATE_IRQCHIP has not been called, since this is an interface
1654between the virtual cpu core and virtual local APIC.  After KVM_CREATE_IRQCHIP
1655has been called, this interface is completely emulated within the kernel.
1656
1657To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the
1658following algorithm:
1659
1660  - pause the vpcu
1661  - read the local APIC's state (KVM_GET_LAPIC)
1662  - check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1)
1663  - if so, issue KVM_NMI
1664  - resume the vcpu
1665
1666Some guests configure the LINT1 NMI input to cause a panic, aiding in
1667debugging.
1668
1669
16704.65 KVM_S390_UCAS_MAP
1671
1672Capability: KVM_CAP_S390_UCONTROL
1673Architectures: s390
1674Type: vcpu ioctl
1675Parameters: struct kvm_s390_ucas_mapping (in)
1676Returns: 0 in case of success
1677
1678The parameter is defined like this:
1679        struct kvm_s390_ucas_mapping {
1680                __u64 user_addr;
1681                __u64 vcpu_addr;
1682                __u64 length;
1683        };
1684
1685This ioctl maps the memory at "user_addr" with the length "length" to
1686the vcpu's address space starting at "vcpu_addr". All parameters need to
1687be aligned by 1 megabyte.
1688
1689
16904.66 KVM_S390_UCAS_UNMAP
1691
1692Capability: KVM_CAP_S390_UCONTROL
1693Architectures: s390
1694Type: vcpu ioctl
1695Parameters: struct kvm_s390_ucas_mapping (in)
1696Returns: 0 in case of success
1697
1698The parameter is defined like this:
1699        struct kvm_s390_ucas_mapping {
1700                __u64 user_addr;
1701                __u64 vcpu_addr;
1702                __u64 length;
1703        };
1704
1705This ioctl unmaps the memory in the vcpu's address space starting at
1706"vcpu_addr" with the length "length". The field "user_addr" is ignored.
1707All parameters need to be aligned by 1 megabyte.
1708
1709
17104.67 KVM_S390_VCPU_FAULT
1711
1712Capability: KVM_CAP_S390_UCONTROL
1713Architectures: s390
1714Type: vcpu ioctl
1715Parameters: vcpu absolute address (in)
1716Returns: 0 in case of success
1717
1718This call creates a page table entry on the virtual cpu's address space
1719(for user controlled virtual machines) or the virtual machine's address
1720space (for regular virtual machines). This only works for minor faults,
1721thus it's recommended to access subject memory page via the user page
1722table upfront. This is useful to handle validity intercepts for user
1723controlled virtual machines to fault in the virtual cpu's lowcore pages
1724prior to calling the KVM_RUN ioctl.
1725
1726
17274.68 KVM_SET_ONE_REG
1728
1729Capability: KVM_CAP_ONE_REG
1730Architectures: all
1731Type: vcpu ioctl
1732Parameters: struct kvm_one_reg (in)
1733Returns: 0 on success, negative value on failure
1734
1735struct kvm_one_reg {
1736       __u64 id;
1737       __u64 addr;
1738};
1739
1740Using this ioctl, a single vcpu register can be set to a specific value
1741defined by user space with the passed in struct kvm_one_reg, where id
1742refers to the register identifier as described below and addr is a pointer
1743to a variable with the respective size. There can be architecture agnostic
1744and architecture specific registers. Each have their own range of operation
1745and their own constants and width. To keep track of the implemented
1746registers, find a list below:
1747
1748  Arch  |       Register        | Width (bits)
1749        |                       |
1750  PPC   | KVM_REG_PPC_HIOR      | 64
1751  PPC   | KVM_REG_PPC_IAC1      | 64
1752  PPC   | KVM_REG_PPC_IAC2      | 64
1753  PPC   | KVM_REG_PPC_IAC3      | 64
1754  PPC   | KVM_REG_PPC_IAC4      | 64
1755  PPC   | KVM_REG_PPC_DAC1      | 64
1756  PPC   | KVM_REG_PPC_DAC2      | 64
1757  PPC   | KVM_REG_PPC_DABR      | 64
1758  PPC   | KVM_REG_PPC_DSCR      | 64
1759  PPC   | KVM_REG_PPC_PURR      | 64
1760  PPC   | KVM_REG_PPC_SPURR     | 64
1761  PPC   | KVM_REG_PPC_DAR       | 64
1762  PPC   | KVM_REG_PPC_DSISR     | 32
1763  PPC   | KVM_REG_PPC_AMR       | 64
1764  PPC   | KVM_REG_PPC_UAMOR     | 64
1765  PPC   | KVM_REG_PPC_MMCR0     | 64
1766  PPC   | KVM_REG_PPC_MMCR1     | 64
1767  PPC   | KVM_REG_PPC_MMCRA     | 64
1768  PPC   | KVM_REG_PPC_PMC1      | 32
1769  PPC   | KVM_REG_PPC_PMC2      | 32
1770  PPC   | KVM_REG_PPC_PMC3      | 32
1771  PPC   | KVM_REG_PPC_PMC4      | 32
1772  PPC   | KVM_REG_PPC_PMC5      | 32
1773  PPC   | KVM_REG_PPC_PMC6      | 32
1774  PPC   | KVM_REG_PPC_PMC7      | 32
1775  PPC   | KVM_REG_PPC_PMC8      | 32
1776  PPC   | KVM_REG_PPC_FPR0      | 64
1777          ...
1778  PPC   | KVM_REG_PPC_FPR31     | 64
1779  PPC   | KVM_REG_PPC_VR0       | 128
1780          ...
1781  PPC   | KVM_REG_PPC_VR31      | 128
1782  PPC   | KVM_REG_PPC_VSR0      | 128
1783          ...
1784  PPC   | KVM_REG_PPC_VSR31     | 128
1785  PPC   | KVM_REG_PPC_FPSCR     | 64
1786  PPC   | KVM_REG_PPC_VSCR      | 32
1787  PPC   | KVM_REG_PPC_VPA_ADDR  | 64
1788  PPC   | KVM_REG_PPC_VPA_SLB   | 128
1789  PPC   | KVM_REG_PPC_VPA_DTL   | 128
1790  PPC   | KVM_REG_PPC_EPCR      | 32
1791  PPC   | KVM_REG_PPC_EPR       | 32
1792  PPC   | KVM_REG_PPC_TCR       | 32
1793  PPC   | KVM_REG_PPC_TSR       | 32
1794  PPC   | KVM_REG_PPC_OR_TSR    | 32
1795  PPC   | KVM_REG_PPC_CLEAR_TSR | 32
1796  PPC   | KVM_REG_PPC_MAS0      | 32
1797  PPC   | KVM_REG_PPC_MAS1      | 32
1798  PPC   | KVM_REG_PPC_MAS2      | 64
1799  PPC   | KVM_REG_PPC_MAS7_3    | 64
1800  PPC   | KVM_REG_PPC_MAS4      | 32
1801  PPC   | KVM_REG_PPC_MAS6      | 32
1802  PPC   | KVM_REG_PPC_MMUCFG    | 32
1803  PPC   | KVM_REG_PPC_TLB0CFG   | 32
1804  PPC   | KVM_REG_PPC_TLB1CFG   | 32
1805  PPC   | KVM_REG_PPC_TLB2CFG   | 32
1806  PPC   | KVM_REG_PPC_TLB3CFG   | 32
1807  PPC   | KVM_REG_PPC_TLB0PS    | 32
1808  PPC   | KVM_REG_PPC_TLB1PS    | 32
1809  PPC   | KVM_REG_PPC_TLB2PS    | 32
1810  PPC   | KVM_REG_PPC_TLB3PS    | 32
1811  PPC   | KVM_REG_PPC_EPTCFG    | 32
1812  PPC   | KVM_REG_PPC_ICP_STATE | 64
1813
1814ARM registers are mapped using the lower 32 bits.  The upper 16 of that
1815is the register group type, or coprocessor number:
1816
1817ARM core registers have the following id bit patterns:
1818  0x4020 0000 0010 <index into the kvm_regs struct:16>
1819
1820ARM 32-bit CP15 registers have the following id bit patterns:
1821  0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3>
1822
1823ARM 64-bit CP15 registers have the following id bit patterns:
1824  0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3>
1825
1826ARM CCSIDR registers are demultiplexed by CSSELR value:
1827  0x4020 0000 0011 00 <csselr:8>
1828
1829ARM 32-bit VFP control registers have the following id bit patterns:
1830  0x4020 0000 0012 1 <regno:12>
1831
1832ARM 64-bit FP registers have the following id bit patterns:
1833  0x4030 0000 0012 0 <regno:12>
1834
1835
1836arm64 registers are mapped using the lower 32 bits. The upper 16 of
1837that is the register group type, or coprocessor number:
1838
1839arm64 core/FP-SIMD registers have the following id bit patterns. Note
1840that the size of the access is variable, as the kvm_regs structure
1841contains elements ranging from 32 to 128 bits. The index is a 32bit
1842value in the kvm_regs structure seen as a 32bit array.
1843  0x60x0 0000 0010 <index into the kvm_regs struct:16>
1844
1845arm64 CCSIDR registers are demultiplexed by CSSELR value:
1846  0x6020 0000 0011 00 <csselr:8>
1847
1848arm64 system registers have the following id bit patterns:
1849  0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3>
1850
18514.69 KVM_GET_ONE_REG
1852
1853Capability: KVM_CAP_ONE_REG
1854Architectures: all
1855Type: vcpu ioctl
1856Parameters: struct kvm_one_reg (in and out)
1857Returns: 0 on success, negative value on failure
1858
1859This ioctl allows to receive the value of a single register implemented
1860in a vcpu. The register to read is indicated by the "id" field of the
1861kvm_one_reg struct passed in. On success, the register value can be found
1862at the memory location pointed to by "addr".
1863
1864The list of registers accessible using this interface is identical to the
1865list in 4.68.
1866
1867
18684.70 KVM_KVMCLOCK_CTRL
1869
1870Capability: KVM_CAP_KVMCLOCK_CTRL
1871Architectures: Any that implement pvclocks (currently x86 only)
1872Type: vcpu ioctl
1873Parameters: None
1874Returns: 0 on success, -1 on error
1875
1876This signals to the host kernel that the specified guest is being paused by
1877userspace.  The host will set a flag in the pvclock structure that is checked
1878from the soft lockup watchdog.  The flag is part of the pvclock structure that
1879is shared between guest and host, specifically the second bit of the flags
1880field of the pvclock_vcpu_time_info structure.  It will be set exclusively by
1881the host and read/cleared exclusively by the guest.  The guest operation of
1882checking and clearing the flag must an atomic operation so
1883load-link/store-conditional, or equivalent must be used.  There are two cases
1884where the guest will clear the flag: when the soft lockup watchdog timer resets
1885itself or when a soft lockup is detected.  This ioctl can be called any time
1886after pausing the vcpu, but before it is resumed.
1887
1888
18894.71 KVM_SIGNAL_MSI
1890
1891Capability: KVM_CAP_SIGNAL_MSI
1892Architectures: x86
1893Type: vm ioctl
1894Parameters: struct kvm_msi (in)
1895Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
1896
1897Directly inject a MSI message. Only valid with in-kernel irqchip that handles
1898MSI messages.
1899
1900struct kvm_msi {
1901        __u32 address_lo;
1902        __u32 address_hi;
1903        __u32 data;
1904        __u32 flags;
1905        __u8  pad[16];
1906};
1907
1908No flags are defined so far. The corresponding field must be 0.
1909
1910
19114.71 KVM_CREATE_PIT2
1912
1913Capability: KVM_CAP_PIT2
1914Architectures: x86
1915Type: vm ioctl
1916Parameters: struct kvm_pit_config (in)
1917Returns: 0 on success, -1 on error
1918
1919Creates an in-kernel device model for the i8254 PIT. This call is only valid
1920after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following
1921parameters have to be passed:
1922
1923struct kvm_pit_config {
1924        __u32 flags;
1925        __u32 pad[15];
1926};
1927
1928Valid flags are:
1929
1930#define KVM_PIT_SPEAKER_DUMMY     1 /* emulate speaker port stub */
1931
1932PIT timer interrupts may use a per-VM kernel thread for injection. If it
1933exists, this thread will have a name of the following pattern:
1934
1935kvm-pit/<owner-process-pid>
1936
1937When running a guest with elevated priorities, the scheduling parameters of
1938this thread may have to be adjusted accordingly.
1939
1940This IOCTL replaces the obsolete KVM_CREATE_PIT.
1941
1942
19434.72 KVM_GET_PIT2
1944
1945Capability: KVM_CAP_PIT_STATE2
1946Architectures: x86
1947Type: vm ioctl
1948Parameters: struct kvm_pit_state2 (out)
1949Returns: 0 on success, -1 on error
1950
1951Retrieves the state of the in-kernel PIT model. Only valid after
1952KVM_CREATE_PIT2. The state is returned in the following structure:
1953
1954struct kvm_pit_state2 {
1955        struct kvm_pit_channel_state channels[3];
1956        __u32 flags;
1957        __u32 reserved[9];
1958};
1959
1960Valid flags are:
1961
1962/* disable PIT in HPET legacy mode */
1963#define KVM_PIT_FLAGS_HPET_LEGACY  0x00000001
1964
1965This IOCTL replaces the obsolete KVM_GET_PIT.
1966
1967
19684.73 KVM_SET_PIT2
1969
1970Capability: KVM_CAP_PIT_STATE2
1971Architectures: x86
1972Type: vm ioctl
1973Parameters: struct kvm_pit_state2 (in)
1974Returns: 0 on success, -1 on error
1975
1976Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
1977See KVM_GET_PIT2 for details on struct kvm_pit_state2.
1978
1979This IOCTL replaces the obsolete KVM_SET_PIT.
1980
1981
19824.74 KVM_PPC_GET_SMMU_INFO
1983
1984Capability: KVM_CAP_PPC_GET_SMMU_INFO
1985Architectures: powerpc
1986Type: vm ioctl
1987Parameters: None
1988Returns: 0 on success, -1 on error
1989
1990This populates and returns a structure describing the features of
1991the "Server" class MMU emulation supported by KVM.
1992This can in turn be used by userspace to generate the appropriate
1993device-tree properties for the guest operating system.
1994
1995The structure contains some global informations, followed by an
1996array of supported segment page sizes:
1997
1998      struct kvm_ppc_smmu_info {
1999             __u64 flags;
2000             __u32 slb_size;
2001             __u32 pad;
2002             struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ];
2003      };
2004
2005The supported flags are:
2006
2007    - KVM_PPC_PAGE_SIZES_REAL:
2008        When that flag is set, guest page sizes must "fit" the backing
2009        store page sizes. When not set, any page size in the list can
2010        be used regardless of how they are backed by userspace.
2011
2012    - KVM_PPC_1T_SEGMENTS
2013        The emulated MMU supports 1T segments in addition to the
2014        standard 256M ones.
2015
2016The "slb_size" field indicates how many SLB entries are supported
2017
2018The "sps" array contains 8 entries indicating the supported base
2019page sizes for a segment in increasing order. Each entry is defined
2020as follow:
2021
2022   struct kvm_ppc_one_seg_page_size {
2023        __u32 page_shift;       /* Base page shift of segment (or 0) */
2024        __u32 slb_enc;          /* SLB encoding for BookS */
2025        struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ];
2026   };
2027
2028An entry with a "page_shift" of 0 is unused. Because the array is
2029organized in increasing order, a lookup can stop when encoutering
2030such an entry.
2031
2032The "slb_enc" field provides the encoding to use in the SLB for the
2033page size. The bits are in positions such as the value can directly
2034be OR'ed into the "vsid" argument of the slbmte instruction.
2035
2036The "enc" array is a list which for each of those segment base page
2037size provides the list of supported actual page sizes (which can be
2038only larger or equal to the base page size), along with the
2039corresponding encoding in the hash PTE. Similarly, the array is
20408 entries sorted by increasing sizes and an entry with a "0" shift
2041is an empty entry and a terminator:
2042
2043   struct kvm_ppc_one_page_size {
2044        __u32 page_shift;       /* Page shift (or 0) */
2045        __u32 pte_enc;          /* Encoding in the HPTE (>>12) */
2046   };
2047
2048The "pte_enc" field provides a value that can OR'ed into the hash
2049PTE's RPN field (ie, it needs to be shifted left by 12 to OR it
2050into the hash PTE second double word).
2051
20524.75 KVM_IRQFD
2053
2054Capability: KVM_CAP_IRQFD
2055Architectures: x86
2056Type: vm ioctl
2057Parameters: struct kvm_irqfd (in)
2058Returns: 0 on success, -1 on error
2059
2060Allows setting an eventfd to directly trigger a guest interrupt.
2061kvm_irqfd.fd specifies the file descriptor to use as the eventfd and
2062kvm_irqfd.gsi specifies the irqchip pin toggled by this event.  When
2063an event is tiggered on the eventfd, an interrupt is injected into
2064the guest using the specified gsi pin.  The irqfd is removed using
2065the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd
2066and kvm_irqfd.gsi.
2067
2068With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify
2069mechanism allowing emulation of level-triggered, irqfd-based
2070interrupts.  When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an
2071additional eventfd in the kvm_irqfd.resamplefd field.  When operating
2072in resample mode, posting of an interrupt through kvm_irq.fd asserts
2073the specified gsi in the irqchip.  When the irqchip is resampled, such
2074as from an EOI, the gsi is de-asserted and the user is notifed via
2075kvm_irqfd.resamplefd.  It is the user's responsibility to re-queue
2076the interrupt if the device making use of it still requires service.
2077Note that closing the resamplefd is not sufficient to disable the
2078irqfd.  The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment
2079and need not be specified with KVM_IRQFD_FLAG_DEASSIGN.
2080
20814.76 KVM_PPC_ALLOCATE_HTAB
2082
2083Capability: KVM_CAP_PPC_ALLOC_HTAB
2084Architectures: powerpc
2085Type: vm ioctl
2086Parameters: Pointer to u32 containing hash table order (in/out)
2087Returns: 0 on success, -1 on error
2088
2089This requests the host kernel to allocate an MMU hash table for a
2090guest using the PAPR paravirtualization interface.  This only does
2091anything if the kernel is configured to use the Book 3S HV style of
2092virtualization.  Otherwise the capability doesn't exist and the ioctl
2093returns an ENOTTY error.  The rest of this description assumes Book 3S
2094HV.
2095
2096There must be no vcpus running when this ioctl is called; if there
2097are, it will do nothing and return an EBUSY error.
2098
2099The parameter is a pointer to a 32-bit unsigned integer variable
2100containing the order (log base 2) of the desired size of the hash
2101table, which must be between 18 and 46.  On successful return from the
2102ioctl, it will have been updated with the order of the hash table that
2103was allocated.
2104
2105If no hash table has been allocated when any vcpu is asked to run
2106(with the KVM_RUN ioctl), the host kernel will allocate a
2107default-sized hash table (16 MB).
2108
2109If this ioctl is called when a hash table has already been allocated,
2110the kernel will clear out the existing hash table (zero all HPTEs) and
2111return the hash table order in the parameter.  (If the guest is using
2112the virtualized real-mode area (VRMA) facility, the kernel will
2113re-create the VMRA HPTEs on the next KVM_RUN of any vcpu.)
2114
21154.77 KVM_S390_INTERRUPT
2116
2117Capability: basic
2118Architectures: s390
2119Type: vm ioctl, vcpu ioctl
2120Parameters: struct kvm_s390_interrupt (in)
2121Returns: 0 on success, -1 on error
2122
2123Allows to inject an interrupt to the guest. Interrupts can be floating
2124(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.
2125
2126Interrupt parameters are passed via kvm_s390_interrupt:
2127
2128struct kvm_s390_interrupt {
2129        __u32 type;
2130        __u32 parm;
2131        __u64 parm64;
2132};
2133
2134type can be one of the following:
2135
2136KVM_S390_SIGP_STOP (vcpu) - sigp restart
2137KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm
2138KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm
2139KVM_S390_RESTART (vcpu) - restart
2140KVM_S390_INT_VIRTIO (vm) - virtio external interrupt; external interrupt
2141                           parameters in parm and parm64
2142KVM_S390_INT_SERVICE (vm) - sclp external interrupt; sclp parameter in parm
2143KVM_S390_INT_EMERGENCY (vcpu) - sigp emergency; source cpu in parm
2144KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm
2145KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm) - compound value to indicate an
2146    I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);
2147    I/O interruption parameters in parm (subchannel) and parm64 (intparm,
2148    interruption subclass)
2149KVM_S390_MCHK (vm, vcpu) - machine check interrupt; cr 14 bits in parm,
2150                           machine check interrupt code in parm64 (note that
2151                           machine checks needing further payload are not
2152                           supported by this ioctl)
2153
2154Note that the vcpu ioctl is asynchronous to vcpu execution.
2155
21564.78 KVM_PPC_GET_HTAB_FD
2157
2158Capability: KVM_CAP_PPC_HTAB_FD
2159Architectures: powerpc
2160Type: vm ioctl
2161Parameters: Pointer to struct kvm_get_htab_fd (in)
2162Returns: file descriptor number (>= 0) on success, -1 on error
2163
2164This returns a file descriptor that can be used either to read out the
2165entries in the guest's hashed page table (HPT), or to write entries to
2166initialize the HPT.  The returned fd can only be written to if the
2167KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
2168can only be read if that bit is clear.  The argument struct looks like
2169this:
2170
2171/* For KVM_PPC_GET_HTAB_FD */
2172struct kvm_get_htab_fd {
2173        __u64   flags;
2174        __u64   start_index;
2175        __u64   reserved[2];
2176};
2177
2178/* Values for kvm_get_htab_fd.flags */
2179#define KVM_GET_HTAB_BOLTED_ONLY        ((__u64)0x1)
2180#define KVM_GET_HTAB_WRITE              ((__u64)0x2)
2181
2182The `start_index' field gives the index in the HPT of the entry at
2183which to start reading.  It is ignored when writing.
2184
2185Reads on the fd will initially supply information about all
2186"interesting" HPT entries.  Interesting entries are those with the
2187bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise
2188all entries.  When the end of the HPT is reached, the read() will
2189return.  If read() is called again on the fd, it will start again from
2190the beginning of the HPT, but will only return HPT entries that have
2191changed since they were last read.
2192
2193Data read or written is structured as a header (8 bytes) followed by a
2194series of valid HPT entries (16 bytes) each.  The header indicates how
2195many valid HPT entries there are and how many invalid entries follow
2196the valid entries.  The invalid entries are not represented explicitly
2197in the stream.  The header format is:
2198
2199struct kvm_get_htab_header {
2200        __u32   index;
2201        __u16   n_valid;
2202        __u16   n_invalid;
2203};
2204
2205Writes to the fd create HPT entries starting at the index given in the
2206header; first `n_valid' valid entries with contents from the data
2207written, then `n_invalid' invalid entries, invalidating any previously
2208valid entries found.
2209
22104.79 KVM_CREATE_DEVICE
2211
2212Capability: KVM_CAP_DEVICE_CTRL
2213Type: vm ioctl
2214Parameters: struct kvm_create_device (in/out)
2215Returns: 0 on success, -1 on error
2216Errors:
2217  ENODEV: The device type is unknown or unsupported
2218  EEXIST: Device already created, and this type of device may not
2219          be instantiated multiple times
2220
2221  Other error conditions may be defined by individual device types or
2222  have their standard meanings.
2223
2224Creates an emulated device in the kernel.  The file descriptor returned
2225in fd can be used with KVM_SET/GET/HAS_DEVICE_ATTR.
2226
2227If the KVM_CREATE_DEVICE_TEST flag is set, only test whether the
2228device type is supported (not necessarily whether it can be created
2229in the current vm).
2230
2231Individual devices should not define flags.  Attributes should be used
2232for specifying any behavior that is not implied by the device type
2233number.
2234
2235struct kvm_create_device {
2236        __u32   type;   /* in: KVM_DEV_TYPE_xxx */
2237        __u32   fd;     /* out: device handle */
2238        __u32   flags;  /* in: KVM_CREATE_DEVICE_xxx */
2239};
2240
22414.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR
2242
2243Capability: KVM_CAP_DEVICE_CTRL
2244Type: device ioctl
2245Parameters: struct kvm_device_attr
2246Returns: 0 on success, -1 on error
2247Errors:
2248  ENXIO:  The group or attribute is unknown/unsupported for this device
2249  EPERM:  The attribute cannot (currently) be accessed this way
2250          (e.g. read-only attribute, or attribute that only makes
2251          sense when the device is in a different state)
2252
2253  Other error conditions may be defined by individual device types.
2254
2255Gets/sets a specified piece of device configuration and/or state.  The
2256semantics are device-specific.  See individual device documentation in
2257the "devices" directory.  As with ONE_REG, the size of the data
2258transferred is defined by the particular attribute.
2259
2260struct kvm_device_attr {
2261        __u32   flags;          /* no flags currently defined */
2262        __u32   group;          /* device-defined */
2263        __u64   attr;           /* group-defined */
2264        __u64   addr;           /* userspace address of attr data */
2265};
2266
22674.81 KVM_HAS_DEVICE_ATTR
2268
2269Capability: KVM_CAP_DEVICE_CTRL
2270Type: device ioctl
2271Parameters: struct kvm_device_attr
2272Returns: 0 on success, -1 on error
2273Errors:
2274  ENXIO:  The group or attribute is unknown/unsupported for this device
2275
2276Tests whether a device supports a particular attribute.  A successful
2277return indicates the attribute is implemented.  It does not necessarily
2278indicate that the attribute can be read or written in the device's
2279current state.  "addr" is ignored.
2280
22814.82 KVM_ARM_VCPU_INIT
2282
2283Capability: basic
2284Architectures: arm, arm64
2285Type: vcpu ioctl
2286Parameters: struct struct kvm_vcpu_init (in)
2287Returns: 0 on success; -1 on error
2288Errors:
2289 \xC2\xA0EINVAL: \xC2\xA0\xC2\xA0\xC2\xA0the target is unknown, or the combination of features is invalid.
2290 \xC2\xA0ENOENT: \xC2\xA0\xC2\xA0\xC2\xA0a features bit specified is unknown.
2291
2292This tells KVM what type of CPU to present to the guest, and what
2293optional features it should have. \xC2\xA0This will cause a reset of the cpu
2294registers to their initial values. \xC2\xA0If this is not called, KVM_RUN will
2295return ENOEXEC for that vcpu.
2296
2297Note that because some registers reflect machine topology, all vcpus
2298should be created before this ioctl is invoked.
2299
2300Possible features:
2301        - KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state.
2302          Depends on KVM_CAP_ARM_PSCI.
2303        - KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode.
2304          Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only).
2305
2306
23074.83 KVM_GET_REG_LIST
2308
2309Capability: basic
2310Architectures: arm, arm64
2311Type: vcpu ioctl
2312Parameters: struct kvm_reg_list (in/out)
2313Returns: 0 on success; -1 on error
2314Errors:
2315 \xC2\xA0E2BIG: \xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0the reg index list is too big to fit in the array specified by
2316 \xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0\xC2\xA0the user (the number required will be written into n).
2317
2318struct kvm_reg_list {
2319        __u64 n; /* number of registers in reg[] */
2320        __u64 reg[0];
2321};
2322
2323This ioctl returns the guest registers that are supported for the
2324KVM_GET_ONE_REG/KVM_SET_ONE_REG calls.
2325
2326
23274.84 KVM_ARM_SET_DEVICE_ADDR
2328
2329Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
2330Architectures: arm, arm64
2331Type: vm ioctl
2332Parameters: struct kvm_arm_device_address (in)
2333Returns: 0 on success, -1 on error
2334Errors:
2335  ENODEV: The device id is unknown
2336  ENXIO:  Device not supported on current system
2337  EEXIST: Address already set
2338  E2BIG:  Address outside guest physical address space
2339  EBUSY:  Address overlaps with other device range
2340
2341struct kvm_arm_device_addr {
2342        __u64 id;
2343        __u64 addr;
2344};
2345
2346Specify a device address in the guest's physical address space where guests
2347can access emulated or directly exposed devices, which the host kernel needs
2348to know about. The id field is an architecture specific identifier for a
2349specific device.
2350
2351ARM/arm64 divides the id field into two parts, a device id and an
2352address type id specific to the individual device.
2353
2354 \xC2\xA0bits:  | 63        ...       32 | 31    ...    16 | 15    ...    0 |
2355  field: |        0x00000000      |     device id   |  addr type id  |
2356
2357ARM/arm64 currently only require this when using the in-kernel GIC
2358support for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2
2359as the device id.  When setting the base address for the guest's
2360mapping of the VGIC virtual CPU and distributor interface, the ioctl
2361must be called after calling KVM_CREATE_IRQCHIP, but before calling
2362KVM_RUN on any of the VCPUs.  Calling this ioctl twice for any of the
2363base addresses will return -EEXIST.
2364
23654.85 KVM_PPC_RTAS_DEFINE_TOKEN
2366
2367Capability: KVM_CAP_PPC_RTAS
2368Architectures: ppc
2369Type: vm ioctl
2370Parameters: struct kvm_rtas_token_args
2371Returns: 0 on success, -1 on error
2372
2373Defines a token value for a RTAS (Run Time Abstraction Services)
2374service in order to allow it to be handled in the kernel.  The
2375argument struct gives the name of the service, which must be the name
2376of a service that has a kernel-side implementation.  If the token
2377value is non-zero, it will be associated with that service, and
2378subsequent RTAS calls by the guest specifying that token will be
2379handled by the kernel.  If the token value is 0, then any token
2380associated with the service will be forgotten, and subsequent RTAS
2381calls by the guest for that service will be passed to userspace to be
2382handled.
2383
2384
23855. The kvm_run structure
2386------------------------
2387
2388Application code obtains a pointer to the kvm_run structure by
2389mmap()ing a vcpu fd.  From that point, application code can control
2390execution by changing fields in kvm_run prior to calling the KVM_RUN
2391ioctl, and obtain information about the reason KVM_RUN returned by
2392looking up structure members.
2393
2394struct kvm_run {
2395        /* in */
2396        __u8 request_interrupt_window;
2397
2398Request that KVM_RUN return when it becomes possible to inject external
2399interrupts into the guest.  Useful in conjunction with KVM_INTERRUPT.
2400
2401        __u8 padding1[7];
2402
2403        /* out */
2404        __u32 exit_reason;
2405
2406When KVM_RUN has returned successfully (return value 0), this informs
2407application code why KVM_RUN has returned.  Allowable values for this
2408field are detailed below.
2409
2410        __u8 ready_for_interrupt_injection;
2411
2412If request_interrupt_window has been specified, this field indicates
2413an interrupt can be injected now with KVM_INTERRUPT.
2414
2415        __u8 if_flag;
2416
2417The value of the current interrupt flag.  Only valid if in-kernel
2418local APIC is not used.
2419
2420        __u8 padding2[2];
2421
2422        /* in (pre_kvm_run), out (post_kvm_run) */
2423        __u64 cr8;
2424
2425The value of the cr8 register.  Only valid if in-kernel local APIC is
2426not used.  Both input and output.
2427
2428        __u64 apic_base;
2429
2430The value of the APIC BASE msr.  Only valid if in-kernel local
2431APIC is not used.  Both input and output.
2432
2433        union {
2434                /* KVM_EXIT_UNKNOWN */
2435                struct {
2436                        __u64 hardware_exit_reason;
2437                } hw;
2438
2439If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
2440reasons.  Further architecture-specific information is available in
2441hardware_exit_reason.
2442
2443                /* KVM_EXIT_FAIL_ENTRY */
2444                struct {
2445                        __u64 hardware_entry_failure_reason;
2446                } fail_entry;
2447
2448If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
2449to unknown reasons.  Further architecture-specific information is
2450available in hardware_entry_failure_reason.
2451
2452                /* KVM_EXIT_EXCEPTION */
2453                struct {
2454                        __u32 exception;
2455                        __u32 error_code;
2456                } ex;
2457
2458Unused.
2459
2460                /* KVM_EXIT_IO */
2461                struct {
2462#define KVM_EXIT_IO_IN  0
2463#define KVM_EXIT_IO_OUT 1
2464                        __u8 direction;
2465                        __u8 size; /* bytes */
2466                        __u16 port;
2467                        __u32 count;
2468                        __u64 data_offset; /* relative to kvm_run start */
2469                } io;
2470
2471If exit_reason is KVM_EXIT_IO, then the vcpu has
2472executed a port I/O instruction which could not be satisfied by kvm.
2473data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
2474where kvm expects application code to place the data for the next
2475KVM_RUN invocation (KVM_EXIT_IO_IN).  Data format is a packed array.
2476
2477                struct {
2478                        struct kvm_debug_exit_arch arch;
2479                } debug;
2480
2481Unused.
2482
2483                /* KVM_EXIT_MMIO */
2484                struct {
2485                        __u64 phys_addr;
2486                        __u8  data[8];
2487                        __u32 len;
2488                        __u8  is_write;
2489                } mmio;
2490
2491If exit_reason is KVM_EXIT_MMIO, then the vcpu has
2492executed a memory-mapped I/O instruction which could not be satisfied
2493by kvm.  The 'data' member contains the written data if 'is_write' is
2494true, and should be filled by application code otherwise.
2495
2496NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_DCR,
2497      KVM_EXIT_PAPR and KVM_EXIT_EPR the corresponding
2498operations are complete (and guest state is consistent) only after userspace
2499has re-entered the kernel with KVM_RUN.  The kernel side will first finish
2500incomplete operations and then check for pending signals.  Userspace
2501can re-enter the guest with an unmasked signal pending to complete
2502pending operations.
2503
2504                /* KVM_EXIT_HYPERCALL */
2505                struct {
2506                        __u64 nr;
2507                        __u64 args[6];
2508                        __u64 ret;
2509                        __u32 longmode;
2510                        __u32 pad;
2511                } hypercall;
2512
2513Unused.  This was once used for 'hypercall to userspace'.  To implement
2514such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
2515Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
2516
2517                /* KVM_EXIT_TPR_ACCESS */
2518                struct {
2519                        __u64 rip;
2520                        __u32 is_write;
2521                        __u32 pad;
2522                } tpr_access;
2523
2524To be documented (KVM_TPR_ACCESS_REPORTING).
2525
2526                /* KVM_EXIT_S390_SIEIC */
2527                struct {
2528                        __u8 icptcode;
2529                        __u64 mask; /* psw upper half */
2530                        __u64 addr; /* psw lower half */
2531                        __u16 ipa;
2532                        __u32 ipb;
2533                } s390_sieic;
2534
2535s390 specific.
2536
2537                /* KVM_EXIT_S390_RESET */
2538#define KVM_S390_RESET_POR       1
2539#define KVM_S390_RESET_CLEAR     2
2540#define KVM_S390_RESET_SUBSYSTEM 4
2541#define KVM_S390_RESET_CPU_INIT  8
2542#define KVM_S390_RESET_IPL       16
2543                __u64 s390_reset_flags;
2544
2545s390 specific.
2546
2547                /* KVM_EXIT_S390_UCONTROL */
2548                struct {
2549                        __u64 trans_exc_code;
2550                        __u32 pgm_code;
2551                } s390_ucontrol;
2552
2553s390 specific. A page fault has occurred for a user controlled virtual
2554machine (KVM_VM_S390_UNCONTROL) on it's host page table that cannot be
2555resolved by the kernel.
2556The program code and the translation exception code that were placed
2557in the cpu's lowcore are presented here as defined by the z Architecture
2558Principles of Operation Book in the Chapter for Dynamic Address Translation
2559(DAT)
2560
2561                /* KVM_EXIT_DCR */
2562                struct {
2563                        __u32 dcrn;
2564                        __u32 data;
2565                        __u8  is_write;
2566                } dcr;
2567
2568powerpc specific.
2569
2570                /* KVM_EXIT_OSI */
2571                struct {
2572                        __u64 gprs[32];
2573                } osi;
2574
2575MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
2576hypercalls and exit with this exit struct that contains all the guest gprs.
2577
2578If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
2579Userspace can now handle the hypercall and when it's done modify the gprs as
2580necessary. Upon guest entry all guest GPRs will then be replaced by the values
2581in this struct.
2582
2583                /* KVM_EXIT_PAPR_HCALL */
2584                struct {
2585                        __u64 nr;
2586                        __u64 ret;
2587                        __u64 args[9];
2588                } papr_hcall;
2589
2590This is used on 64-bit PowerPC when emulating a pSeries partition,
2591e.g. with the 'pseries' machine type in qemu.  It occurs when the
2592guest does a hypercall using the 'sc 1' instruction.  The 'nr' field
2593contains the hypercall number (from the guest R3), and 'args' contains
2594the arguments (from the guest R4 - R12).  Userspace should put the
2595return code in 'ret' and any extra returned values in args[].
2596The possible hypercalls are defined in the Power Architecture Platform
2597Requirements (PAPR) document available from www.power.org (free
2598developer registration required to access it).
2599
2600                /* KVM_EXIT_S390_TSCH */
2601                struct {
2602                        __u16 subchannel_id;
2603                        __u16 subchannel_nr;
2604                        __u32 io_int_parm;
2605                        __u32 io_int_word;
2606                        __u32 ipb;
2607                        __u8 dequeued;
2608                } s390_tsch;
2609
2610s390 specific. This exit occurs when KVM_CAP_S390_CSS_SUPPORT has been enabled
2611and TEST SUBCHANNEL was intercepted. If dequeued is set, a pending I/O
2612interrupt for the target subchannel has been dequeued and subchannel_id,
2613subchannel_nr, io_int_parm and io_int_word contain the parameters for that
2614interrupt. ipb is needed for instruction parameter decoding.
2615
2616                /* KVM_EXIT_EPR */
2617                struct {
2618                        __u32 epr;
2619                } epr;
2620
2621On FSL BookE PowerPC chips, the interrupt controller has a fast patch
2622interrupt acknowledge path to the core. When the core successfully
2623delivers an interrupt, it automatically populates the EPR register with
2624the interrupt vector number and acknowledges the interrupt inside
2625the interrupt controller.
2626
2627In case the interrupt controller lives in user space, we need to do
2628the interrupt acknowledge cycle through it to fetch the next to be
2629delivered interrupt vector using this exit.
2630
2631It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an
2632external interrupt has just been delivered into the guest. User space
2633should put the acknowledged interrupt vector into the 'epr' field.
2634
2635                /* Fix the size of the union. */
2636                char padding[256];
2637        };
2638
2639        /*
2640         * shared registers between kvm and userspace.
2641         * kvm_valid_regs specifies the register classes set by the host
2642         * kvm_dirty_regs specified the register classes dirtied by userspace
2643         * struct kvm_sync_regs is architecture specific, as well as the
2644         * bits for kvm_valid_regs and kvm_dirty_regs
2645         */
2646        __u64 kvm_valid_regs;
2647        __u64 kvm_dirty_regs;
2648        union {
2649                struct kvm_sync_regs regs;
2650                char padding[1024];
2651        } s;
2652
2653If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access
2654certain guest registers without having to call SET/GET_*REGS. Thus we can
2655avoid some system call overhead if userspace has to handle the exit.
2656Userspace can query the validity of the structure by checking
2657kvm_valid_regs for specific bits. These bits are architecture specific
2658and usually define the validity of a groups of registers. (e.g. one bit
2659 for general purpose registers)
2660
2661};
2662
2663
26646. Capabilities that can be enabled
2665-----------------------------------
2666
2667There are certain capabilities that change the behavior of the virtual CPU when
2668enabled. To enable them, please see section 4.37. Below you can find a list of
2669capabilities and what their effect on the vCPU is when enabling them.
2670
2671The following information is provided along with the description:
2672
2673  Architectures: which instruction set architectures provide this ioctl.
2674      x86 includes both i386 and x86_64.
2675
2676  Parameters: what parameters are accepted by the capability.
2677
2678  Returns: the return value.  General error numbers (EBADF, ENOMEM, EINVAL)
2679      are not detailed, but errors with specific meanings are.
2680
2681
26826.1 KVM_CAP_PPC_OSI
2683
2684Architectures: ppc
2685Parameters: none
2686Returns: 0 on success; -1 on error
2687
2688This capability enables interception of OSI hypercalls that otherwise would
2689be treated as normal system calls to be injected into the guest. OSI hypercalls
2690were invented by Mac-on-Linux to have a standardized communication mechanism
2691between the guest and the host.
2692
2693When this capability is enabled, KVM_EXIT_OSI can occur.
2694
2695
26966.2 KVM_CAP_PPC_PAPR
2697
2698Architectures: ppc
2699Parameters: none
2700Returns: 0 on success; -1 on error
2701
2702This capability enables interception of PAPR hypercalls. PAPR hypercalls are
2703done using the hypercall instruction "sc 1".
2704
2705It also sets the guest privilege level to "supervisor" mode. Usually the guest
2706runs in "hypervisor" privilege mode with a few missing features.
2707
2708In addition to the above, it changes the semantics of SDR1. In this mode, the
2709HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
2710HTAB invisible to the guest.
2711
2712When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
2713
2714
27156.3 KVM_CAP_SW_TLB
2716
2717Architectures: ppc
2718Parameters: args[0] is the address of a struct kvm_config_tlb
2719Returns: 0 on success; -1 on error
2720
2721struct kvm_config_tlb {
2722        __u64 params;
2723        __u64 array;
2724        __u32 mmu_type;
2725        __u32 array_len;
2726};
2727
2728Configures the virtual CPU's TLB array, establishing a shared memory area
2729between userspace and KVM.  The "params" and "array" fields are userspace
2730addresses of mmu-type-specific data structures.  The "array_len" field is an
2731safety mechanism, and should be set to the size in bytes of the memory that
2732userspace has reserved for the array.  It must be at least the size dictated
2733by "mmu_type" and "params".
2734
2735While KVM_RUN is active, the shared region is under control of KVM.  Its
2736contents are undefined, and any modification by userspace results in
2737boundedly undefined behavior.
2738
2739On return from KVM_RUN, the shared region will reflect the current state of
2740the guest's TLB.  If userspace makes any changes, it must call KVM_DIRTY_TLB
2741to tell KVM which entries have been changed, prior to calling KVM_RUN again
2742on this vcpu.
2743
2744For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
2745 - The "params" field is of type "struct kvm_book3e_206_tlb_params".
2746 - The "array" field points to an array of type "struct
2747   kvm_book3e_206_tlb_entry".
2748 - The array consists of all entries in the first TLB, followed by all
2749   entries in the second TLB.
2750 - Within a TLB, entries are ordered first by increasing set number.  Within a
2751   set, entries are ordered by way (increasing ESEL).
2752 - The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1)
2753   where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value.
2754 - The tsize field of mas1 shall be set to 4K on TLB0, even though the
2755   hardware ignores this value for TLB0.
2756
27576.4 KVM_CAP_S390_CSS_SUPPORT
2758
2759Architectures: s390
2760Parameters: none
2761Returns: 0 on success; -1 on error
2762
2763This capability enables support for handling of channel I/O instructions.
2764
2765TEST PENDING INTERRUPTION and the interrupt portion of TEST SUBCHANNEL are
2766handled in-kernel, while the other I/O instructions are passed to userspace.
2767
2768When this capability is enabled, KVM_EXIT_S390_TSCH will occur on TEST
2769SUBCHANNEL intercepts.
2770
27716.5 KVM_CAP_PPC_EPR
2772
2773Architectures: ppc
2774Parameters: args[0] defines whether the proxy facility is active
2775Returns: 0 on success; -1 on error
2776
2777This capability enables or disables the delivery of interrupts through the
2778external proxy facility.
2779
2780When enabled (args[0] != 0), every time the guest gets an external interrupt
2781delivered, it automatically exits into user space with a KVM_EXIT_EPR exit
2782to receive the topmost interrupt vector.
2783
2784When disabled (args[0] == 0), behavior is as if this facility is unsupported.
2785
2786When this capability is enabled, KVM_EXIT_EPR can occur.
2787
27886.6 KVM_CAP_IRQ_MPIC
2789
2790Architectures: ppc
2791Parameters: args[0] is the MPIC device fd
2792            args[1] is the MPIC CPU number for this vcpu
2793
2794This capability connects the vcpu to an in-kernel MPIC device.
2795
27966.7 KVM_CAP_IRQ_XICS
2797
2798Architectures: ppc
2799Parameters: args[0] is the XICS device fd
2800            args[1] is the XICS CPU number (server ID) for this vcpu
2801
2802This capability connects the vcpu to an in-kernel XICS device.
2803
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.