1 The Definitive KVM (Kernel-based Virtual Machine) API Documentation
2 ===================================================================
6 The kvm API is a set of ioctls that are issued to control various aspects
7 of a virtual machine. The ioctls belong to three classes
9 - System ioctls: These query and set global attributes which affect the
10 whole kvm subsystem. In addition a system ioctl is used to create
13 - VM ioctls: These query and set attributes that affect an entire virtual
14 machine, for example memory layout. In addition a VM ioctl is used to
15 create virtual cpus (vcpus).
17 Only run VM ioctls from the same process (address space) that was used
20 - vcpu ioctls: These query and set attributes that control the operation
21 of a single virtual cpu.
23 Only run vcpu ioctls from the same thread that was used to create the
28 The kvm API is centered around file descriptors. An initial
29 open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
30 can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this
31 handle will create a VM file descriptor which can be used to issue VM
32 ioctls. A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu
33 and return a file descriptor pointing to it. Finally, ioctls on a vcpu
34 fd can be used to control the vcpu, including the important task of
35 actually running guest code.
37 In general file descriptors can be migrated among processes by means
38 of fork() and the SCM_RIGHTS facility of unix domain socket. These
39 kinds of tricks are explicitly not supported by kvm. While they will
40 not cause harm to the host, their actual behavior is not guaranteed by
41 the API. The only supported use is one virtual machine per process,
42 and one vcpu per thread.
46 As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
47 incompatible change are allowed. However, there is an extension
48 facility that allows backward-compatible extensions to the API to be
51 The extension mechanism is not based on on the Linux version number.
52 Instead, kvm defines extension identifiers and a facility to query
53 whether a particular extension identifier is available. If it is, a
54 set of ioctls is available for application use.
58 This section describes ioctls that can be used to control kvm guests.
59 For each ioctl, the following information is provided along with a
62 Capability: which KVM extension provides this ioctl. Can be 'basic',
63 which means that is will be provided by any kernel that supports
64 API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which
65 means availability needs to be checked with KVM_CHECK_EXTENSION
68 Architectures: which instruction set architectures provide this ioctl.
69 x86 includes both i386 and x86_64.
71 Type: system, vm, or vcpu.
73 Parameters: what parameters are accepted by the ioctl.
75 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
76 are not detailed, but errors with specific meanings are.
78 4.1 KVM_GET_API_VERSION
84 Returns: the constant KVM_API_VERSION (=12)
86 This identifies the API version as the stable kvm API. It is not
87 expected that this number will change. However, Linux 2.6.20 and
88 2.6.21 report earlier versions; these are not documented and not
89 supported. Applications should refuse to run if KVM_GET_API_VERSION
90 returns a value other than 12. If this check passes, all ioctls
91 described as 'basic' will be available.
99 Returns: a VM fd that can be used to control the new virtual machine.
101 The new VM has no virtual cpus and no memory. An mmap() of a VM fd
102 will access the virtual machine's physical address space; offset zero
103 corresponds to guest physical address zero. Use of mmap() on a VM fd
104 is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is
107 4.3 KVM_GET_MSR_INDEX_LIST
112 Parameters: struct kvm_msr_list (in/out)
113 Returns: 0 on success; -1 on error
115 E2BIG: the msr index list is to be to fit in the array specified by
118 struct kvm_msr_list {
119 __u32 nmsrs; /* number of msrs in entries */
123 This ioctl returns the guest msrs that are supported. The list varies
124 by kvm version and host processor, but does not change otherwise. The
125 user fills in the size of the indices array in nmsrs, and in return
126 kvm adjusts nmsrs to reflect the actual number of msrs and fills in
127 the indices array with their numbers.
129 Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
130 not returned in the MSR list, as different vcpus can have a different number
131 of banks, as set via the KVM_X86_SETUP_MCE ioctl.
133 4.4 KVM_CHECK_EXTENSION
138 Parameters: extension identifier (KVM_CAP_*)
139 Returns: 0 if unsupported; 1 (or some other positive integer) if supported
141 The API allows the application to query about extensions to the core
142 kvm API. Userspace passes an extension identifier (an integer) and
143 receives an integer that describes the extension availability.
144 Generally 0 means no and 1 means yes, but some extensions may report
145 additional information in the integer return value.
147 4.5 KVM_GET_VCPU_MMAP_SIZE
153 Returns: size of vcpu mmap area, in bytes
155 The KVM_RUN ioctl (cf.) communicates with userspace via a shared
156 memory region. This ioctl returns the size of that region. See the
157 KVM_RUN documentation for details.
159 4.6 KVM_SET_MEMORY_REGION
164 Parameters: struct kvm_memory_region (in)
165 Returns: 0 on success, -1 on error
167 This ioctl is obsolete and has been removed.
174 Parameters: vcpu id (apic id on x86)
175 Returns: vcpu fd on success, -1 on error
177 This API adds a vcpu to a virtual machine. The vcpu id is a small integer
178 in the range [0, max_vcpus).
180 The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of
181 the KVM_CHECK_EXTENSION ioctl() at run-time.
182 The maximum possible value for max_vcpus can be retrieved using the
183 KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.
185 If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
187 If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is
188 same as the value returned from KVM_CAP_NR_VCPUS.
190 On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
191 threads in one or more virtual CPU cores. (This is because the
192 hardware requires all the hardware threads in a CPU core to be in the
193 same partition.) The KVM_CAP_PPC_SMT capability indicates the number
194 of vcpus per virtual core (vcore). The vcore id is obtained by
195 dividing the vcpu id by the number of vcpus per vcore. The vcpus in a
196 given vcore will always be in the same physical core as each other
197 (though that might be a different physical core from time to time).
198 Userspace can control the threading (SMT) mode of the guest by its
199 allocation of vcpu ids. For example, if userspace wants
200 single-threaded guest vcpus, it should make all vcpu ids be a multiple
201 of the number of vcpus per vcore.
203 4.8 KVM_GET_DIRTY_LOG (vm ioctl)
208 Parameters: struct kvm_dirty_log (in/out)
209 Returns: 0 on success, -1 on error
211 /* for KVM_GET_DIRTY_LOG */
212 struct kvm_dirty_log {
216 void __user *dirty_bitmap; /* one bit per page */
221 Given a memory slot, return a bitmap containing any pages dirtied
222 since the last call to this ioctl. Bit 0 is the first page in the
223 memory slot. Ensure the entire structure is cleared to avoid padding
226 4.9 KVM_SET_MEMORY_ALIAS
231 Parameters: struct kvm_memory_alias (in)
232 Returns: 0 (success), -1 (error)
234 This ioctl is obsolete and has been removed.
242 Returns: 0 on success, -1 on error
244 EINTR: an unmasked signal is pending
246 This ioctl is used to run a guest virtual cpu. While there are no
247 explicit parameters, there is an implicit parameter block that can be
248 obtained by mmap()ing the vcpu fd at offset 0, with the size given by
249 KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct
250 kvm_run' (see below).
257 Parameters: struct kvm_regs (out)
258 Returns: 0 on success, -1 on error
260 Reads the general purpose registers from the vcpu.
264 /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
265 __u64 rax, rbx, rcx, rdx;
266 __u64 rsi, rdi, rsp, rbp;
267 __u64 r8, r9, r10, r11;
268 __u64 r12, r13, r14, r15;
277 Parameters: struct kvm_regs (in)
278 Returns: 0 on success, -1 on error
280 Writes the general purpose registers into the vcpu.
282 See KVM_GET_REGS for the data structure.
287 Architectures: x86, ppc
289 Parameters: struct kvm_sregs (out)
290 Returns: 0 on success, -1 on error
292 Reads special registers from the vcpu.
296 struct kvm_segment cs, ds, es, fs, gs, ss;
297 struct kvm_segment tr, ldt;
298 struct kvm_dtable gdt, idt;
299 __u64 cr0, cr2, cr3, cr4, cr8;
302 __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
305 /* ppc -- see arch/powerpc/include/asm/kvm.h */
307 interrupt_bitmap is a bitmap of pending external interrupts. At most
308 one bit may be set. This interrupt has been acknowledged by the APIC
309 but not yet injected into the cpu core.
314 Architectures: x86, ppc
316 Parameters: struct kvm_sregs (in)
317 Returns: 0 on success, -1 on error
319 Writes special registers into the vcpu. See KVM_GET_SREGS for the
327 Parameters: struct kvm_translation (in/out)
328 Returns: 0 on success, -1 on error
330 Translates a virtual address according to the vcpu's current address
333 struct kvm_translation {
335 __u64 linear_address;
338 __u64 physical_address;
348 Architectures: x86, ppc
350 Parameters: struct kvm_interrupt (in)
351 Returns: 0 on success, -1 on error
353 Queues a hardware interrupt vector to be injected. This is only
354 useful if in-kernel local APIC or equivalent is not used.
356 /* for KVM_INTERRUPT */
357 struct kvm_interrupt {
364 Note 'irq' is an interrupt vector, not an interrupt pin or line.
368 Queues an external interrupt to be injected. This ioctl is overleaded
369 with 3 different irq values:
373 This injects an edge type external interrupt into the guest once it's ready
374 to receive interrupts. When injected, the interrupt is done.
376 b) KVM_INTERRUPT_UNSET
378 This unsets any pending interrupt.
380 Only available with KVM_CAP_PPC_UNSET_IRQ.
382 c) KVM_INTERRUPT_SET_LEVEL
384 This injects a level type external interrupt into the guest context. The
385 interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
388 Only available with KVM_CAP_PPC_IRQ_LEVEL.
390 Note that any value for 'irq' other than the ones stated above is invalid
391 and incurs unexpected behavior.
401 Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.
408 Parameters: struct kvm_msrs (in/out)
409 Returns: 0 on success, -1 on error
411 Reads model-specific registers from the vcpu. Supported msr indices can
412 be obtained using KVM_GET_MSR_INDEX_LIST.
415 __u32 nmsrs; /* number of msrs in entries */
418 struct kvm_msr_entry entries[0];
421 struct kvm_msr_entry {
427 Application code should set the 'nmsrs' member (which indicates the
428 size of the entries array) and the 'index' member of each array entry.
429 kvm will fill in the 'data' member.
436 Parameters: struct kvm_msrs (in)
437 Returns: 0 on success, -1 on error
439 Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
442 Application code should set the 'nmsrs' member (which indicates the
443 size of the entries array), and the 'index' and 'data' members of each
451 Parameters: struct kvm_cpuid (in)
452 Returns: 0 on success, -1 on error
454 Defines the vcpu responses to the cpuid instruction. Applications
455 should use the KVM_SET_CPUID2 ioctl if available.
458 struct kvm_cpuid_entry {
467 /* for KVM_SET_CPUID */
471 struct kvm_cpuid_entry entries[0];
474 4.21 KVM_SET_SIGNAL_MASK
479 Parameters: struct kvm_signal_mask (in)
480 Returns: 0 on success, -1 on error
482 Defines which signals are blocked during execution of KVM_RUN. This
483 signal mask temporarily overrides the threads signal mask. Any
484 unblocked signal received (except SIGKILL and SIGSTOP, which retain
485 their traditional behaviour) will cause KVM_RUN to return with -EINTR.
487 Note the signal will only be delivered if not blocked by the original
490 /* for KVM_SET_SIGNAL_MASK */
491 struct kvm_signal_mask {
501 Parameters: struct kvm_fpu (out)
502 Returns: 0 on success, -1 on error
504 Reads the floating point state from the vcpu.
506 /* for KVM_GET_FPU and KVM_SET_FPU */
511 __u8 ftwx; /* in fxsave format */
526 Parameters: struct kvm_fpu (in)
527 Returns: 0 on success, -1 on error
529 Writes the floating point state to the vcpu.
531 /* for KVM_GET_FPU and KVM_SET_FPU */
536 __u8 ftwx; /* in fxsave format */
546 4.24 KVM_CREATE_IRQCHIP
548 Capability: KVM_CAP_IRQCHIP
549 Architectures: x86, ia64
552 Returns: 0 on success, -1 on error
554 Creates an interrupt controller model in the kernel. On x86, creates a virtual
555 ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a
556 local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23
557 only go to the IOAPIC. On ia64, a IOSAPIC is created.
561 Capability: KVM_CAP_IRQCHIP
562 Architectures: x86, ia64
564 Parameters: struct kvm_irq_level
565 Returns: 0 on success, -1 on error
567 Sets the level of a GSI input to the interrupt controller model in the kernel.
568 Requires that an interrupt controller model has been previously created with
569 KVM_CREATE_IRQCHIP. Note that edge-triggered interrupts require the level
570 to be set to 1 and then back to 0.
572 struct kvm_irq_level {
575 __s32 status; /* not used for KVM_IRQ_LEVEL */
577 __u32 level; /* 0 or 1 */
582 Capability: KVM_CAP_IRQCHIP
583 Architectures: x86, ia64
585 Parameters: struct kvm_irqchip (in/out)
586 Returns: 0 on success, -1 on error
588 Reads the state of a kernel interrupt controller created with
589 KVM_CREATE_IRQCHIP into a buffer provided by the caller.
592 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
595 char dummy[512]; /* reserving space */
596 struct kvm_pic_state pic;
597 struct kvm_ioapic_state ioapic;
603 Capability: KVM_CAP_IRQCHIP
604 Architectures: x86, ia64
606 Parameters: struct kvm_irqchip (in)
607 Returns: 0 on success, -1 on error
609 Sets the state of a kernel interrupt controller created with
610 KVM_CREATE_IRQCHIP from a buffer provided by the caller.
613 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
616 char dummy[512]; /* reserving space */
617 struct kvm_pic_state pic;
618 struct kvm_ioapic_state ioapic;
622 4.28 KVM_XEN_HVM_CONFIG
624 Capability: KVM_CAP_XEN_HVM
627 Parameters: struct kvm_xen_hvm_config (in)
628 Returns: 0 on success, -1 on error
630 Sets the MSR that the Xen HVM guest uses to initialize its hypercall
631 page, and provides the starting address and size of the hypercall
632 blobs in userspace. When the guest writes the MSR, kvm copies one
633 page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
636 struct kvm_xen_hvm_config {
648 Capability: KVM_CAP_ADJUST_CLOCK
651 Parameters: struct kvm_clock_data (out)
652 Returns: 0 on success, -1 on error
654 Gets the current timestamp of kvmclock as seen by the current guest. In
655 conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
658 struct kvm_clock_data {
659 __u64 clock; /* kvmclock current value */
666 Capability: KVM_CAP_ADJUST_CLOCK
669 Parameters: struct kvm_clock_data (in)
670 Returns: 0 on success, -1 on error
672 Sets the current timestamp of kvmclock to the value specified in its parameter.
673 In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
676 struct kvm_clock_data {
677 __u64 clock; /* kvmclock current value */
682 4.31 KVM_GET_VCPU_EVENTS
684 Capability: KVM_CAP_VCPU_EVENTS
685 Extended by: KVM_CAP_INTR_SHADOW
688 Parameters: struct kvm_vcpu_event (out)
689 Returns: 0 on success, -1 on error
691 Gets currently pending exceptions, interrupts, and NMIs as well as related
694 struct kvm_vcpu_events {
718 KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
719 interrupt.shadow contains a valid state. Otherwise, this field is undefined.
721 4.32 KVM_SET_VCPU_EVENTS
723 Capability: KVM_CAP_VCPU_EVENTS
724 Extended by: KVM_CAP_INTR_SHADOW
727 Parameters: struct kvm_vcpu_event (in)
728 Returns: 0 on success, -1 on error
730 Set pending exceptions, interrupts, and NMIs as well as related states of the
733 See KVM_GET_VCPU_EVENTS for the data structure.
735 Fields that may be modified asynchronously by running VCPUs can be excluded
736 from the update. These fields are nmi.pending and sipi_vector. Keep the
737 corresponding bits in the flags field cleared to suppress overwriting the
738 current in-kernel state. The bits are:
740 KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
741 KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
743 If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
744 the flags field to signal that interrupt.shadow contains a valid state and
745 shall be written into the VCPU.
747 4.33 KVM_GET_DEBUGREGS
749 Capability: KVM_CAP_DEBUGREGS
752 Parameters: struct kvm_debugregs (out)
753 Returns: 0 on success, -1 on error
755 Reads debug registers from the vcpu.
757 struct kvm_debugregs {
765 4.34 KVM_SET_DEBUGREGS
767 Capability: KVM_CAP_DEBUGREGS
770 Parameters: struct kvm_debugregs (in)
771 Returns: 0 on success, -1 on error
773 Writes debug registers into the vcpu.
775 See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
776 yet and must be cleared on entry.
778 4.35 KVM_SET_USER_MEMORY_REGION
780 Capability: KVM_CAP_USER_MEM
783 Parameters: struct kvm_userspace_memory_region (in)
784 Returns: 0 on success, -1 on error
786 struct kvm_userspace_memory_region {
789 __u64 guest_phys_addr;
790 __u64 memory_size; /* bytes */
791 __u64 userspace_addr; /* start of the userspace allocated memory */
794 /* for kvm_memory_region::flags */
795 #define KVM_MEM_LOG_DIRTY_PAGES 1UL
797 This ioctl allows the user to create or modify a guest physical memory
798 slot. When changing an existing slot, it may be moved in the guest
799 physical memory space, or its flags may be modified. It may not be
800 resized. Slots may not overlap in guest physical address space.
802 Memory for the region is taken starting at the address denoted by the
803 field userspace_addr, which must point at user addressable memory for
804 the entire memory slot size. Any object may back this memory, including
805 anonymous memory, ordinary files, and hugetlbfs.
807 It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
808 be identical. This allows large pages in the guest to be backed by large
811 The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which
812 instructs kvm to keep track of writes to memory within the slot. See
813 the KVM_GET_DIRTY_LOG ioctl.
815 When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory
816 region are automatically reflected into the guest. For example, an mmap()
817 that affects the region will be made visible immediately. Another example
818 is madvise(MADV_DROP).
820 It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
821 The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
822 allocation and is deprecated.
824 4.36 KVM_SET_TSS_ADDR
826 Capability: KVM_CAP_SET_TSS_ADDR
829 Parameters: unsigned long tss_address (in)
830 Returns: 0 on success, -1 on error
832 This ioctl defines the physical address of a three-page region in the guest
833 physical address space. The region must be within the first 4GB of the
834 guest physical address space and must not conflict with any memory slot
835 or any mmio address. The guest may malfunction if it accesses this memory
838 This ioctl is required on Intel-based hosts. This is needed on Intel hardware
839 because of a quirk in the virtualization implementation (see the internals
840 documentation when it pops into existence).
844 Capability: KVM_CAP_ENABLE_CAP
847 Parameters: struct kvm_enable_cap (in)
848 Returns: 0 on success; -1 on error
850 +Not all extensions are enabled by default. Using this ioctl the application
851 can enable an extension, making it available to the guest.
853 On systems that do not support this ioctl, it always fails. On systems that
854 do support it, it only works for extensions that are supported for enablement.
856 To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
859 struct kvm_enable_cap {
863 The capability that is supposed to get enabled.
867 A bitfield indicating future enhancements. Has to be 0 for now.
871 Arguments for enabling a feature. If a feature needs initial values to
872 function properly, this is the place to put them.
877 4.38 KVM_GET_MP_STATE
879 Capability: KVM_CAP_MP_STATE
880 Architectures: x86, ia64
882 Parameters: struct kvm_mp_state (out)
883 Returns: 0 on success; -1 on error
885 struct kvm_mp_state {
889 Returns the vcpu's current "multiprocessing state" (though also valid on
890 uniprocessor guests).
894 - KVM_MP_STATE_RUNNABLE: the vcpu is currently running
895 - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP)
896 which has not yet received an INIT signal
897 - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is
899 - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and
900 is waiting for an interrupt
901 - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector
902 accessible via KVM_GET_VCPU_EVENTS)
904 This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
905 irqchip, the multiprocessing state must be maintained by userspace.
907 4.39 KVM_SET_MP_STATE
909 Capability: KVM_CAP_MP_STATE
910 Architectures: x86, ia64
912 Parameters: struct kvm_mp_state (in)
913 Returns: 0 on success; -1 on error
915 Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
918 This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
919 irqchip, the multiprocessing state must be maintained by userspace.
921 4.40 KVM_SET_IDENTITY_MAP_ADDR
923 Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
926 Parameters: unsigned long identity (in)
927 Returns: 0 on success, -1 on error
929 This ioctl defines the physical address of a one-page region in the guest
930 physical address space. The region must be within the first 4GB of the
931 guest physical address space and must not conflict with any memory slot
932 or any mmio address. The guest may malfunction if it accesses this memory
935 This ioctl is required on Intel-based hosts. This is needed on Intel hardware
936 because of a quirk in the virtualization implementation (see the internals
937 documentation when it pops into existence).
939 4.41 KVM_SET_BOOT_CPU_ID
941 Capability: KVM_CAP_SET_BOOT_CPU_ID
942 Architectures: x86, ia64
944 Parameters: unsigned long vcpu_id
945 Returns: 0 on success, -1 on error
947 Define which vcpu is the Bootstrap Processor (BSP). Values are the same
948 as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
953 Capability: KVM_CAP_XSAVE
956 Parameters: struct kvm_xsave (out)
957 Returns: 0 on success, -1 on error
963 This ioctl would copy current vcpu's xsave struct to the userspace.
967 Capability: KVM_CAP_XSAVE
970 Parameters: struct kvm_xsave (in)
971 Returns: 0 on success, -1 on error
977 This ioctl would copy userspace's xsave struct to the kernel.
981 Capability: KVM_CAP_XCRS
984 Parameters: struct kvm_xcrs (out)
985 Returns: 0 on success, -1 on error
996 struct kvm_xcr xcrs[KVM_MAX_XCRS];
1000 This ioctl would copy current vcpu's xcrs to the userspace.
1004 Capability: KVM_CAP_XCRS
1007 Parameters: struct kvm_xcrs (in)
1008 Returns: 0 on success, -1 on error
1019 struct kvm_xcr xcrs[KVM_MAX_XCRS];
1023 This ioctl would set vcpu's xcr to the value userspace specified.
1025 4.46 KVM_GET_SUPPORTED_CPUID
1027 Capability: KVM_CAP_EXT_CPUID
1030 Parameters: struct kvm_cpuid2 (in/out)
1031 Returns: 0 on success, -1 on error
1036 struct kvm_cpuid_entry2 entries[0];
1039 #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX 1
1040 #define KVM_CPUID_FLAG_STATEFUL_FUNC 2
1041 #define KVM_CPUID_FLAG_STATE_READ_NEXT 4
1043 struct kvm_cpuid_entry2 {
1054 This ioctl returns x86 cpuid features which are supported by both the hardware
1055 and kvm. Userspace can use the information returned by this ioctl to
1056 construct cpuid information (for KVM_SET_CPUID2) that is consistent with
1057 hardware, kernel, and userspace capabilities, and with user requirements (for
1058 example, the user may wish to constrain cpuid to emulate older hardware,
1059 or for feature consistency across a cluster).
1061 Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1062 with the 'nent' field indicating the number of entries in the variable-size
1063 array 'entries'. If the number of entries is too low to describe the cpu
1064 capabilities, an error (E2BIG) is returned. If the number is too high,
1065 the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
1066 number is just right, the 'nent' field is adjusted to the number of valid
1067 entries in the 'entries' array, which is then filled.
1069 The entries returned are the host cpuid as returned by the cpuid instruction,
1070 with unknown or unsupported features masked out. Some features (for example,
1071 x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1072 emulate them efficiently. The fields in each entry are defined as follows:
1074 function: the eax value used to obtain the entry
1075 index: the ecx value used to obtain the entry (for entries that are
1077 flags: an OR of zero or more of the following:
1078 KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
1079 if the index field is valid
1080 KVM_CPUID_FLAG_STATEFUL_FUNC:
1081 if cpuid for this function returns different values for successive
1082 invocations; there will be several entries with the same function,
1083 all with this flag set
1084 KVM_CPUID_FLAG_STATE_READ_NEXT:
1085 for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
1086 the first entry to be read by a cpu
1087 eax, ebx, ecx, edx: the values returned by the cpuid instruction for
1088 this function/index combination
1090 4.47 KVM_PPC_GET_PVINFO
1092 Capability: KVM_CAP_PPC_GET_PVINFO
1095 Parameters: struct kvm_ppc_pvinfo (out)
1096 Returns: 0 on success, !0 on error
1098 struct kvm_ppc_pvinfo {
1104 This ioctl fetches PV specific information that need to be passed to the guest
1105 using the device tree or other means from vm context.
1107 For now the only implemented piece of information distributed here is an array
1108 of 4 instructions that make up a hypercall.
1110 If any additional field gets added to this structure later on, a bit for that
1111 additional piece of information will be set in the flags bitmap.
1113 4.48 KVM_ASSIGN_PCI_DEVICE
1115 Capability: KVM_CAP_DEVICE_ASSIGNMENT
1116 Architectures: x86 ia64
1118 Parameters: struct kvm_assigned_pci_dev (in)
1119 Returns: 0 on success, -1 on error
1121 Assigns a host PCI device to the VM.
1123 struct kvm_assigned_pci_dev {
1124 __u32 assigned_dev_id;
1134 The PCI device is specified by the triple segnr, busnr, and devfn.
1135 Identification in succeeding service requests is done via assigned_dev_id. The
1136 following flags are specified:
1138 /* Depends on KVM_CAP_IOMMU */
1139 #define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0)
1141 4.49 KVM_DEASSIGN_PCI_DEVICE
1143 Capability: KVM_CAP_DEVICE_DEASSIGNMENT
1144 Architectures: x86 ia64
1146 Parameters: struct kvm_assigned_pci_dev (in)
1147 Returns: 0 on success, -1 on error
1149 Ends PCI device assignment, releasing all associated resources.
1151 See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is
1152 used in kvm_assigned_pci_dev to identify the device.
1154 4.50 KVM_ASSIGN_DEV_IRQ
1156 Capability: KVM_CAP_ASSIGN_DEV_IRQ
1157 Architectures: x86 ia64
1159 Parameters: struct kvm_assigned_irq (in)
1160 Returns: 0 on success, -1 on error
1162 Assigns an IRQ to a passed-through device.
1164 struct kvm_assigned_irq {
1165 __u32 assigned_dev_id;
1166 __u32 host_irq; /* ignored (legacy field) */
1174 The following flags are defined:
1176 #define KVM_DEV_IRQ_HOST_INTX (1 << 0)
1177 #define KVM_DEV_IRQ_HOST_MSI (1 << 1)
1178 #define KVM_DEV_IRQ_HOST_MSIX (1 << 2)
1180 #define KVM_DEV_IRQ_GUEST_INTX (1 << 8)
1181 #define KVM_DEV_IRQ_GUEST_MSI (1 << 9)
1182 #define KVM_DEV_IRQ_GUEST_MSIX (1 << 10)
1184 It is not valid to specify multiple types per host or guest IRQ. However, the
1185 IRQ type of host and guest can differ or can even be null.
1187 4.51 KVM_DEASSIGN_DEV_IRQ
1189 Capability: KVM_CAP_ASSIGN_DEV_IRQ
1190 Architectures: x86 ia64
1192 Parameters: struct kvm_assigned_irq (in)
1193 Returns: 0 on success, -1 on error
1195 Ends an IRQ assignment to a passed-through device.
1197 See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1198 by assigned_dev_id, flags must correspond to the IRQ type specified on
1199 KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed.
1201 4.52 KVM_SET_GSI_ROUTING
1203 Capability: KVM_CAP_IRQ_ROUTING
1204 Architectures: x86 ia64
1206 Parameters: struct kvm_irq_routing (in)
1207 Returns: 0 on success, -1 on error
1209 Sets the GSI routing table entries, overwriting any previously set entries.
1211 struct kvm_irq_routing {
1214 struct kvm_irq_routing_entry entries[0];
1217 No flags are specified so far, the corresponding field must be set to zero.
1219 struct kvm_irq_routing_entry {
1225 struct kvm_irq_routing_irqchip irqchip;
1226 struct kvm_irq_routing_msi msi;
1231 /* gsi routing entry types */
1232 #define KVM_IRQ_ROUTING_IRQCHIP 1
1233 #define KVM_IRQ_ROUTING_MSI 2
1235 No flags are specified so far, the corresponding field must be set to zero.
1237 struct kvm_irq_routing_irqchip {
1242 struct kvm_irq_routing_msi {
1249 4.53 KVM_ASSIGN_SET_MSIX_NR
1251 Capability: KVM_CAP_DEVICE_MSIX
1252 Architectures: x86 ia64
1254 Parameters: struct kvm_assigned_msix_nr (in)
1255 Returns: 0 on success, -1 on error
1257 Set the number of MSI-X interrupts for an assigned device. The number is
1258 reset again by terminating the MSI-X assignment of the device via
1259 KVM_DEASSIGN_DEV_IRQ. Calling this service more than once at any earlier
1262 struct kvm_assigned_msix_nr {
1263 __u32 assigned_dev_id;
1268 #define KVM_MAX_MSIX_PER_DEV 256
1270 4.54 KVM_ASSIGN_SET_MSIX_ENTRY
1272 Capability: KVM_CAP_DEVICE_MSIX
1273 Architectures: x86 ia64
1275 Parameters: struct kvm_assigned_msix_entry (in)
1276 Returns: 0 on success, -1 on error
1278 Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1279 the GSI vector to zero means disabling the interrupt.
1281 struct kvm_assigned_msix_entry {
1282 __u32 assigned_dev_id;
1284 __u16 entry; /* The index of entry in the MSI-X table */
1288 4.54 KVM_SET_TSC_KHZ
1290 Capability: KVM_CAP_TSC_CONTROL
1293 Parameters: virtual tsc_khz
1294 Returns: 0 on success, -1 on error
1296 Specifies the tsc frequency for the virtual machine. The unit of the
1299 4.55 KVM_GET_TSC_KHZ
1301 Capability: KVM_CAP_GET_TSC_KHZ
1305 Returns: virtual tsc-khz on success, negative value on error
1307 Returns the tsc frequency of the guest. The unit of the return value is
1308 KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
1313 Capability: KVM_CAP_IRQCHIP
1316 Parameters: struct kvm_lapic_state (out)
1317 Returns: 0 on success, -1 on error
1319 #define KVM_APIC_REG_SIZE 0x400
1320 struct kvm_lapic_state {
1321 char regs[KVM_APIC_REG_SIZE];
1324 Reads the Local APIC registers and copies them into the input argument. The
1325 data format and layout are the same as documented in the architecture manual.
1329 Capability: KVM_CAP_IRQCHIP
1332 Parameters: struct kvm_lapic_state (in)
1333 Returns: 0 on success, -1 on error
1335 #define KVM_APIC_REG_SIZE 0x400
1336 struct kvm_lapic_state {
1337 char regs[KVM_APIC_REG_SIZE];
1340 Copies the input argument into the the Local APIC registers. The data format
1341 and layout are the same as documented in the architecture manual.
1345 Capability: KVM_CAP_IOEVENTFD
1348 Parameters: struct kvm_ioeventfd (in)
1349 Returns: 0 on success, !0 on error
1351 This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
1352 within the guest. A guest write in the registered address will signal the
1353 provided event instead of triggering an exit.
1355 struct kvm_ioeventfd {
1357 __u64 addr; /* legal pio/mmio address */
1358 __u32 len; /* 1, 2, 4, or 8 bytes */
1364 The following flags are defined:
1366 #define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
1367 #define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
1368 #define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
1370 If datamatch flag is set, the event will be signaled only if the written value
1371 to the registered address is equal to datamatch in struct kvm_ioeventfd.
1373 4.62 KVM_CREATE_SPAPR_TCE
1375 Capability: KVM_CAP_SPAPR_TCE
1376 Architectures: powerpc
1378 Parameters: struct kvm_create_spapr_tce (in)
1379 Returns: file descriptor for manipulating the created TCE table
1381 This creates a virtual TCE (translation control entry) table, which
1382 is an IOMMU for PAPR-style virtual I/O. It is used to translate
1383 logical addresses used in virtual I/O into guest physical addresses,
1384 and provides a scatter/gather capability for PAPR virtual I/O.
1386 /* for KVM_CAP_SPAPR_TCE */
1387 struct kvm_create_spapr_tce {
1392 The liobn field gives the logical IO bus number for which to create a
1393 TCE table. The window_size field specifies the size of the DMA window
1394 which this TCE table will translate - the table will contain one 64
1395 bit TCE entry for every 4kiB of the DMA window.
1397 When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
1398 table has been created using this ioctl(), the kernel will handle it
1399 in real mode, updating the TCE table. H_PUT_TCE calls for other
1400 liobns will cause a vm exit and must be handled by userspace.
1402 The return value is a file descriptor which can be passed to mmap(2)
1403 to map the created TCE table into userspace. This lets userspace read
1404 the entries written by kernel-handled H_PUT_TCE calls, and also lets
1405 userspace update the TCE table directly which is useful in some
1408 4.63 KVM_ALLOCATE_RMA
1410 Capability: KVM_CAP_PPC_RMA
1411 Architectures: powerpc
1413 Parameters: struct kvm_allocate_rma (out)
1414 Returns: file descriptor for mapping the allocated RMA
1416 This allocates a Real Mode Area (RMA) from the pool allocated at boot
1417 time by the kernel. An RMA is a physically-contiguous, aligned region
1418 of memory used on older POWER processors to provide the memory which
1419 will be accessed by real-mode (MMU off) accesses in a KVM guest.
1420 POWER processors support a set of sizes for the RMA that usually
1421 includes 64MB, 128MB, 256MB and some larger powers of two.
1423 /* for KVM_ALLOCATE_RMA */
1424 struct kvm_allocate_rma {
1428 The return value is a file descriptor which can be passed to mmap(2)
1429 to map the allocated RMA into userspace. The mapped area can then be
1430 passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the
1431 RMA for a virtual machine. The size of the RMA in bytes (which is
1432 fixed at host kernel boot time) is returned in the rma_size field of
1433 the argument structure.
1435 The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl
1436 is supported; 2 if the processor requires all virtual machines to have
1437 an RMA, or 1 if the processor can use an RMA but doesn't require it,
1438 because it supports the Virtual RMA (VRMA) facility.
1440 5. The kvm_run structure
1442 Application code obtains a pointer to the kvm_run structure by
1443 mmap()ing a vcpu fd. From that point, application code can control
1444 execution by changing fields in kvm_run prior to calling the KVM_RUN
1445 ioctl, and obtain information about the reason KVM_RUN returned by
1446 looking up structure members.
1450 __u8 request_interrupt_window;
1452 Request that KVM_RUN return when it becomes possible to inject external
1453 interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
1460 When KVM_RUN has returned successfully (return value 0), this informs
1461 application code why KVM_RUN has returned. Allowable values for this
1462 field are detailed below.
1464 __u8 ready_for_interrupt_injection;
1466 If request_interrupt_window has been specified, this field indicates
1467 an interrupt can be injected now with KVM_INTERRUPT.
1471 The value of the current interrupt flag. Only valid if in-kernel
1472 local APIC is not used.
1476 /* in (pre_kvm_run), out (post_kvm_run) */
1479 The value of the cr8 register. Only valid if in-kernel local APIC is
1480 not used. Both input and output.
1484 The value of the APIC BASE msr. Only valid if in-kernel local
1485 APIC is not used. Both input and output.
1488 /* KVM_EXIT_UNKNOWN */
1490 __u64 hardware_exit_reason;
1493 If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
1494 reasons. Further architecture-specific information is available in
1495 hardware_exit_reason.
1497 /* KVM_EXIT_FAIL_ENTRY */
1499 __u64 hardware_entry_failure_reason;
1502 If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
1503 to unknown reasons. Further architecture-specific information is
1504 available in hardware_entry_failure_reason.
1506 /* KVM_EXIT_EXCEPTION */
1516 #define KVM_EXIT_IO_IN 0
1517 #define KVM_EXIT_IO_OUT 1
1519 __u8 size; /* bytes */
1522 __u64 data_offset; /* relative to kvm_run start */
1525 If exit_reason is KVM_EXIT_IO, then the vcpu has
1526 executed a port I/O instruction which could not be satisfied by kvm.
1527 data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
1528 where kvm expects application code to place the data for the next
1529 KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
1532 struct kvm_debug_exit_arch arch;
1545 If exit_reason is KVM_EXIT_MMIO, then the vcpu has
1546 executed a memory-mapped I/O instruction which could not be satisfied
1547 by kvm. The 'data' member contains the written data if 'is_write' is
1548 true, and should be filled by application code otherwise.
1550 NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO and KVM_EXIT_OSI, the corresponding
1551 operations are complete (and guest state is consistent) only after userspace
1552 has re-entered the kernel with KVM_RUN. The kernel side will first finish
1553 incomplete operations and then check for pending signals. Userspace
1554 can re-enter the guest with an unmasked signal pending to complete
1557 /* KVM_EXIT_HYPERCALL */
1566 Unused. This was once used for 'hypercall to userspace'. To implement
1567 such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
1568 Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
1570 /* KVM_EXIT_TPR_ACCESS */
1577 To be documented (KVM_TPR_ACCESS_REPORTING).
1579 /* KVM_EXIT_S390_SIEIC */
1582 __u64 mask; /* psw upper half */
1583 __u64 addr; /* psw lower half */
1590 /* KVM_EXIT_S390_RESET */
1591 #define KVM_S390_RESET_POR 1
1592 #define KVM_S390_RESET_CLEAR 2
1593 #define KVM_S390_RESET_SUBSYSTEM 4
1594 #define KVM_S390_RESET_CPU_INIT 8
1595 #define KVM_S390_RESET_IPL 16
1596 __u64 s390_reset_flags;
1614 MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
1615 hypercalls and exit with this exit struct that contains all the guest gprs.
1617 If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
1618 Userspace can now handle the hypercall and when it's done modify the gprs as
1619 necessary. Upon guest entry all guest GPRs will then be replaced by the values
1622 /* KVM_EXIT_PAPR_HCALL */
1629 This is used on 64-bit PowerPC when emulating a pSeries partition,
1630 e.g. with the 'pseries' machine type in qemu. It occurs when the
1631 guest does a hypercall using the 'sc 1' instruction. The 'nr' field
1632 contains the hypercall number (from the guest R3), and 'args' contains
1633 the arguments (from the guest R4 - R12). Userspace should put the
1634 return code in 'ret' and any extra returned values in args[].
1635 The possible hypercalls are defined in the Power Architecture Platform
1636 Requirements (PAPR) document available from www.power.org (free
1637 developer registration required to access it).
1639 /* Fix the size of the union. */