blob: b336266bea5e58238030af999a61f682e4c47a65 [file] [log] [blame]
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001The Definitive KVM (Kernel-based Virtual Machine) API Documentation
2===================================================================
3
41. General description
5
6The kvm API is a set of ioctls that are issued to control various aspects
7of a virtual machine. The ioctls belong to three classes
8
9 - System ioctls: These query and set global attributes which affect the
10 whole kvm subsystem. In addition a system ioctl is used to create
11 virtual machines
12
13 - VM ioctls: These query and set attributes that affect an entire virtual
14 machine, for example memory layout. In addition a VM ioctl is used to
15 create virtual cpus (vcpus).
16
17 Only run VM ioctls from the same process (address space) that was used
18 to create the VM.
19
20 - vcpu ioctls: These query and set attributes that control the operation
21 of a single virtual cpu.
22
23 Only run vcpu ioctls from the same thread that was used to create the
24 vcpu.
25
Wu Fengguang2044892d2009-12-24 09:04:16 +0800262. File descriptors
Avi Kivity9c1b96e2009-06-09 12:37:58 +030027
28The kvm API is centered around file descriptors. An initial
29open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
30can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this
Wu Fengguang2044892d2009-12-24 09:04:16 +080031handle will create a VM file descriptor which can be used to issue VM
Avi Kivity9c1b96e2009-06-09 12:37:58 +030032ioctls. A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu
33and return a file descriptor pointing to it. Finally, ioctls on a vcpu
34fd can be used to control the vcpu, including the important task of
35actually running guest code.
36
37In general file descriptors can be migrated among processes by means
38of fork() and the SCM_RIGHTS facility of unix domain socket. These
39kinds of tricks are explicitly not supported by kvm. While they will
40not cause harm to the host, their actual behavior is not guaranteed by
41the API. The only supported use is one virtual machine per process,
42and one vcpu per thread.
43
443. Extensions
45
46As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
47incompatible change are allowed. However, there is an extension
48facility that allows backward-compatible extensions to the API to be
49queried and used.
50
51The extension mechanism is not based on on the Linux version number.
52Instead, kvm defines extension identifiers and a facility to query
53whether a particular extension identifier is available. If it is, a
54set of ioctls is available for application use.
55
564. API description
57
58This section describes ioctls that can be used to control kvm guests.
59For each ioctl, the following information is provided along with a
60description:
61
62 Capability: which KVM extension provides this ioctl. Can be 'basic',
63 which means that is will be provided by any kernel that supports
64 API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which
65 means availability needs to be checked with KVM_CHECK_EXTENSION
66 (see section 4.4).
67
68 Architectures: which instruction set architectures provide this ioctl.
69 x86 includes both i386 and x86_64.
70
71 Type: system, vm, or vcpu.
72
73 Parameters: what parameters are accepted by the ioctl.
74
75 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
76 are not detailed, but errors with specific meanings are.
77
784.1 KVM_GET_API_VERSION
79
80Capability: basic
81Architectures: all
82Type: system ioctl
83Parameters: none
84Returns: the constant KVM_API_VERSION (=12)
85
86This identifies the API version as the stable kvm API. It is not
87expected that this number will change. However, Linux 2.6.20 and
882.6.21 report earlier versions; these are not documented and not
89supported. Applications should refuse to run if KVM_GET_API_VERSION
90returns a value other than 12. If this check passes, all ioctls
91described as 'basic' will be available.
92
934.2 KVM_CREATE_VM
94
95Capability: basic
96Architectures: all
97Type: system ioctl
98Parameters: none
99Returns: a VM fd that can be used to control the new virtual machine.
100
101The new VM has no virtual cpus and no memory. An mmap() of a VM fd
102will access the virtual machine's physical address space; offset zero
103corresponds to guest physical address zero. Use of mmap() on a VM fd
104is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is
105available.
106
1074.3 KVM_GET_MSR_INDEX_LIST
108
109Capability: basic
110Architectures: x86
111Type: system
112Parameters: struct kvm_msr_list (in/out)
113Returns: 0 on success; -1 on error
114Errors:
115 E2BIG: the msr index list is to be to fit in the array specified by
116 the user.
117
118struct kvm_msr_list {
119 __u32 nmsrs; /* number of msrs in entries */
120 __u32 indices[0];
121};
122
123This ioctl returns the guest msrs that are supported. The list varies
124by kvm version and host processor, but does not change otherwise. The
125user fills in the size of the indices array in nmsrs, and in return
126kvm adjusts nmsrs to reflect the actual number of msrs and fills in
127the indices array with their numbers.
128
Avi Kivity2e2602c2010-07-07 14:09:39 +0300129Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
130not returned in the MSR list, as different vcpus can have a different number
131of banks, as set via the KVM_X86_SETUP_MCE ioctl.
132
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001334.4 KVM_CHECK_EXTENSION
134
135Capability: basic
136Architectures: all
137Type: system ioctl
138Parameters: extension identifier (KVM_CAP_*)
139Returns: 0 if unsupported; 1 (or some other positive integer) if supported
140
141The API allows the application to query about extensions to the core
142kvm API. Userspace passes an extension identifier (an integer) and
143receives an integer that describes the extension availability.
144Generally 0 means no and 1 means yes, but some extensions may report
145additional information in the integer return value.
146
1474.5 KVM_GET_VCPU_MMAP_SIZE
148
149Capability: basic
150Architectures: all
151Type: system ioctl
152Parameters: none
153Returns: size of vcpu mmap area, in bytes
154
155The KVM_RUN ioctl (cf.) communicates with userspace via a shared
156memory region. This ioctl returns the size of that region. See the
157KVM_RUN documentation for details.
158
1594.6 KVM_SET_MEMORY_REGION
160
161Capability: basic
162Architectures: all
163Type: vm ioctl
164Parameters: struct kvm_memory_region (in)
165Returns: 0 on success, -1 on error
166
Avi Kivityb74a07b2010-06-21 11:48:05 +0300167This ioctl is obsolete and has been removed.
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300168
1694.6 KVM_CREATE_VCPU
170
171Capability: basic
172Architectures: all
173Type: vm ioctl
174Parameters: vcpu id (apic id on x86)
175Returns: vcpu fd on success, -1 on error
176
177This API adds a vcpu to a virtual machine. The vcpu id is a small integer
178in the range [0, max_vcpus).
179
1804.7 KVM_GET_DIRTY_LOG (vm ioctl)
181
182Capability: basic
183Architectures: x86
184Type: vm ioctl
185Parameters: struct kvm_dirty_log (in/out)
186Returns: 0 on success, -1 on error
187
188/* for KVM_GET_DIRTY_LOG */
189struct kvm_dirty_log {
190 __u32 slot;
191 __u32 padding;
192 union {
193 void __user *dirty_bitmap; /* one bit per page */
194 __u64 padding;
195 };
196};
197
198Given a memory slot, return a bitmap containing any pages dirtied
199since the last call to this ioctl. Bit 0 is the first page in the
200memory slot. Ensure the entire structure is cleared to avoid padding
201issues.
202
2034.8 KVM_SET_MEMORY_ALIAS
204
205Capability: basic
206Architectures: x86
207Type: vm ioctl
208Parameters: struct kvm_memory_alias (in)
209Returns: 0 (success), -1 (error)
210
Avi Kivitya1f4d3952010-06-21 11:44:20 +0300211This ioctl is obsolete and has been removed.
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300212
2134.9 KVM_RUN
214
215Capability: basic
216Architectures: all
217Type: vcpu ioctl
218Parameters: none
219Returns: 0 on success, -1 on error
220Errors:
221 EINTR: an unmasked signal is pending
222
223This ioctl is used to run a guest virtual cpu. While there are no
224explicit parameters, there is an implicit parameter block that can be
225obtained by mmap()ing the vcpu fd at offset 0, with the size given by
226KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct
227kvm_run' (see below).
228
2294.10 KVM_GET_REGS
230
231Capability: basic
232Architectures: all
233Type: vcpu ioctl
234Parameters: struct kvm_regs (out)
235Returns: 0 on success, -1 on error
236
237Reads the general purpose registers from the vcpu.
238
239/* x86 */
240struct kvm_regs {
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;
246 __u64 rip, rflags;
247};
248
2494.11 KVM_SET_REGS
250
251Capability: basic
252Architectures: all
253Type: vcpu ioctl
254Parameters: struct kvm_regs (in)
255Returns: 0 on success, -1 on error
256
257Writes the general purpose registers into the vcpu.
258
259See KVM_GET_REGS for the data structure.
260
2614.12 KVM_GET_SREGS
262
263Capability: basic
264Architectures: x86
265Type: vcpu ioctl
266Parameters: struct kvm_sregs (out)
267Returns: 0 on success, -1 on error
268
269Reads special registers from the vcpu.
270
271/* x86 */
272struct kvm_sregs {
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;
277 __u64 efer;
278 __u64 apic_base;
279 __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
280};
281
282interrupt_bitmap is a bitmap of pending external interrupts. At most
283one bit may be set. This interrupt has been acknowledged by the APIC
284but not yet injected into the cpu core.
285
2864.13 KVM_SET_SREGS
287
288Capability: basic
289Architectures: x86
290Type: vcpu ioctl
291Parameters: struct kvm_sregs (in)
292Returns: 0 on success, -1 on error
293
294Writes special registers into the vcpu. See KVM_GET_SREGS for the
295data structures.
296
2974.14 KVM_TRANSLATE
298
299Capability: basic
300Architectures: x86
301Type: vcpu ioctl
302Parameters: struct kvm_translation (in/out)
303Returns: 0 on success, -1 on error
304
305Translates a virtual address according to the vcpu's current address
306translation mode.
307
308struct kvm_translation {
309 /* in */
310 __u64 linear_address;
311
312 /* out */
313 __u64 physical_address;
314 __u8 valid;
315 __u8 writeable;
316 __u8 usermode;
317 __u8 pad[5];
318};
319
3204.15 KVM_INTERRUPT
321
322Capability: basic
Alexander Graf6f7a2bd2010-08-31 02:03:32 +0200323Architectures: x86, ppc
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300324Type: vcpu ioctl
325Parameters: struct kvm_interrupt (in)
326Returns: 0 on success, -1 on error
327
328Queues a hardware interrupt vector to be injected. This is only
Alexander Graf6f7a2bd2010-08-31 02:03:32 +0200329useful if in-kernel local APIC or equivalent is not used.
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300330
331/* for KVM_INTERRUPT */
332struct kvm_interrupt {
333 /* in */
334 __u32 irq;
335};
336
Alexander Graf6f7a2bd2010-08-31 02:03:32 +0200337X86:
338
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300339Note 'irq' is an interrupt vector, not an interrupt pin or line.
340
Alexander Graf6f7a2bd2010-08-31 02:03:32 +0200341PPC:
342
343Queues an external interrupt to be injected. This ioctl is overleaded
344with 3 different irq values:
345
346a) KVM_INTERRUPT_SET
347
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.
350
351b) KVM_INTERRUPT_UNSET
352
353 This unsets any pending interrupt.
354
355 Only available with KVM_CAP_PPC_UNSET_IRQ.
356
357c) KVM_INTERRUPT_SET_LEVEL
358
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
361 is triggered.
362
363 Only available with KVM_CAP_PPC_IRQ_LEVEL.
364
365Note that any value for 'irq' other than the ones stated above is invalid
366and incurs unexpected behavior.
367
Avi Kivity9c1b96e2009-06-09 12:37:58 +03003684.16 KVM_DEBUG_GUEST
369
370Capability: basic
371Architectures: none
372Type: vcpu ioctl
373Parameters: none)
374Returns: -1 on error
375
376Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.
377
3784.17 KVM_GET_MSRS
379
380Capability: basic
381Architectures: x86
382Type: vcpu ioctl
383Parameters: struct kvm_msrs (in/out)
384Returns: 0 on success, -1 on error
385
386Reads model-specific registers from the vcpu. Supported msr indices can
387be obtained using KVM_GET_MSR_INDEX_LIST.
388
389struct kvm_msrs {
390 __u32 nmsrs; /* number of msrs in entries */
391 __u32 pad;
392
393 struct kvm_msr_entry entries[0];
394};
395
396struct kvm_msr_entry {
397 __u32 index;
398 __u32 reserved;
399 __u64 data;
400};
401
402Application code should set the 'nmsrs' member (which indicates the
403size of the entries array) and the 'index' member of each array entry.
404kvm will fill in the 'data' member.
405
4064.18 KVM_SET_MSRS
407
408Capability: basic
409Architectures: x86
410Type: vcpu ioctl
411Parameters: struct kvm_msrs (in)
412Returns: 0 on success, -1 on error
413
414Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
415data structures.
416
417Application code should set the 'nmsrs' member (which indicates the
418size of the entries array), and the 'index' and 'data' members of each
419array entry.
420
4214.19 KVM_SET_CPUID
422
423Capability: basic
424Architectures: x86
425Type: vcpu ioctl
426Parameters: struct kvm_cpuid (in)
427Returns: 0 on success, -1 on error
428
429Defines the vcpu responses to the cpuid instruction. Applications
430should use the KVM_SET_CPUID2 ioctl if available.
431
432
433struct kvm_cpuid_entry {
434 __u32 function;
435 __u32 eax;
436 __u32 ebx;
437 __u32 ecx;
438 __u32 edx;
439 __u32 padding;
440};
441
442/* for KVM_SET_CPUID */
443struct kvm_cpuid {
444 __u32 nent;
445 __u32 padding;
446 struct kvm_cpuid_entry entries[0];
447};
448
4494.20 KVM_SET_SIGNAL_MASK
450
451Capability: basic
452Architectures: x86
453Type: vcpu ioctl
454Parameters: struct kvm_signal_mask (in)
455Returns: 0 on success, -1 on error
456
457Defines which signals are blocked during execution of KVM_RUN. This
458signal mask temporarily overrides the threads signal mask. Any
459unblocked signal received (except SIGKILL and SIGSTOP, which retain
460their traditional behaviour) will cause KVM_RUN to return with -EINTR.
461
462Note the signal will only be delivered if not blocked by the original
463signal mask.
464
465/* for KVM_SET_SIGNAL_MASK */
466struct kvm_signal_mask {
467 __u32 len;
468 __u8 sigset[0];
469};
470
4714.21 KVM_GET_FPU
472
473Capability: basic
474Architectures: x86
475Type: vcpu ioctl
476Parameters: struct kvm_fpu (out)
477Returns: 0 on success, -1 on error
478
479Reads the floating point state from the vcpu.
480
481/* for KVM_GET_FPU and KVM_SET_FPU */
482struct kvm_fpu {
483 __u8 fpr[8][16];
484 __u16 fcw;
485 __u16 fsw;
486 __u8 ftwx; /* in fxsave format */
487 __u8 pad1;
488 __u16 last_opcode;
489 __u64 last_ip;
490 __u64 last_dp;
491 __u8 xmm[16][16];
492 __u32 mxcsr;
493 __u32 pad2;
494};
495
4964.22 KVM_SET_FPU
497
498Capability: basic
499Architectures: x86
500Type: vcpu ioctl
501Parameters: struct kvm_fpu (in)
502Returns: 0 on success, -1 on error
503
504Writes the floating point state to the vcpu.
505
506/* for KVM_GET_FPU and KVM_SET_FPU */
507struct kvm_fpu {
508 __u8 fpr[8][16];
509 __u16 fcw;
510 __u16 fsw;
511 __u8 ftwx; /* in fxsave format */
512 __u8 pad1;
513 __u16 last_opcode;
514 __u64 last_ip;
515 __u64 last_dp;
516 __u8 xmm[16][16];
517 __u32 mxcsr;
518 __u32 pad2;
519};
520
Avi Kivity5dadbfd2009-08-23 17:08:04 +03005214.23 KVM_CREATE_IRQCHIP
522
523Capability: KVM_CAP_IRQCHIP
524Architectures: x86, ia64
525Type: vm ioctl
526Parameters: none
527Returns: 0 on success, -1 on error
528
529Creates an interrupt controller model in the kernel. On x86, creates a virtual
530ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a
531local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23
532only go to the IOAPIC. On ia64, a IOSAPIC is created.
533
5344.24 KVM_IRQ_LINE
535
536Capability: KVM_CAP_IRQCHIP
537Architectures: x86, ia64
538Type: vm ioctl
539Parameters: struct kvm_irq_level
540Returns: 0 on success, -1 on error
541
542Sets the level of a GSI input to the interrupt controller model in the kernel.
543Requires that an interrupt controller model has been previously created with
544KVM_CREATE_IRQCHIP. Note that edge-triggered interrupts require the level
545to be set to 1 and then back to 0.
546
547struct kvm_irq_level {
548 union {
549 __u32 irq; /* GSI */
550 __s32 status; /* not used for KVM_IRQ_LEVEL */
551 };
552 __u32 level; /* 0 or 1 */
553};
554
5554.25 KVM_GET_IRQCHIP
556
557Capability: KVM_CAP_IRQCHIP
558Architectures: x86, ia64
559Type: vm ioctl
560Parameters: struct kvm_irqchip (in/out)
561Returns: 0 on success, -1 on error
562
563Reads the state of a kernel interrupt controller created with
564KVM_CREATE_IRQCHIP into a buffer provided by the caller.
565
566struct kvm_irqchip {
567 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
568 __u32 pad;
569 union {
570 char dummy[512]; /* reserving space */
571 struct kvm_pic_state pic;
572 struct kvm_ioapic_state ioapic;
573 } chip;
574};
575
5764.26 KVM_SET_IRQCHIP
577
578Capability: KVM_CAP_IRQCHIP
579Architectures: x86, ia64
580Type: vm ioctl
581Parameters: struct kvm_irqchip (in)
582Returns: 0 on success, -1 on error
583
584Sets the state of a kernel interrupt controller created with
585KVM_CREATE_IRQCHIP from a buffer provided by the caller.
586
587struct kvm_irqchip {
588 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
589 __u32 pad;
590 union {
591 char dummy[512]; /* reserving space */
592 struct kvm_pic_state pic;
593 struct kvm_ioapic_state ioapic;
594 } chip;
595};
596
Ed Swierkffde22a2009-10-15 15:21:43 -07005974.27 KVM_XEN_HVM_CONFIG
598
599Capability: KVM_CAP_XEN_HVM
600Architectures: x86
601Type: vm ioctl
602Parameters: struct kvm_xen_hvm_config (in)
603Returns: 0 on success, -1 on error
604
605Sets the MSR that the Xen HVM guest uses to initialize its hypercall
606page, and provides the starting address and size of the hypercall
607blobs in userspace. When the guest writes the MSR, kvm copies one
608page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
609memory.
610
611struct kvm_xen_hvm_config {
612 __u32 flags;
613 __u32 msr;
614 __u64 blob_addr_32;
615 __u64 blob_addr_64;
616 __u8 blob_size_32;
617 __u8 blob_size_64;
618 __u8 pad2[30];
619};
620
Glauber Costaafbcf7a2009-10-16 15:28:36 -04006214.27 KVM_GET_CLOCK
622
623Capability: KVM_CAP_ADJUST_CLOCK
624Architectures: x86
625Type: vm ioctl
626Parameters: struct kvm_clock_data (out)
627Returns: 0 on success, -1 on error
628
629Gets the current timestamp of kvmclock as seen by the current guest. In
630conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
631such as migration.
632
633struct kvm_clock_data {
634 __u64 clock; /* kvmclock current value */
635 __u32 flags;
636 __u32 pad[9];
637};
638
6394.28 KVM_SET_CLOCK
640
641Capability: KVM_CAP_ADJUST_CLOCK
642Architectures: x86
643Type: vm ioctl
644Parameters: struct kvm_clock_data (in)
645Returns: 0 on success, -1 on error
646
Wu Fengguang2044892d2009-12-24 09:04:16 +0800647Sets the current timestamp of kvmclock to the value specified in its parameter.
Glauber Costaafbcf7a2009-10-16 15:28:36 -0400648In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
649such as migration.
650
651struct kvm_clock_data {
652 __u64 clock; /* kvmclock current value */
653 __u32 flags;
654 __u32 pad[9];
655};
656
Jan Kiszka3cfc3092009-11-12 01:04:25 +01006574.29 KVM_GET_VCPU_EVENTS
658
659Capability: KVM_CAP_VCPU_EVENTS
Jan Kiszka48005f62010-02-19 19:38:07 +0100660Extended by: KVM_CAP_INTR_SHADOW
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100661Architectures: x86
662Type: vm ioctl
663Parameters: struct kvm_vcpu_event (out)
664Returns: 0 on success, -1 on error
665
666Gets currently pending exceptions, interrupts, and NMIs as well as related
667states of the vcpu.
668
669struct kvm_vcpu_events {
670 struct {
671 __u8 injected;
672 __u8 nr;
673 __u8 has_error_code;
674 __u8 pad;
675 __u32 error_code;
676 } exception;
677 struct {
678 __u8 injected;
679 __u8 nr;
680 __u8 soft;
Jan Kiszka48005f62010-02-19 19:38:07 +0100681 __u8 shadow;
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100682 } interrupt;
683 struct {
684 __u8 injected;
685 __u8 pending;
686 __u8 masked;
687 __u8 pad;
688 } nmi;
689 __u32 sipi_vector;
Jan Kiszkadab4b912009-12-06 18:24:15 +0100690 __u32 flags;
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100691};
692
Jan Kiszka48005f62010-02-19 19:38:07 +0100693KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
694interrupt.shadow contains a valid state. Otherwise, this field is undefined.
695
Jan Kiszka3cfc3092009-11-12 01:04:25 +01006964.30 KVM_SET_VCPU_EVENTS
697
698Capability: KVM_CAP_VCPU_EVENTS
Jan Kiszka48005f62010-02-19 19:38:07 +0100699Extended by: KVM_CAP_INTR_SHADOW
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100700Architectures: x86
701Type: vm ioctl
702Parameters: struct kvm_vcpu_event (in)
703Returns: 0 on success, -1 on error
704
705Set pending exceptions, interrupts, and NMIs as well as related states of the
706vcpu.
707
708See KVM_GET_VCPU_EVENTS for the data structure.
709
Jan Kiszkadab4b912009-12-06 18:24:15 +0100710Fields that may be modified asynchronously by running VCPUs can be excluded
711from the update. These fields are nmi.pending and sipi_vector. Keep the
712corresponding bits in the flags field cleared to suppress overwriting the
713current in-kernel state. The bits are:
714
715KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
716KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
717
Jan Kiszka48005f62010-02-19 19:38:07 +0100718If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
719the flags field to signal that interrupt.shadow contains a valid state and
720shall be written into the VCPU.
721
Jan Kiszkaa1efbe72010-02-15 10:45:43 +01007224.32 KVM_GET_DEBUGREGS
723
724Capability: KVM_CAP_DEBUGREGS
725Architectures: x86
726Type: vm ioctl
727Parameters: struct kvm_debugregs (out)
728Returns: 0 on success, -1 on error
729
730Reads debug registers from the vcpu.
731
732struct kvm_debugregs {
733 __u64 db[4];
734 __u64 dr6;
735 __u64 dr7;
736 __u64 flags;
737 __u64 reserved[9];
738};
739
7404.33 KVM_SET_DEBUGREGS
741
742Capability: KVM_CAP_DEBUGREGS
743Architectures: x86
744Type: vm ioctl
745Parameters: struct kvm_debugregs (in)
746Returns: 0 on success, -1 on error
747
748Writes debug registers into the vcpu.
749
750See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
751yet and must be cleared on entry.
752
Avi Kivity0f2d8f42010-03-25 12:16:48 +02007534.34 KVM_SET_USER_MEMORY_REGION
754
755Capability: KVM_CAP_USER_MEM
756Architectures: all
757Type: vm ioctl
758Parameters: struct kvm_userspace_memory_region (in)
759Returns: 0 on success, -1 on error
760
761struct kvm_userspace_memory_region {
762 __u32 slot;
763 __u32 flags;
764 __u64 guest_phys_addr;
765 __u64 memory_size; /* bytes */
766 __u64 userspace_addr; /* start of the userspace allocated memory */
767};
768
769/* for kvm_memory_region::flags */
770#define KVM_MEM_LOG_DIRTY_PAGES 1UL
771
772This ioctl allows the user to create or modify a guest physical memory
773slot. When changing an existing slot, it may be moved in the guest
774physical memory space, or its flags may be modified. It may not be
775resized. Slots may not overlap in guest physical address space.
776
777Memory for the region is taken starting at the address denoted by the
778field userspace_addr, which must point at user addressable memory for
779the entire memory slot size. Any object may back this memory, including
780anonymous memory, ordinary files, and hugetlbfs.
781
782It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
783be identical. This allows large pages in the guest to be backed by large
784pages in the host.
785
786The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which
787instructs kvm to keep track of writes to memory within the slot. See
788the KVM_GET_DIRTY_LOG ioctl.
789
790When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory
791region are automatically reflected into the guest. For example, an mmap()
792that affects the region will be made visible immediately. Another example
793is madvise(MADV_DROP).
794
795It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
796The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
797allocation and is deprecated.
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100798
Avi Kivity8a5416d2010-03-25 12:27:30 +02007994.35 KVM_SET_TSS_ADDR
800
801Capability: KVM_CAP_SET_TSS_ADDR
802Architectures: x86
803Type: vm ioctl
804Parameters: unsigned long tss_address (in)
805Returns: 0 on success, -1 on error
806
807This ioctl defines the physical address of a three-page region in the guest
808physical address space. The region must be within the first 4GB of the
809guest physical address space and must not conflict with any memory slot
810or any mmio address. The guest may malfunction if it accesses this memory
811region.
812
813This ioctl is required on Intel-based hosts. This is needed on Intel hardware
814because of a quirk in the virtualization implementation (see the internals
815documentation when it pops into existence).
816
Alexander Graf71fbfd52010-03-24 21:48:29 +01008174.36 KVM_ENABLE_CAP
818
819Capability: KVM_CAP_ENABLE_CAP
820Architectures: ppc
821Type: vcpu ioctl
822Parameters: struct kvm_enable_cap (in)
823Returns: 0 on success; -1 on error
824
825+Not all extensions are enabled by default. Using this ioctl the application
826can enable an extension, making it available to the guest.
827
828On systems that do not support this ioctl, it always fails. On systems that
829do support it, it only works for extensions that are supported for enablement.
830
831To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
832be used.
833
834struct kvm_enable_cap {
835 /* in */
836 __u32 cap;
837
838The capability that is supposed to get enabled.
839
840 __u32 flags;
841
842A bitfield indicating future enhancements. Has to be 0 for now.
843
844 __u64 args[4];
845
846Arguments for enabling a feature. If a feature needs initial values to
847function properly, this is the place to put them.
848
849 __u8 pad[64];
850};
851
Avi Kivityb843f062010-04-25 15:51:46 +03008524.37 KVM_GET_MP_STATE
853
854Capability: KVM_CAP_MP_STATE
855Architectures: x86, ia64
856Type: vcpu ioctl
857Parameters: struct kvm_mp_state (out)
858Returns: 0 on success; -1 on error
859
860struct kvm_mp_state {
861 __u32 mp_state;
862};
863
864Returns the vcpu's current "multiprocessing state" (though also valid on
865uniprocessor guests).
866
867Possible values are:
868
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
873 now ready for a SIPI
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 accesible via KVM_GET_VCPU_EVENTS)
878
879This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
880irqchip, the multiprocessing state must be maintained by userspace.
881
8824.38 KVM_SET_MP_STATE
883
884Capability: KVM_CAP_MP_STATE
885Architectures: x86, ia64
886Type: vcpu ioctl
887Parameters: struct kvm_mp_state (in)
888Returns: 0 on success; -1 on error
889
890Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
891arguments.
892
893This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
894irqchip, the multiprocessing state must be maintained by userspace.
895
Avi Kivity47dbb842010-04-29 12:08:56 +03008964.39 KVM_SET_IDENTITY_MAP_ADDR
897
898Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
899Architectures: x86
900Type: vm ioctl
901Parameters: unsigned long identity (in)
902Returns: 0 on success, -1 on error
903
904This ioctl defines the physical address of a one-page region in the guest
905physical address space. The region must be within the first 4GB of the
906guest physical address space and must not conflict with any memory slot
907or any mmio address. The guest may malfunction if it accesses this memory
908region.
909
910This ioctl is required on Intel-based hosts. This is needed on Intel hardware
911because of a quirk in the virtualization implementation (see the internals
912documentation when it pops into existence).
913
Avi Kivity57bc24c2010-04-29 12:12:57 +03009144.40 KVM_SET_BOOT_CPU_ID
915
916Capability: KVM_CAP_SET_BOOT_CPU_ID
917Architectures: x86, ia64
918Type: vm ioctl
919Parameters: unsigned long vcpu_id
920Returns: 0 on success, -1 on error
921
922Define which vcpu is the Bootstrap Processor (BSP). Values are the same
923as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
924is vcpu 0.
925
Sheng Yang2d5b5a62010-06-13 17:29:39 +08009264.41 KVM_GET_XSAVE
927
928Capability: KVM_CAP_XSAVE
929Architectures: x86
930Type: vcpu ioctl
931Parameters: struct kvm_xsave (out)
932Returns: 0 on success, -1 on error
933
934struct kvm_xsave {
935 __u32 region[1024];
936};
937
938This ioctl would copy current vcpu's xsave struct to the userspace.
939
9404.42 KVM_SET_XSAVE
941
942Capability: KVM_CAP_XSAVE
943Architectures: x86
944Type: vcpu ioctl
945Parameters: struct kvm_xsave (in)
946Returns: 0 on success, -1 on error
947
948struct kvm_xsave {
949 __u32 region[1024];
950};
951
952This ioctl would copy userspace's xsave struct to the kernel.
953
9544.43 KVM_GET_XCRS
955
956Capability: KVM_CAP_XCRS
957Architectures: x86
958Type: vcpu ioctl
959Parameters: struct kvm_xcrs (out)
960Returns: 0 on success, -1 on error
961
962struct kvm_xcr {
963 __u32 xcr;
964 __u32 reserved;
965 __u64 value;
966};
967
968struct kvm_xcrs {
969 __u32 nr_xcrs;
970 __u32 flags;
971 struct kvm_xcr xcrs[KVM_MAX_XCRS];
972 __u64 padding[16];
973};
974
975This ioctl would copy current vcpu's xcrs to the userspace.
976
9774.44 KVM_SET_XCRS
978
979Capability: KVM_CAP_XCRS
980Architectures: x86
981Type: vcpu ioctl
982Parameters: struct kvm_xcrs (in)
983Returns: 0 on success, -1 on error
984
985struct kvm_xcr {
986 __u32 xcr;
987 __u32 reserved;
988 __u64 value;
989};
990
991struct kvm_xcrs {
992 __u32 nr_xcrs;
993 __u32 flags;
994 struct kvm_xcr xcrs[KVM_MAX_XCRS];
995 __u64 padding[16];
996};
997
998This ioctl would set vcpu's xcr to the value userspace specified.
999
Avi Kivityd1535132010-07-14 09:45:21 +030010004.45 KVM_GET_SUPPORTED_CPUID
1001
1002Capability: KVM_CAP_EXT_CPUID
1003Architectures: x86
1004Type: system ioctl
1005Parameters: struct kvm_cpuid2 (in/out)
1006Returns: 0 on success, -1 on error
1007
1008struct kvm_cpuid2 {
1009 __u32 nent;
1010 __u32 padding;
1011 struct kvm_cpuid_entry2 entries[0];
1012};
1013
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
1017
1018struct kvm_cpuid_entry2 {
1019 __u32 function;
1020 __u32 index;
1021 __u32 flags;
1022 __u32 eax;
1023 __u32 ebx;
1024 __u32 ecx;
1025 __u32 edx;
1026 __u32 padding[3];
1027};
1028
1029This ioctl returns x86 cpuid features which are supported by both the hardware
1030and kvm. Userspace can use the information returned by this ioctl to
1031construct cpuid information (for KVM_SET_CPUID2) that is consistent with
1032hardware, kernel, and userspace capabilities, and with user requirements (for
1033example, the user may wish to constrain cpuid to emulate older hardware,
1034or for feature consistency across a cluster).
1035
1036Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1037with the 'nent' field indicating the number of entries in the variable-size
1038array 'entries'. If the number of entries is too low to describe the cpu
1039capabilities, an error (E2BIG) is returned. If the number is too high,
1040the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
1041number is just right, the 'nent' field is adjusted to the number of valid
1042entries in the 'entries' array, which is then filled.
1043
1044The entries returned are the host cpuid as returned by the cpuid instruction,
Avi Kivityc39cbd22010-09-12 16:39:11 +02001045with unknown or unsupported features masked out. Some features (for example,
1046x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1047emulate them efficiently. The fields in each entry are defined as follows:
Avi Kivityd1535132010-07-14 09:45:21 +03001048
1049 function: the eax value used to obtain the entry
1050 index: the ecx value used to obtain the entry (for entries that are
1051 affected by ecx)
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
1064
Alexander Graf15711e92010-07-29 14:48:08 +020010654.46 KVM_PPC_GET_PVINFO
1066
1067Capability: KVM_CAP_PPC_GET_PVINFO
1068Architectures: ppc
1069Type: vm ioctl
1070Parameters: struct kvm_ppc_pvinfo (out)
1071Returns: 0 on success, !0 on error
1072
1073struct kvm_ppc_pvinfo {
1074 __u32 flags;
1075 __u32 hcall[4];
1076 __u8 pad[108];
1077};
1078
1079This ioctl fetches PV specific information that need to be passed to the guest
1080using the device tree or other means from vm context.
1081
1082For now the only implemented piece of information distributed here is an array
1083of 4 instructions that make up a hypercall.
1084
1085If any additional field gets added to this structure later on, a bit for that
1086additional piece of information will be set in the flags bitmap.
1087
Avi Kivity9c1b96e2009-06-09 12:37:58 +030010885. The kvm_run structure
1089
1090Application code obtains a pointer to the kvm_run structure by
1091mmap()ing a vcpu fd. From that point, application code can control
1092execution by changing fields in kvm_run prior to calling the KVM_RUN
1093ioctl, and obtain information about the reason KVM_RUN returned by
1094looking up structure members.
1095
1096struct kvm_run {
1097 /* in */
1098 __u8 request_interrupt_window;
1099
1100Request that KVM_RUN return when it becomes possible to inject external
1101interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
1102
1103 __u8 padding1[7];
1104
1105 /* out */
1106 __u32 exit_reason;
1107
1108When KVM_RUN has returned successfully (return value 0), this informs
1109application code why KVM_RUN has returned. Allowable values for this
1110field are detailed below.
1111
1112 __u8 ready_for_interrupt_injection;
1113
1114If request_interrupt_window has been specified, this field indicates
1115an interrupt can be injected now with KVM_INTERRUPT.
1116
1117 __u8 if_flag;
1118
1119The value of the current interrupt flag. Only valid if in-kernel
1120local APIC is not used.
1121
1122 __u8 padding2[2];
1123
1124 /* in (pre_kvm_run), out (post_kvm_run) */
1125 __u64 cr8;
1126
1127The value of the cr8 register. Only valid if in-kernel local APIC is
1128not used. Both input and output.
1129
1130 __u64 apic_base;
1131
1132The value of the APIC BASE msr. Only valid if in-kernel local
1133APIC is not used. Both input and output.
1134
1135 union {
1136 /* KVM_EXIT_UNKNOWN */
1137 struct {
1138 __u64 hardware_exit_reason;
1139 } hw;
1140
1141If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
1142reasons. Further architecture-specific information is available in
1143hardware_exit_reason.
1144
1145 /* KVM_EXIT_FAIL_ENTRY */
1146 struct {
1147 __u64 hardware_entry_failure_reason;
1148 } fail_entry;
1149
1150If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
1151to unknown reasons. Further architecture-specific information is
1152available in hardware_entry_failure_reason.
1153
1154 /* KVM_EXIT_EXCEPTION */
1155 struct {
1156 __u32 exception;
1157 __u32 error_code;
1158 } ex;
1159
1160Unused.
1161
1162 /* KVM_EXIT_IO */
1163 struct {
1164#define KVM_EXIT_IO_IN 0
1165#define KVM_EXIT_IO_OUT 1
1166 __u8 direction;
1167 __u8 size; /* bytes */
1168 __u16 port;
1169 __u32 count;
1170 __u64 data_offset; /* relative to kvm_run start */
1171 } io;
1172
Wu Fengguang2044892d2009-12-24 09:04:16 +08001173If exit_reason is KVM_EXIT_IO, then the vcpu has
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001174executed a port I/O instruction which could not be satisfied by kvm.
1175data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
1176where kvm expects application code to place the data for the next
Wu Fengguang2044892d2009-12-24 09:04:16 +08001177KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001178
1179 struct {
1180 struct kvm_debug_exit_arch arch;
1181 } debug;
1182
1183Unused.
1184
1185 /* KVM_EXIT_MMIO */
1186 struct {
1187 __u64 phys_addr;
1188 __u8 data[8];
1189 __u32 len;
1190 __u8 is_write;
1191 } mmio;
1192
Wu Fengguang2044892d2009-12-24 09:04:16 +08001193If exit_reason is KVM_EXIT_MMIO, then the vcpu has
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001194executed a memory-mapped I/O instruction which could not be satisfied
1195by kvm. The 'data' member contains the written data if 'is_write' is
1196true, and should be filled by application code otherwise.
1197
Alexander Grafad0a0482010-03-24 21:48:30 +01001198NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO and KVM_EXIT_OSI, the corresponding
1199operations are complete (and guest state is consistent) only after userspace
1200has re-entered the kernel with KVM_RUN. The kernel side will first finish
Marcelo Tosatti67961342010-02-13 16:10:26 -02001201incomplete operations and then check for pending signals. Userspace
1202can re-enter the guest with an unmasked signal pending to complete
1203pending operations.
1204
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001205 /* KVM_EXIT_HYPERCALL */
1206 struct {
1207 __u64 nr;
1208 __u64 args[6];
1209 __u64 ret;
1210 __u32 longmode;
1211 __u32 pad;
1212 } hypercall;
1213
Avi Kivity647dc492010-04-01 14:39:21 +03001214Unused. This was once used for 'hypercall to userspace'. To implement
1215such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
1216Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001217
1218 /* KVM_EXIT_TPR_ACCESS */
1219 struct {
1220 __u64 rip;
1221 __u32 is_write;
1222 __u32 pad;
1223 } tpr_access;
1224
1225To be documented (KVM_TPR_ACCESS_REPORTING).
1226
1227 /* KVM_EXIT_S390_SIEIC */
1228 struct {
1229 __u8 icptcode;
1230 __u64 mask; /* psw upper half */
1231 __u64 addr; /* psw lower half */
1232 __u16 ipa;
1233 __u32 ipb;
1234 } s390_sieic;
1235
1236s390 specific.
1237
1238 /* KVM_EXIT_S390_RESET */
1239#define KVM_S390_RESET_POR 1
1240#define KVM_S390_RESET_CLEAR 2
1241#define KVM_S390_RESET_SUBSYSTEM 4
1242#define KVM_S390_RESET_CPU_INIT 8
1243#define KVM_S390_RESET_IPL 16
1244 __u64 s390_reset_flags;
1245
1246s390 specific.
1247
1248 /* KVM_EXIT_DCR */
1249 struct {
1250 __u32 dcrn;
1251 __u32 data;
1252 __u8 is_write;
1253 } dcr;
1254
1255powerpc specific.
1256
Alexander Grafad0a0482010-03-24 21:48:30 +01001257 /* KVM_EXIT_OSI */
1258 struct {
1259 __u64 gprs[32];
1260 } osi;
1261
1262MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
1263hypercalls and exit with this exit struct that contains all the guest gprs.
1264
1265If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
1266Userspace can now handle the hypercall and when it's done modify the gprs as
1267necessary. Upon guest entry all guest GPRs will then be replaced by the values
1268in this struct.
1269
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001270 /* Fix the size of the union. */
1271 char padding[256];
1272 };
1273};