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
4.7 KVM_GET_DIRTY_LOG (vm ioctl)
185
Parameters: struct kvm_dirty_log (in/out)
186
Returns: 0 on success, -1 on error
188
/* for KVM_GET_DIRTY_LOG */
189
struct kvm_dirty_log {
193
void __user *dirty_bitmap; /* one bit per page */
198
Given a memory slot, return a bitmap containing any pages dirtied
199
since the last call to this ioctl. Bit 0 is the first page in the
200
memory slot. Ensure the entire structure is cleared to avoid padding
203
4.8 KVM_SET_MEMORY_ALIAS
208
Parameters: struct kvm_memory_alias (in)
209
Returns: 0 (success), -1 (error)
211
This ioctl is obsolete and has been removed.
219
Returns: 0 on success, -1 on error
221
EINTR: an unmasked signal is pending
223
This ioctl is used to run a guest virtual cpu. While there are no
224
explicit parameters, there is an implicit parameter block that can be
225
obtained by mmap()ing the vcpu fd at offset 0, with the size given by
226
KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct
227
kvm_run' (see below).
234
Parameters: struct kvm_regs (out)
235
Returns: 0 on success, -1 on error
237
Reads the general purpose registers from the vcpu.
241
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
242
__u64 rax, rbx, rcx, rdx;
243
__u64 rsi, rdi, rsp, rbp;
244
__u64 r8, r9, r10, r11;
245
__u64 r12, r13, r14, r15;
254
Parameters: struct kvm_regs (in)
255
Returns: 0 on success, -1 on error
257
Writes the general purpose registers into the vcpu.
259
See KVM_GET_REGS for the data structure.
266
Parameters: struct kvm_sregs (out)
267
Returns: 0 on success, -1 on error
269
Reads special registers from the vcpu.
273
struct kvm_segment cs, ds, es, fs, gs, ss;
274
struct kvm_segment tr, ldt;
275
struct kvm_dtable gdt, idt;
276
__u64 cr0, cr2, cr3, cr4, cr8;
279
__u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
282
interrupt_bitmap is a bitmap of pending external interrupts. At most
283
one bit may be set. This interrupt has been acknowledged by the APIC
284
but not yet injected into the cpu core.
291
Parameters: struct kvm_sregs (in)
292
Returns: 0 on success, -1 on error
294
Writes special registers into the vcpu. See KVM_GET_SREGS for the
302
Parameters: struct kvm_translation (in/out)
303
Returns: 0 on success, -1 on error
305
Translates a virtual address according to the vcpu's current address
308
struct kvm_translation {
310
__u64 linear_address;
313
__u64 physical_address;
323
Architectures: x86, ppc
325
Parameters: struct kvm_interrupt (in)
326
Returns: 0 on success, -1 on error
328
Queues a hardware interrupt vector to be injected. This is only
329
useful if in-kernel local APIC or equivalent is not used.
331
/* for KVM_INTERRUPT */
332
struct kvm_interrupt {
339
Note 'irq' is an interrupt vector, not an interrupt pin or line.
343
Queues an external interrupt to be injected. This ioctl is overleaded
344
with 3 different irq values:
348
This injects an edge type external interrupt into the guest once it's ready
349
to receive interrupts. When injected, the interrupt is done.
351
b) KVM_INTERRUPT_UNSET
353
This unsets any pending interrupt.
355
Only available with KVM_CAP_PPC_UNSET_IRQ.
357
c) KVM_INTERRUPT_SET_LEVEL
359
This injects a level type external interrupt into the guest context. The
360
interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
363
Only available with KVM_CAP_PPC_IRQ_LEVEL.
365
Note that any value for 'irq' other than the ones stated above is invalid
366
and incurs unexpected behavior.
376
Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.
383
Parameters: struct kvm_msrs (in/out)
384
Returns: 0 on success, -1 on error
386
Reads model-specific registers from the vcpu. Supported msr indices can
387
be obtained using KVM_GET_MSR_INDEX_LIST.
390
__u32 nmsrs; /* number of msrs in entries */
393
struct kvm_msr_entry entries[0];
396
struct kvm_msr_entry {
402
Application code should set the 'nmsrs' member (which indicates the
403
size of the entries array) and the 'index' member of each array entry.
404
kvm will fill in the 'data' member.
411
Parameters: struct kvm_msrs (in)
412
Returns: 0 on success, -1 on error
414
Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
417
Application code should set the 'nmsrs' member (which indicates the
418
size of the entries array), and the 'index' and 'data' members of each
426
Parameters: struct kvm_cpuid (in)
427
Returns: 0 on success, -1 on error
429
Defines the vcpu responses to the cpuid instruction. Applications
430
should use the KVM_SET_CPUID2 ioctl if available.
433
struct kvm_cpuid_entry {
442
/* for KVM_SET_CPUID */
446
struct kvm_cpuid_entry entries[0];
449
4.20 KVM_SET_SIGNAL_MASK
454
Parameters: struct kvm_signal_mask (in)
455
Returns: 0 on success, -1 on error
457
Defines which signals are blocked during execution of KVM_RUN. This
458
signal mask temporarily overrides the threads signal mask. Any
459
unblocked signal received (except SIGKILL and SIGSTOP, which retain
460
their traditional behaviour) will cause KVM_RUN to return with -EINTR.
462
Note the signal will only be delivered if not blocked by the original
465
/* for KVM_SET_SIGNAL_MASK */
466
struct kvm_signal_mask {
476
Parameters: struct kvm_fpu (out)
477
Returns: 0 on success, -1 on error
479
Reads the floating point state from the vcpu.
481
/* for KVM_GET_FPU and KVM_SET_FPU */
486
__u8 ftwx; /* in fxsave format */
501
Parameters: struct kvm_fpu (in)
502
Returns: 0 on success, -1 on error
504
Writes the floating point state to the vcpu.
506
/* for KVM_GET_FPU and KVM_SET_FPU */
511
__u8 ftwx; /* in fxsave format */
521
4.23 KVM_CREATE_IRQCHIP
523
Capability: KVM_CAP_IRQCHIP
524
Architectures: x86, ia64
527
Returns: 0 on success, -1 on error
529
Creates an interrupt controller model in the kernel. On x86, creates a virtual
530
ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a
531
local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23
532
only go to the IOAPIC. On ia64, a IOSAPIC is created.
536
Capability: KVM_CAP_IRQCHIP
537
Architectures: x86, ia64
539
Parameters: struct kvm_irq_level
540
Returns: 0 on success, -1 on error
542
Sets the level of a GSI input to the interrupt controller model in the kernel.
543
Requires that an interrupt controller model has been previously created with
544
KVM_CREATE_IRQCHIP. Note that edge-triggered interrupts require the level
545
to be set to 1 and then back to 0.
547
struct kvm_irq_level {
550
__s32 status; /* not used for KVM_IRQ_LEVEL */
552
__u32 level; /* 0 or 1 */
557
Capability: KVM_CAP_IRQCHIP
558
Architectures: x86, ia64
560
Parameters: struct kvm_irqchip (in/out)
561
Returns: 0 on success, -1 on error
563
Reads the state of a kernel interrupt controller created with
564
KVM_CREATE_IRQCHIP into a buffer provided by the caller.
567
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
570
char dummy[512]; /* reserving space */
571
struct kvm_pic_state pic;
572
struct kvm_ioapic_state ioapic;
578
Capability: KVM_CAP_IRQCHIP
579
Architectures: x86, ia64
581
Parameters: struct kvm_irqchip (in)
582
Returns: 0 on success, -1 on error
584
Sets the state of a kernel interrupt controller created with
585
KVM_CREATE_IRQCHIP from a buffer provided by the caller.
588
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
591
char dummy[512]; /* reserving space */
592
struct kvm_pic_state pic;
593
struct kvm_ioapic_state ioapic;
597
4.27 KVM_XEN_HVM_CONFIG
599
Capability: KVM_CAP_XEN_HVM
602
Parameters: struct kvm_xen_hvm_config (in)
603
Returns: 0 on success, -1 on error
605
Sets the MSR that the Xen HVM guest uses to initialize its hypercall
606
page, and provides the starting address and size of the hypercall
607
blobs in userspace. When the guest writes the MSR, kvm copies one
608
page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
611
struct kvm_xen_hvm_config {
623
Capability: KVM_CAP_ADJUST_CLOCK
626
Parameters: struct kvm_clock_data (out)
627
Returns: 0 on success, -1 on error
629
Gets the current timestamp of kvmclock as seen by the current guest. In
630
conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
633
struct kvm_clock_data {
634
__u64 clock; /* kvmclock current value */
641
Capability: KVM_CAP_ADJUST_CLOCK
644
Parameters: struct kvm_clock_data (in)
645
Returns: 0 on success, -1 on error
647
Sets the current timestamp of kvmclock to the value specified in its parameter.
648
In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
651
struct kvm_clock_data {
652
__u64 clock; /* kvmclock current value */
657
4.29 KVM_GET_VCPU_EVENTS
659
Capability: KVM_CAP_VCPU_EVENTS
660
Extended by: KVM_CAP_INTR_SHADOW
663
Parameters: struct kvm_vcpu_event (out)
664
Returns: 0 on success, -1 on error
666
Gets currently pending exceptions, interrupts, and NMIs as well as related
669
struct kvm_vcpu_events {
693
KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
694
interrupt.shadow contains a valid state. Otherwise, this field is undefined.
696
4.30 KVM_SET_VCPU_EVENTS
698
Capability: KVM_CAP_VCPU_EVENTS
699
Extended by: KVM_CAP_INTR_SHADOW
702
Parameters: struct kvm_vcpu_event (in)
703
Returns: 0 on success, -1 on error
705
Set pending exceptions, interrupts, and NMIs as well as related states of the
708
See KVM_GET_VCPU_EVENTS for the data structure.
710
Fields that may be modified asynchronously by running VCPUs can be excluded
711
from the update. These fields are nmi.pending and sipi_vector. Keep the
712
corresponding bits in the flags field cleared to suppress overwriting the
713
current in-kernel state. The bits are:
715
KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
716
KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
718
If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
719
the flags field to signal that interrupt.shadow contains a valid state and
720
shall be written into the VCPU.
722
4.32 KVM_GET_DEBUGREGS
724
Capability: KVM_CAP_DEBUGREGS
727
Parameters: struct kvm_debugregs (out)
728
Returns: 0 on success, -1 on error
730
Reads debug registers from the vcpu.
732
struct kvm_debugregs {
740
4.33 KVM_SET_DEBUGREGS
742
Capability: KVM_CAP_DEBUGREGS
745
Parameters: struct kvm_debugregs (in)
746
Returns: 0 on success, -1 on error
748
Writes debug registers into the vcpu.
750
See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
751
yet and must be cleared on entry.
753
4.34 KVM_SET_USER_MEMORY_REGION
755
Capability: KVM_CAP_USER_MEM
758
Parameters: struct kvm_userspace_memory_region (in)
759
Returns: 0 on success, -1 on error
761
struct kvm_userspace_memory_region {
764
__u64 guest_phys_addr;
765
__u64 memory_size; /* bytes */
766
__u64 userspace_addr; /* start of the userspace allocated memory */
769
/* for kvm_memory_region::flags */
770
#define KVM_MEM_LOG_DIRTY_PAGES 1UL
772
This ioctl allows the user to create or modify a guest physical memory
773
slot. When changing an existing slot, it may be moved in the guest
774
physical memory space, or its flags may be modified. It may not be
775
resized. Slots may not overlap in guest physical address space.
777
Memory for the region is taken starting at the address denoted by the
778
field userspace_addr, which must point at user addressable memory for
779
the entire memory slot size. Any object may back this memory, including
780
anonymous memory, ordinary files, and hugetlbfs.
782
It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
783
be identical. This allows large pages in the guest to be backed by large
786
The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which
787
instructs kvm to keep track of writes to memory within the slot. See
788
the KVM_GET_DIRTY_LOG ioctl.
790
When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory
791
region are automatically reflected into the guest. For example, an mmap()
792
that affects the region will be made visible immediately. Another example
793
is madvise(MADV_DROP).
795
It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
796
The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
797
allocation and is deprecated.
799
4.35 KVM_SET_TSS_ADDR
801
Capability: KVM_CAP_SET_TSS_ADDR
804
Parameters: unsigned long tss_address (in)
805
Returns: 0 on success, -1 on error
807
This ioctl defines the physical address of a three-page region in the guest
808
physical address space. The region must be within the first 4GB of the
809
guest physical address space and must not conflict with any memory slot
810
or any mmio address. The guest may malfunction if it accesses this memory
813
This ioctl is required on Intel-based hosts. This is needed on Intel hardware
814
because of a quirk in the virtualization implementation (see the internals
815
documentation when it pops into existence).
819
Capability: KVM_CAP_ENABLE_CAP
822
Parameters: struct kvm_enable_cap (in)
823
Returns: 0 on success; -1 on error
825
+Not all extensions are enabled by default. Using this ioctl the application
826
can enable an extension, making it available to the guest.
828
On systems that do not support this ioctl, it always fails. On systems that
829
do support it, it only works for extensions that are supported for enablement.
831
To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
834
struct kvm_enable_cap {
838
The capability that is supposed to get enabled.
842
A bitfield indicating future enhancements. Has to be 0 for now.
846
Arguments for enabling a feature. If a feature needs initial values to
847
function properly, this is the place to put them.
852
4.37 KVM_GET_MP_STATE
854
Capability: KVM_CAP_MP_STATE
855
Architectures: x86, ia64
857
Parameters: struct kvm_mp_state (out)
858
Returns: 0 on success; -1 on error
860
struct kvm_mp_state {
864
Returns the vcpu's current "multiprocessing state" (though also valid on
865
uniprocessor guests).
869
- KVM_MP_STATE_RUNNABLE: the vcpu is currently running
870
- KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP)
871
which has not yet received an INIT signal
872
- KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is
874
- KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and
875
is waiting for an interrupt
876
- KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector
877
accessible via KVM_GET_VCPU_EVENTS)
879
This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
880
irqchip, the multiprocessing state must be maintained by userspace.
882
4.38 KVM_SET_MP_STATE
884
Capability: KVM_CAP_MP_STATE
885
Architectures: x86, ia64
887
Parameters: struct kvm_mp_state (in)
888
Returns: 0 on success; -1 on error
890
Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
893
This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
894
irqchip, the multiprocessing state must be maintained by userspace.
896
4.39 KVM_SET_IDENTITY_MAP_ADDR
898
Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
901
Parameters: unsigned long identity (in)
902
Returns: 0 on success, -1 on error
904
This ioctl defines the physical address of a one-page region in the guest
905
physical address space. The region must be within the first 4GB of the
906
guest physical address space and must not conflict with any memory slot
907
or any mmio address. The guest may malfunction if it accesses this memory
910
This ioctl is required on Intel-based hosts. This is needed on Intel hardware
911
because of a quirk in the virtualization implementation (see the internals
912
documentation when it pops into existence).
914
4.40 KVM_SET_BOOT_CPU_ID
916
Capability: KVM_CAP_SET_BOOT_CPU_ID
917
Architectures: x86, ia64
919
Parameters: unsigned long vcpu_id
920
Returns: 0 on success, -1 on error
922
Define which vcpu is the Bootstrap Processor (BSP). Values are the same
923
as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
928
Capability: KVM_CAP_XSAVE
931
Parameters: struct kvm_xsave (out)
932
Returns: 0 on success, -1 on error
938
This ioctl would copy current vcpu's xsave struct to the userspace.
942
Capability: KVM_CAP_XSAVE
945
Parameters: struct kvm_xsave (in)
946
Returns: 0 on success, -1 on error
952
This ioctl would copy userspace's xsave struct to the kernel.
956
Capability: KVM_CAP_XCRS
959
Parameters: struct kvm_xcrs (out)
960
Returns: 0 on success, -1 on error
971
struct kvm_xcr xcrs[KVM_MAX_XCRS];
975
This ioctl would copy current vcpu's xcrs to the userspace.
979
Capability: KVM_CAP_XCRS
982
Parameters: struct kvm_xcrs (in)
983
Returns: 0 on success, -1 on error
994
struct kvm_xcr xcrs[KVM_MAX_XCRS];
998
This ioctl would set vcpu's xcr to the value userspace specified.
1000
4.45 KVM_GET_SUPPORTED_CPUID
1002
Capability: KVM_CAP_EXT_CPUID
1005
Parameters: struct kvm_cpuid2 (in/out)
1006
Returns: 0 on success, -1 on error
1011
struct kvm_cpuid_entry2 entries[0];
1014
#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX 1
1015
#define KVM_CPUID_FLAG_STATEFUL_FUNC 2
1016
#define KVM_CPUID_FLAG_STATE_READ_NEXT 4
1018
struct kvm_cpuid_entry2 {
1029
This ioctl returns x86 cpuid features which are supported by both the hardware
1030
and kvm. Userspace can use the information returned by this ioctl to
1031
construct cpuid information (for KVM_SET_CPUID2) that is consistent with
1032
hardware, kernel, and userspace capabilities, and with user requirements (for
1033
example, the user may wish to constrain cpuid to emulate older hardware,
1034
or for feature consistency across a cluster).
1036
Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1037
with the 'nent' field indicating the number of entries in the variable-size
1038
array 'entries'. If the number of entries is too low to describe the cpu
1039
capabilities, an error (E2BIG) is returned. If the number is too high,
1040
the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
1041
number is just right, the 'nent' field is adjusted to the number of valid
1042
entries in the 'entries' array, which is then filled.
1044
The entries returned are the host cpuid as returned by the cpuid instruction,
1045
with unknown or unsupported features masked out. Some features (for example,
1046
x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1047
emulate them efficiently. The fields in each entry are defined as follows:
1049
function: the eax value used to obtain the entry
1050
index: the ecx value used to obtain the entry (for entries that are
1052
flags: an OR of zero or more of the following:
1053
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
1054
if the index field is valid
1055
KVM_CPUID_FLAG_STATEFUL_FUNC:
1056
if cpuid for this function returns different values for successive
1057
invocations; there will be several entries with the same function,
1058
all with this flag set
1059
KVM_CPUID_FLAG_STATE_READ_NEXT:
1060
for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
1061
the first entry to be read by a cpu
1062
eax, ebx, ecx, edx: the values returned by the cpuid instruction for
1063
this function/index combination
1065
4.46 KVM_PPC_GET_PVINFO
1067
Capability: KVM_CAP_PPC_GET_PVINFO
1070
Parameters: struct kvm_ppc_pvinfo (out)
1071
Returns: 0 on success, !0 on error
1073
struct kvm_ppc_pvinfo {
1079
This ioctl fetches PV specific information that need to be passed to the guest
1080
using the device tree or other means from vm context.
1082
For now the only implemented piece of information distributed here is an array
1083
of 4 instructions that make up a hypercall.
1085
If any additional field gets added to this structure later on, a bit for that
1086
additional piece of information will be set in the flags bitmap.
1088
4.47 KVM_ASSIGN_PCI_DEVICE
1090
Capability: KVM_CAP_DEVICE_ASSIGNMENT
1091
Architectures: x86 ia64
1093
Parameters: struct kvm_assigned_pci_dev (in)
1094
Returns: 0 on success, -1 on error
1096
Assigns a host PCI device to the VM.
1098
struct kvm_assigned_pci_dev {
1099
__u32 assigned_dev_id;
1109
The PCI device is specified by the triple segnr, busnr, and devfn.
1110
Identification in succeeding service requests is done via assigned_dev_id. The
1111
following flags are specified:
1113
/* Depends on KVM_CAP_IOMMU */
1114
#define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0)
1116
4.48 KVM_DEASSIGN_PCI_DEVICE
1118
Capability: KVM_CAP_DEVICE_DEASSIGNMENT
1119
Architectures: x86 ia64
1121
Parameters: struct kvm_assigned_pci_dev (in)
1122
Returns: 0 on success, -1 on error
1124
Ends PCI device assignment, releasing all associated resources.
1126
See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is
1127
used in kvm_assigned_pci_dev to identify the device.
1129
4.49 KVM_ASSIGN_DEV_IRQ
1131
Capability: KVM_CAP_ASSIGN_DEV_IRQ
1132
Architectures: x86 ia64
1134
Parameters: struct kvm_assigned_irq (in)
1135
Returns: 0 on success, -1 on error
1137
Assigns an IRQ to a passed-through device.
1139
struct kvm_assigned_irq {
1140
__u32 assigned_dev_id;
1154
The following flags are defined:
1156
#define KVM_DEV_IRQ_HOST_INTX (1 << 0)
1157
#define KVM_DEV_IRQ_HOST_MSI (1 << 1)
1158
#define KVM_DEV_IRQ_HOST_MSIX (1 << 2)
1160
#define KVM_DEV_IRQ_GUEST_INTX (1 << 8)
1161
#define KVM_DEV_IRQ_GUEST_MSI (1 << 9)
1162
#define KVM_DEV_IRQ_GUEST_MSIX (1 << 10)
1164
It is not valid to specify multiple types per host or guest IRQ. However, the
1165
IRQ type of host and guest can differ or can even be null.
1167
4.50 KVM_DEASSIGN_DEV_IRQ
1169
Capability: KVM_CAP_ASSIGN_DEV_IRQ
1170
Architectures: x86 ia64
1172
Parameters: struct kvm_assigned_irq (in)
1173
Returns: 0 on success, -1 on error
1175
Ends an IRQ assignment to a passed-through device.
1177
See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1178
by assigned_dev_id, flags must correspond to the IRQ type specified on
1179
KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed.
1181
4.51 KVM_SET_GSI_ROUTING
1183
Capability: KVM_CAP_IRQ_ROUTING
1184
Architectures: x86 ia64
1186
Parameters: struct kvm_irq_routing (in)
1187
Returns: 0 on success, -1 on error
1189
Sets the GSI routing table entries, overwriting any previously set entries.
1191
struct kvm_irq_routing {
1194
struct kvm_irq_routing_entry entries[0];
1197
No flags are specified so far, the corresponding field must be set to zero.
1199
struct kvm_irq_routing_entry {
1205
struct kvm_irq_routing_irqchip irqchip;
1206
struct kvm_irq_routing_msi msi;
1211
/* gsi routing entry types */
1212
#define KVM_IRQ_ROUTING_IRQCHIP 1
1213
#define KVM_IRQ_ROUTING_MSI 2
1215
No flags are specified so far, the corresponding field must be set to zero.
1217
struct kvm_irq_routing_irqchip {
1222
struct kvm_irq_routing_msi {
1229
4.52 KVM_ASSIGN_SET_MSIX_NR
1231
Capability: KVM_CAP_DEVICE_MSIX
1232
Architectures: x86 ia64
1234
Parameters: struct kvm_assigned_msix_nr (in)
1235
Returns: 0 on success, -1 on error
1237
Set the number of MSI-X interrupts for an assigned device. This service can
1238
only be called once in the lifetime of an assigned device.
1240
struct kvm_assigned_msix_nr {
1241
__u32 assigned_dev_id;
1246
#define KVM_MAX_MSIX_PER_DEV 256
1248
4.53 KVM_ASSIGN_SET_MSIX_ENTRY
1250
Capability: KVM_CAP_DEVICE_MSIX
1251
Architectures: x86 ia64
1253
Parameters: struct kvm_assigned_msix_entry (in)
1254
Returns: 0 on success, -1 on error
1256
Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1257
the GSI vector to zero means disabling the interrupt.
1259
struct kvm_assigned_msix_entry {
1260
__u32 assigned_dev_id;
1262
__u16 entry; /* The index of entry in the MSI-X table */
1266
5. The kvm_run structure
1268
Application code obtains a pointer to the kvm_run structure by
1269
mmap()ing a vcpu fd. From that point, application code can control
1270
execution by changing fields in kvm_run prior to calling the KVM_RUN
1271
ioctl, and obtain information about the reason KVM_RUN returned by
1272
looking up structure members.
1276
__u8 request_interrupt_window;
1278
Request that KVM_RUN return when it becomes possible to inject external
1279
interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
1286
When KVM_RUN has returned successfully (return value 0), this informs
1287
application code why KVM_RUN has returned. Allowable values for this
1288
field are detailed below.
1290
__u8 ready_for_interrupt_injection;
1292
If request_interrupt_window has been specified, this field indicates
1293
an interrupt can be injected now with KVM_INTERRUPT.
1297
The value of the current interrupt flag. Only valid if in-kernel
1298
local APIC is not used.
1302
/* in (pre_kvm_run), out (post_kvm_run) */
1305
The value of the cr8 register. Only valid if in-kernel local APIC is
1306
not used. Both input and output.
1310
The value of the APIC BASE msr. Only valid if in-kernel local
1311
APIC is not used. Both input and output.
1314
/* KVM_EXIT_UNKNOWN */
1316
__u64 hardware_exit_reason;
1319
If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
1320
reasons. Further architecture-specific information is available in
1321
hardware_exit_reason.
1323
/* KVM_EXIT_FAIL_ENTRY */
1325
__u64 hardware_entry_failure_reason;
1328
If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
1329
to unknown reasons. Further architecture-specific information is
1330
available in hardware_entry_failure_reason.
1332
/* KVM_EXIT_EXCEPTION */
1342
#define KVM_EXIT_IO_IN 0
1343
#define KVM_EXIT_IO_OUT 1
1345
__u8 size; /* bytes */
1348
__u64 data_offset; /* relative to kvm_run start */
1351
If exit_reason is KVM_EXIT_IO, then the vcpu has
1352
executed a port I/O instruction which could not be satisfied by kvm.
1353
data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
1354
where kvm expects application code to place the data for the next
1355
KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
1358
struct kvm_debug_exit_arch arch;
1371
If exit_reason is KVM_EXIT_MMIO, then the vcpu has
1372
executed a memory-mapped I/O instruction which could not be satisfied
1373
by kvm. The 'data' member contains the written data if 'is_write' is
1374
true, and should be filled by application code otherwise.
1376
NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO and KVM_EXIT_OSI, the corresponding
1377
operations are complete (and guest state is consistent) only after userspace
1378
has re-entered the kernel with KVM_RUN. The kernel side will first finish
1379
incomplete operations and then check for pending signals. Userspace
1380
can re-enter the guest with an unmasked signal pending to complete
1383
/* KVM_EXIT_HYPERCALL */
1392
Unused. This was once used for 'hypercall to userspace'. To implement
1393
such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
1394
Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
1396
/* KVM_EXIT_TPR_ACCESS */
1403
To be documented (KVM_TPR_ACCESS_REPORTING).
1405
/* KVM_EXIT_S390_SIEIC */
1408
__u64 mask; /* psw upper half */
1409
__u64 addr; /* psw lower half */
1416
/* KVM_EXIT_S390_RESET */
1417
#define KVM_S390_RESET_POR 1
1418
#define KVM_S390_RESET_CLEAR 2
1419
#define KVM_S390_RESET_SUBSYSTEM 4
1420
#define KVM_S390_RESET_CPU_INIT 8
1421
#define KVM_S390_RESET_IPL 16
1422
__u64 s390_reset_flags;
1440
MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
1441
hypercalls and exit with this exit struct that contains all the guest gprs.
1443
If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
1444
Userspace can now handle the hypercall and when it's done modify the gprs as
1445
necessary. Upon guest entry all guest GPRs will then be replaced by the values
1448
/* Fix the size of the union. */
added
removed
Documentation/kvm/api.txt
