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). You can use KVM_CAP_NR_VCPUS of the
179
KVM_CHECK_EXTENSION ioctl() to determine the value for max_vcpus at run-time.
180
If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
183
4.8 KVM_GET_DIRTY_LOG (vm ioctl)
188
Parameters: struct kvm_dirty_log (in/out)
189
Returns: 0 on success, -1 on error
191
/* for KVM_GET_DIRTY_LOG */
192
struct kvm_dirty_log {
196
void __user *dirty_bitmap; /* one bit per page */
201
Given a memory slot, return a bitmap containing any pages dirtied
202
since the last call to this ioctl. Bit 0 is the first page in the
203
memory slot. Ensure the entire structure is cleared to avoid padding
206
4.9 KVM_SET_MEMORY_ALIAS
211
Parameters: struct kvm_memory_alias (in)
212
Returns: 0 (success), -1 (error)
214
This ioctl is obsolete and has been removed.
222
Returns: 0 on success, -1 on error
224
EINTR: an unmasked signal is pending
226
This ioctl is used to run a guest virtual cpu. While there are no
227
explicit parameters, there is an implicit parameter block that can be
228
obtained by mmap()ing the vcpu fd at offset 0, with the size given by
229
KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct
230
kvm_run' (see below).
237
Parameters: struct kvm_regs (out)
238
Returns: 0 on success, -1 on error
240
Reads the general purpose registers from the vcpu.
244
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
245
__u64 rax, rbx, rcx, rdx;
246
__u64 rsi, rdi, rsp, rbp;
247
__u64 r8, r9, r10, r11;
248
__u64 r12, r13, r14, r15;
257
Parameters: struct kvm_regs (in)
258
Returns: 0 on success, -1 on error
260
Writes the general purpose registers into the vcpu.
262
See KVM_GET_REGS for the data structure.
267
Architectures: x86, ppc
269
Parameters: struct kvm_sregs (out)
270
Returns: 0 on success, -1 on error
272
Reads special registers from the vcpu.
276
struct kvm_segment cs, ds, es, fs, gs, ss;
277
struct kvm_segment tr, ldt;
278
struct kvm_dtable gdt, idt;
279
__u64 cr0, cr2, cr3, cr4, cr8;
282
__u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
285
/* ppc -- see arch/powerpc/include/asm/kvm.h */
287
interrupt_bitmap is a bitmap of pending external interrupts. At most
288
one bit may be set. This interrupt has been acknowledged by the APIC
289
but not yet injected into the cpu core.
294
Architectures: x86, ppc
296
Parameters: struct kvm_sregs (in)
297
Returns: 0 on success, -1 on error
299
Writes special registers into the vcpu. See KVM_GET_SREGS for the
307
Parameters: struct kvm_translation (in/out)
308
Returns: 0 on success, -1 on error
310
Translates a virtual address according to the vcpu's current address
313
struct kvm_translation {
315
__u64 linear_address;
318
__u64 physical_address;
328
Architectures: x86, ppc
330
Parameters: struct kvm_interrupt (in)
331
Returns: 0 on success, -1 on error
333
Queues a hardware interrupt vector to be injected. This is only
334
useful if in-kernel local APIC or equivalent is not used.
336
/* for KVM_INTERRUPT */
337
struct kvm_interrupt {
344
Note 'irq' is an interrupt vector, not an interrupt pin or line.
348
Queues an external interrupt to be injected. This ioctl is overleaded
349
with 3 different irq values:
353
This injects an edge type external interrupt into the guest once it's ready
354
to receive interrupts. When injected, the interrupt is done.
356
b) KVM_INTERRUPT_UNSET
358
This unsets any pending interrupt.
360
Only available with KVM_CAP_PPC_UNSET_IRQ.
362
c) KVM_INTERRUPT_SET_LEVEL
364
This injects a level type external interrupt into the guest context. The
365
interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
368
Only available with KVM_CAP_PPC_IRQ_LEVEL.
370
Note that any value for 'irq' other than the ones stated above is invalid
371
and incurs unexpected behavior.
381
Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.
388
Parameters: struct kvm_msrs (in/out)
389
Returns: 0 on success, -1 on error
391
Reads model-specific registers from the vcpu. Supported msr indices can
392
be obtained using KVM_GET_MSR_INDEX_LIST.
395
__u32 nmsrs; /* number of msrs in entries */
398
struct kvm_msr_entry entries[0];
401
struct kvm_msr_entry {
407
Application code should set the 'nmsrs' member (which indicates the
408
size of the entries array) and the 'index' member of each array entry.
409
kvm will fill in the 'data' member.
416
Parameters: struct kvm_msrs (in)
417
Returns: 0 on success, -1 on error
419
Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
422
Application code should set the 'nmsrs' member (which indicates the
423
size of the entries array), and the 'index' and 'data' members of each
431
Parameters: struct kvm_cpuid (in)
432
Returns: 0 on success, -1 on error
434
Defines the vcpu responses to the cpuid instruction. Applications
435
should use the KVM_SET_CPUID2 ioctl if available.
438
struct kvm_cpuid_entry {
447
/* for KVM_SET_CPUID */
451
struct kvm_cpuid_entry entries[0];
454
4.21 KVM_SET_SIGNAL_MASK
459
Parameters: struct kvm_signal_mask (in)
460
Returns: 0 on success, -1 on error
462
Defines which signals are blocked during execution of KVM_RUN. This
463
signal mask temporarily overrides the threads signal mask. Any
464
unblocked signal received (except SIGKILL and SIGSTOP, which retain
465
their traditional behaviour) will cause KVM_RUN to return with -EINTR.
467
Note the signal will only be delivered if not blocked by the original
470
/* for KVM_SET_SIGNAL_MASK */
471
struct kvm_signal_mask {
481
Parameters: struct kvm_fpu (out)
482
Returns: 0 on success, -1 on error
484
Reads the floating point state from the vcpu.
486
/* for KVM_GET_FPU and KVM_SET_FPU */
491
__u8 ftwx; /* in fxsave format */
506
Parameters: struct kvm_fpu (in)
507
Returns: 0 on success, -1 on error
509
Writes the floating point state to the vcpu.
511
/* for KVM_GET_FPU and KVM_SET_FPU */
516
__u8 ftwx; /* in fxsave format */
526
4.24 KVM_CREATE_IRQCHIP
528
Capability: KVM_CAP_IRQCHIP
529
Architectures: x86, ia64
532
Returns: 0 on success, -1 on error
534
Creates an interrupt controller model in the kernel. On x86, creates a virtual
535
ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a
536
local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23
537
only go to the IOAPIC. On ia64, a IOSAPIC is created.
541
Capability: KVM_CAP_IRQCHIP
542
Architectures: x86, ia64
544
Parameters: struct kvm_irq_level
545
Returns: 0 on success, -1 on error
547
Sets the level of a GSI input to the interrupt controller model in the kernel.
548
Requires that an interrupt controller model has been previously created with
549
KVM_CREATE_IRQCHIP. Note that edge-triggered interrupts require the level
550
to be set to 1 and then back to 0.
552
struct kvm_irq_level {
555
__s32 status; /* not used for KVM_IRQ_LEVEL */
557
__u32 level; /* 0 or 1 */
562
Capability: KVM_CAP_IRQCHIP
563
Architectures: x86, ia64
565
Parameters: struct kvm_irqchip (in/out)
566
Returns: 0 on success, -1 on error
568
Reads the state of a kernel interrupt controller created with
569
KVM_CREATE_IRQCHIP into a buffer provided by the caller.
572
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
575
char dummy[512]; /* reserving space */
576
struct kvm_pic_state pic;
577
struct kvm_ioapic_state ioapic;
583
Capability: KVM_CAP_IRQCHIP
584
Architectures: x86, ia64
586
Parameters: struct kvm_irqchip (in)
587
Returns: 0 on success, -1 on error
589
Sets the state of a kernel interrupt controller created with
590
KVM_CREATE_IRQCHIP from a buffer provided by the caller.
593
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
596
char dummy[512]; /* reserving space */
597
struct kvm_pic_state pic;
598
struct kvm_ioapic_state ioapic;
602
4.28 KVM_XEN_HVM_CONFIG
604
Capability: KVM_CAP_XEN_HVM
607
Parameters: struct kvm_xen_hvm_config (in)
608
Returns: 0 on success, -1 on error
610
Sets the MSR that the Xen HVM guest uses to initialize its hypercall
611
page, and provides the starting address and size of the hypercall
612
blobs in userspace. When the guest writes the MSR, kvm copies one
613
page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
616
struct kvm_xen_hvm_config {
628
Capability: KVM_CAP_ADJUST_CLOCK
631
Parameters: struct kvm_clock_data (out)
632
Returns: 0 on success, -1 on error
634
Gets the current timestamp of kvmclock as seen by the current guest. In
635
conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
638
struct kvm_clock_data {
639
__u64 clock; /* kvmclock current value */
646
Capability: KVM_CAP_ADJUST_CLOCK
649
Parameters: struct kvm_clock_data (in)
650
Returns: 0 on success, -1 on error
652
Sets the current timestamp of kvmclock to the value specified in its parameter.
653
In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
656
struct kvm_clock_data {
657
__u64 clock; /* kvmclock current value */
662
4.31 KVM_GET_VCPU_EVENTS
664
Capability: KVM_CAP_VCPU_EVENTS
665
Extended by: KVM_CAP_INTR_SHADOW
668
Parameters: struct kvm_vcpu_event (out)
669
Returns: 0 on success, -1 on error
671
Gets currently pending exceptions, interrupts, and NMIs as well as related
674
struct kvm_vcpu_events {
698
KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
699
interrupt.shadow contains a valid state. Otherwise, this field is undefined.
701
4.32 KVM_SET_VCPU_EVENTS
703
Capability: KVM_CAP_VCPU_EVENTS
704
Extended by: KVM_CAP_INTR_SHADOW
707
Parameters: struct kvm_vcpu_event (in)
708
Returns: 0 on success, -1 on error
710
Set pending exceptions, interrupts, and NMIs as well as related states of the
713
See KVM_GET_VCPU_EVENTS for the data structure.
715
Fields that may be modified asynchronously by running VCPUs can be excluded
716
from the update. These fields are nmi.pending and sipi_vector. Keep the
717
corresponding bits in the flags field cleared to suppress overwriting the
718
current in-kernel state. The bits are:
720
KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
721
KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
723
If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
724
the flags field to signal that interrupt.shadow contains a valid state and
725
shall be written into the VCPU.
727
4.33 KVM_GET_DEBUGREGS
729
Capability: KVM_CAP_DEBUGREGS
732
Parameters: struct kvm_debugregs (out)
733
Returns: 0 on success, -1 on error
735
Reads debug registers from the vcpu.
737
struct kvm_debugregs {
745
4.34 KVM_SET_DEBUGREGS
747
Capability: KVM_CAP_DEBUGREGS
750
Parameters: struct kvm_debugregs (in)
751
Returns: 0 on success, -1 on error
753
Writes debug registers into the vcpu.
755
See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
756
yet and must be cleared on entry.
758
4.35 KVM_SET_USER_MEMORY_REGION
760
Capability: KVM_CAP_USER_MEM
763
Parameters: struct kvm_userspace_memory_region (in)
764
Returns: 0 on success, -1 on error
766
struct kvm_userspace_memory_region {
769
__u64 guest_phys_addr;
770
__u64 memory_size; /* bytes */
771
__u64 userspace_addr; /* start of the userspace allocated memory */
774
/* for kvm_memory_region::flags */
775
#define KVM_MEM_LOG_DIRTY_PAGES 1UL
777
This ioctl allows the user to create or modify a guest physical memory
778
slot. When changing an existing slot, it may be moved in the guest
779
physical memory space, or its flags may be modified. It may not be
780
resized. Slots may not overlap in guest physical address space.
782
Memory for the region is taken starting at the address denoted by the
783
field userspace_addr, which must point at user addressable memory for
784
the entire memory slot size. Any object may back this memory, including
785
anonymous memory, ordinary files, and hugetlbfs.
787
It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
788
be identical. This allows large pages in the guest to be backed by large
791
The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which
792
instructs kvm to keep track of writes to memory within the slot. See
793
the KVM_GET_DIRTY_LOG ioctl.
795
When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory
796
region are automatically reflected into the guest. For example, an mmap()
797
that affects the region will be made visible immediately. Another example
798
is madvise(MADV_DROP).
800
It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
801
The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
802
allocation and is deprecated.
804
4.36 KVM_SET_TSS_ADDR
806
Capability: KVM_CAP_SET_TSS_ADDR
809
Parameters: unsigned long tss_address (in)
810
Returns: 0 on success, -1 on error
812
This ioctl defines the physical address of a three-page region in the guest
813
physical address space. The region must be within the first 4GB of the
814
guest physical address space and must not conflict with any memory slot
815
or any mmio address. The guest may malfunction if it accesses this memory
818
This ioctl is required on Intel-based hosts. This is needed on Intel hardware
819
because of a quirk in the virtualization implementation (see the internals
820
documentation when it pops into existence).
824
Capability: KVM_CAP_ENABLE_CAP
827
Parameters: struct kvm_enable_cap (in)
828
Returns: 0 on success; -1 on error
830
+Not all extensions are enabled by default. Using this ioctl the application
831
can enable an extension, making it available to the guest.
833
On systems that do not support this ioctl, it always fails. On systems that
834
do support it, it only works for extensions that are supported for enablement.
836
To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
839
struct kvm_enable_cap {
843
The capability that is supposed to get enabled.
847
A bitfield indicating future enhancements. Has to be 0 for now.
851
Arguments for enabling a feature. If a feature needs initial values to
852
function properly, this is the place to put them.
857
4.38 KVM_GET_MP_STATE
859
Capability: KVM_CAP_MP_STATE
860
Architectures: x86, ia64
862
Parameters: struct kvm_mp_state (out)
863
Returns: 0 on success; -1 on error
865
struct kvm_mp_state {
869
Returns the vcpu's current "multiprocessing state" (though also valid on
870
uniprocessor guests).
874
- KVM_MP_STATE_RUNNABLE: the vcpu is currently running
875
- KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP)
876
which has not yet received an INIT signal
877
- KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is
879
- KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and
880
is waiting for an interrupt
881
- KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector
882
accessible via KVM_GET_VCPU_EVENTS)
884
This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
885
irqchip, the multiprocessing state must be maintained by userspace.
887
4.39 KVM_SET_MP_STATE
889
Capability: KVM_CAP_MP_STATE
890
Architectures: x86, ia64
892
Parameters: struct kvm_mp_state (in)
893
Returns: 0 on success; -1 on error
895
Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
898
This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
899
irqchip, the multiprocessing state must be maintained by userspace.
901
4.40 KVM_SET_IDENTITY_MAP_ADDR
903
Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
906
Parameters: unsigned long identity (in)
907
Returns: 0 on success, -1 on error
909
This ioctl defines the physical address of a one-page region in the guest
910
physical address space. The region must be within the first 4GB of the
911
guest physical address space and must not conflict with any memory slot
912
or any mmio address. The guest may malfunction if it accesses this memory
915
This ioctl is required on Intel-based hosts. This is needed on Intel hardware
916
because of a quirk in the virtualization implementation (see the internals
917
documentation when it pops into existence).
919
4.41 KVM_SET_BOOT_CPU_ID
921
Capability: KVM_CAP_SET_BOOT_CPU_ID
922
Architectures: x86, ia64
924
Parameters: unsigned long vcpu_id
925
Returns: 0 on success, -1 on error
927
Define which vcpu is the Bootstrap Processor (BSP). Values are the same
928
as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
933
Capability: KVM_CAP_XSAVE
936
Parameters: struct kvm_xsave (out)
937
Returns: 0 on success, -1 on error
943
This ioctl would copy current vcpu's xsave struct to the userspace.
947
Capability: KVM_CAP_XSAVE
950
Parameters: struct kvm_xsave (in)
951
Returns: 0 on success, -1 on error
957
This ioctl would copy userspace's xsave struct to the kernel.
961
Capability: KVM_CAP_XCRS
964
Parameters: struct kvm_xcrs (out)
965
Returns: 0 on success, -1 on error
976
struct kvm_xcr xcrs[KVM_MAX_XCRS];
980
This ioctl would copy current vcpu's xcrs to the userspace.
984
Capability: KVM_CAP_XCRS
987
Parameters: struct kvm_xcrs (in)
988
Returns: 0 on success, -1 on error
999
struct kvm_xcr xcrs[KVM_MAX_XCRS];
1003
This ioctl would set vcpu's xcr to the value userspace specified.
1005
4.46 KVM_GET_SUPPORTED_CPUID
1007
Capability: KVM_CAP_EXT_CPUID
1010
Parameters: struct kvm_cpuid2 (in/out)
1011
Returns: 0 on success, -1 on error
1016
struct kvm_cpuid_entry2 entries[0];
1019
#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX 1
1020
#define KVM_CPUID_FLAG_STATEFUL_FUNC 2
1021
#define KVM_CPUID_FLAG_STATE_READ_NEXT 4
1023
struct kvm_cpuid_entry2 {
1034
This ioctl returns x86 cpuid features which are supported by both the hardware
1035
and kvm. Userspace can use the information returned by this ioctl to
1036
construct cpuid information (for KVM_SET_CPUID2) that is consistent with
1037
hardware, kernel, and userspace capabilities, and with user requirements (for
1038
example, the user may wish to constrain cpuid to emulate older hardware,
1039
or for feature consistency across a cluster).
1041
Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1042
with the 'nent' field indicating the number of entries in the variable-size
1043
array 'entries'. If the number of entries is too low to describe the cpu
1044
capabilities, an error (E2BIG) is returned. If the number is too high,
1045
the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
1046
number is just right, the 'nent' field is adjusted to the number of valid
1047
entries in the 'entries' array, which is then filled.
1049
The entries returned are the host cpuid as returned by the cpuid instruction,
1050
with unknown or unsupported features masked out. Some features (for example,
1051
x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1052
emulate them efficiently. The fields in each entry are defined as follows:
1054
function: the eax value used to obtain the entry
1055
index: the ecx value used to obtain the entry (for entries that are
1057
flags: an OR of zero or more of the following:
1058
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
1059
if the index field is valid
1060
KVM_CPUID_FLAG_STATEFUL_FUNC:
1061
if cpuid for this function returns different values for successive
1062
invocations; there will be several entries with the same function,
1063
all with this flag set
1064
KVM_CPUID_FLAG_STATE_READ_NEXT:
1065
for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
1066
the first entry to be read by a cpu
1067
eax, ebx, ecx, edx: the values returned by the cpuid instruction for
1068
this function/index combination
1070
4.47 KVM_PPC_GET_PVINFO
1072
Capability: KVM_CAP_PPC_GET_PVINFO
1075
Parameters: struct kvm_ppc_pvinfo (out)
1076
Returns: 0 on success, !0 on error
1078
struct kvm_ppc_pvinfo {
1084
This ioctl fetches PV specific information that need to be passed to the guest
1085
using the device tree or other means from vm context.
1087
For now the only implemented piece of information distributed here is an array
1088
of 4 instructions that make up a hypercall.
1090
If any additional field gets added to this structure later on, a bit for that
1091
additional piece of information will be set in the flags bitmap.
1093
4.48 KVM_ASSIGN_PCI_DEVICE
1095
Capability: KVM_CAP_DEVICE_ASSIGNMENT
1096
Architectures: x86 ia64
1098
Parameters: struct kvm_assigned_pci_dev (in)
1099
Returns: 0 on success, -1 on error
1101
Assigns a host PCI device to the VM.
1103
struct kvm_assigned_pci_dev {
1104
__u32 assigned_dev_id;
1114
The PCI device is specified by the triple segnr, busnr, and devfn.
1115
Identification in succeeding service requests is done via assigned_dev_id. The
1116
following flags are specified:
1118
/* Depends on KVM_CAP_IOMMU */
1119
#define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0)
1121
4.49 KVM_DEASSIGN_PCI_DEVICE
1123
Capability: KVM_CAP_DEVICE_DEASSIGNMENT
1124
Architectures: x86 ia64
1126
Parameters: struct kvm_assigned_pci_dev (in)
1127
Returns: 0 on success, -1 on error
1129
Ends PCI device assignment, releasing all associated resources.
1131
See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is
1132
used in kvm_assigned_pci_dev to identify the device.
1134
4.50 KVM_ASSIGN_DEV_IRQ
1136
Capability: KVM_CAP_ASSIGN_DEV_IRQ
1137
Architectures: x86 ia64
1139
Parameters: struct kvm_assigned_irq (in)
1140
Returns: 0 on success, -1 on error
1142
Assigns an IRQ to a passed-through device.
1144
struct kvm_assigned_irq {
1145
__u32 assigned_dev_id;
1159
The following flags are defined:
1161
#define KVM_DEV_IRQ_HOST_INTX (1 << 0)
1162
#define KVM_DEV_IRQ_HOST_MSI (1 << 1)
1163
#define KVM_DEV_IRQ_HOST_MSIX (1 << 2)
1165
#define KVM_DEV_IRQ_GUEST_INTX (1 << 8)
1166
#define KVM_DEV_IRQ_GUEST_MSI (1 << 9)
1167
#define KVM_DEV_IRQ_GUEST_MSIX (1 << 10)
1169
It is not valid to specify multiple types per host or guest IRQ. However, the
1170
IRQ type of host and guest can differ or can even be null.
1172
4.51 KVM_DEASSIGN_DEV_IRQ
1174
Capability: KVM_CAP_ASSIGN_DEV_IRQ
1175
Architectures: x86 ia64
1177
Parameters: struct kvm_assigned_irq (in)
1178
Returns: 0 on success, -1 on error
1180
Ends an IRQ assignment to a passed-through device.
1182
See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1183
by assigned_dev_id, flags must correspond to the IRQ type specified on
1184
KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed.
1186
4.52 KVM_SET_GSI_ROUTING
1188
Capability: KVM_CAP_IRQ_ROUTING
1189
Architectures: x86 ia64
1191
Parameters: struct kvm_irq_routing (in)
1192
Returns: 0 on success, -1 on error
1194
Sets the GSI routing table entries, overwriting any previously set entries.
1196
struct kvm_irq_routing {
1199
struct kvm_irq_routing_entry entries[0];
1202
No flags are specified so far, the corresponding field must be set to zero.
1204
struct kvm_irq_routing_entry {
1210
struct kvm_irq_routing_irqchip irqchip;
1211
struct kvm_irq_routing_msi msi;
1216
/* gsi routing entry types */
1217
#define KVM_IRQ_ROUTING_IRQCHIP 1
1218
#define KVM_IRQ_ROUTING_MSI 2
1220
No flags are specified so far, the corresponding field must be set to zero.
1222
struct kvm_irq_routing_irqchip {
1227
struct kvm_irq_routing_msi {
1234
4.53 KVM_ASSIGN_SET_MSIX_NR
1236
Capability: KVM_CAP_DEVICE_MSIX
1237
Architectures: x86 ia64
1239
Parameters: struct kvm_assigned_msix_nr (in)
1240
Returns: 0 on success, -1 on error
1242
Set the number of MSI-X interrupts for an assigned device. This service can
1243
only be called once in the lifetime of an assigned device.
1245
struct kvm_assigned_msix_nr {
1246
__u32 assigned_dev_id;
1251
#define KVM_MAX_MSIX_PER_DEV 256
1253
4.54 KVM_ASSIGN_SET_MSIX_ENTRY
1255
Capability: KVM_CAP_DEVICE_MSIX
1256
Architectures: x86 ia64
1258
Parameters: struct kvm_assigned_msix_entry (in)
1259
Returns: 0 on success, -1 on error
1261
Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1262
the GSI vector to zero means disabling the interrupt.
1264
struct kvm_assigned_msix_entry {
1265
__u32 assigned_dev_id;
1267
__u16 entry; /* The index of entry in the MSI-X table */
1271
4.54 KVM_SET_TSC_KHZ
1273
Capability: KVM_CAP_TSC_CONTROL
1276
Parameters: virtual tsc_khz
1277
Returns: 0 on success, -1 on error
1279
Specifies the tsc frequency for the virtual machine. The unit of the
1282
4.55 KVM_GET_TSC_KHZ
1284
Capability: KVM_CAP_GET_TSC_KHZ
1288
Returns: virtual tsc-khz on success, negative value on error
1290
Returns the tsc frequency of the guest. The unit of the return value is
1291
KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
1294
5. The kvm_run structure
1296
Application code obtains a pointer to the kvm_run structure by
1297
mmap()ing a vcpu fd. From that point, application code can control
1298
execution by changing fields in kvm_run prior to calling the KVM_RUN
1299
ioctl, and obtain information about the reason KVM_RUN returned by
1300
looking up structure members.
1304
__u8 request_interrupt_window;
1306
Request that KVM_RUN return when it becomes possible to inject external
1307
interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
1314
When KVM_RUN has returned successfully (return value 0), this informs
1315
application code why KVM_RUN has returned. Allowable values for this
1316
field are detailed below.
1318
__u8 ready_for_interrupt_injection;
1320
If request_interrupt_window has been specified, this field indicates
1321
an interrupt can be injected now with KVM_INTERRUPT.
1325
The value of the current interrupt flag. Only valid if in-kernel
1326
local APIC is not used.
1330
/* in (pre_kvm_run), out (post_kvm_run) */
1333
The value of the cr8 register. Only valid if in-kernel local APIC is
1334
not used. Both input and output.
1338
The value of the APIC BASE msr. Only valid if in-kernel local
1339
APIC is not used. Both input and output.
1342
/* KVM_EXIT_UNKNOWN */
1344
__u64 hardware_exit_reason;
1347
If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
1348
reasons. Further architecture-specific information is available in
1349
hardware_exit_reason.
1351
/* KVM_EXIT_FAIL_ENTRY */
1353
__u64 hardware_entry_failure_reason;
1356
If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
1357
to unknown reasons. Further architecture-specific information is
1358
available in hardware_entry_failure_reason.
1360
/* KVM_EXIT_EXCEPTION */
1370
#define KVM_EXIT_IO_IN 0
1371
#define KVM_EXIT_IO_OUT 1
1373
__u8 size; /* bytes */
1376
__u64 data_offset; /* relative to kvm_run start */
1379
If exit_reason is KVM_EXIT_IO, then the vcpu has
1380
executed a port I/O instruction which could not be satisfied by kvm.
1381
data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
1382
where kvm expects application code to place the data for the next
1383
KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
1386
struct kvm_debug_exit_arch arch;
1399
If exit_reason is KVM_EXIT_MMIO, then the vcpu has
1400
executed a memory-mapped I/O instruction which could not be satisfied
1401
by kvm. The 'data' member contains the written data if 'is_write' is
1402
true, and should be filled by application code otherwise.
1404
NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO and KVM_EXIT_OSI, the corresponding
1405
operations are complete (and guest state is consistent) only after userspace
1406
has re-entered the kernel with KVM_RUN. The kernel side will first finish
1407
incomplete operations and then check for pending signals. Userspace
1408
can re-enter the guest with an unmasked signal pending to complete
1411
/* KVM_EXIT_HYPERCALL */
1420
Unused. This was once used for 'hypercall to userspace'. To implement
1421
such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
1422
Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
1424
/* KVM_EXIT_TPR_ACCESS */
1431
To be documented (KVM_TPR_ACCESS_REPORTING).
1433
/* KVM_EXIT_S390_SIEIC */
1436
__u64 mask; /* psw upper half */
1437
__u64 addr; /* psw lower half */
1444
/* KVM_EXIT_S390_RESET */
1445
#define KVM_S390_RESET_POR 1
1446
#define KVM_S390_RESET_CLEAR 2
1447
#define KVM_S390_RESET_SUBSYSTEM 4
1448
#define KVM_S390_RESET_CPU_INIT 8
1449
#define KVM_S390_RESET_IPL 16
1450
__u64 s390_reset_flags;
1468
MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
1469
hypercalls and exit with this exit struct that contains all the guest gprs.
1471
If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
1472
Userspace can now handle the hypercall and when it's done modify the gprs as
1473
necessary. Upon guest entry all guest GPRs will then be replaced by the values
1476
/* Fix the size of the union. */
added
removed
Documentation/virtual/kvm/api.txt
