KVM: Expose MCE control MSRs to userspace
[linux-2.6.git] / Documentation / kvm / api.txt
1 The Definitive KVM (Kernel-based Virtual Machine) API Documentation
2 ===================================================================
3
4 1. General description
5
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
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
26 2. File descriptors
27
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.
36
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.
43
44 3. Extensions
45
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
49 queried and used.
50
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.
55
56 4. API description
57
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
60 description:
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
78 4.1 KVM_GET_API_VERSION
79
80 Capability: basic
81 Architectures: all
82 Type: system ioctl
83 Parameters: none
84 Returns: the constant KVM_API_VERSION (=12)
85
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.
92
93 4.2 KVM_CREATE_VM
94
95 Capability: basic
96 Architectures: all
97 Type: system ioctl
98 Parameters: none
99 Returns: a VM fd that can be used to control the new virtual machine.
100
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
105 available.
106
107 4.3 KVM_GET_MSR_INDEX_LIST
108
109 Capability: basic
110 Architectures: x86
111 Type: system
112 Parameters: struct kvm_msr_list (in/out)
113 Returns: 0 on success; -1 on error
114 Errors:
115   E2BIG:     the msr index list is to be to fit in the array specified by
116              the user.
117
118 struct kvm_msr_list {
119         __u32 nmsrs; /* number of msrs in entries */
120         __u32 indices[0];
121 };
122
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.
128
129 4.4 KVM_CHECK_EXTENSION
130
131 Capability: basic
132 Architectures: all
133 Type: system ioctl
134 Parameters: extension identifier (KVM_CAP_*)
135 Returns: 0 if unsupported; 1 (or some other positive integer) if supported
136
137 The API allows the application to query about extensions to the core
138 kvm API.  Userspace passes an extension identifier (an integer) and
139 receives an integer that describes the extension availability.
140 Generally 0 means no and 1 means yes, but some extensions may report
141 additional information in the integer return value.
142
143 4.5 KVM_GET_VCPU_MMAP_SIZE
144
145 Capability: basic
146 Architectures: all
147 Type: system ioctl
148 Parameters: none
149 Returns: size of vcpu mmap area, in bytes
150
151 The KVM_RUN ioctl (cf.) communicates with userspace via a shared
152 memory region.  This ioctl returns the size of that region.  See the
153 KVM_RUN documentation for details.
154
155 4.6 KVM_SET_MEMORY_REGION
156
157 Capability: basic
158 Architectures: all
159 Type: vm ioctl
160 Parameters: struct kvm_memory_region (in)
161 Returns: 0 on success, -1 on error
162
163 This ioctl is obsolete and has been removed.
164
165 4.6 KVM_CREATE_VCPU
166
167 Capability: basic
168 Architectures: all
169 Type: vm ioctl
170 Parameters: vcpu id (apic id on x86)
171 Returns: vcpu fd on success, -1 on error
172
173 This API adds a vcpu to a virtual machine.  The vcpu id is a small integer
174 in the range [0, max_vcpus).
175
176 4.7 KVM_GET_DIRTY_LOG (vm ioctl)
177
178 Capability: basic
179 Architectures: x86
180 Type: vm ioctl
181 Parameters: struct kvm_dirty_log (in/out)
182 Returns: 0 on success, -1 on error
183
184 /* for KVM_GET_DIRTY_LOG */
185 struct kvm_dirty_log {
186         __u32 slot;
187         __u32 padding;
188         union {
189                 void __user *dirty_bitmap; /* one bit per page */
190                 __u64 padding;
191         };
192 };
193
194 Given a memory slot, return a bitmap containing any pages dirtied
195 since the last call to this ioctl.  Bit 0 is the first page in the
196 memory slot.  Ensure the entire structure is cleared to avoid padding
197 issues.
198
199 4.8 KVM_SET_MEMORY_ALIAS
200
201 Capability: basic
202 Architectures: x86
203 Type: vm ioctl
204 Parameters: struct kvm_memory_alias (in)
205 Returns: 0 (success), -1 (error)
206
207 This ioctl is obsolete and has been removed.
208
209 4.9 KVM_RUN
210
211 Capability: basic
212 Architectures: all
213 Type: vcpu ioctl
214 Parameters: none
215 Returns: 0 on success, -1 on error
216 Errors:
217   EINTR:     an unmasked signal is pending
218
219 This ioctl is used to run a guest virtual cpu.  While there are no
220 explicit parameters, there is an implicit parameter block that can be
221 obtained by mmap()ing the vcpu fd at offset 0, with the size given by
222 KVM_GET_VCPU_MMAP_SIZE.  The parameter block is formatted as a 'struct
223 kvm_run' (see below).
224
225 4.10 KVM_GET_REGS
226
227 Capability: basic
228 Architectures: all
229 Type: vcpu ioctl
230 Parameters: struct kvm_regs (out)
231 Returns: 0 on success, -1 on error
232
233 Reads the general purpose registers from the vcpu.
234
235 /* x86 */
236 struct kvm_regs {
237         /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
238         __u64 rax, rbx, rcx, rdx;
239         __u64 rsi, rdi, rsp, rbp;
240         __u64 r8,  r9,  r10, r11;
241         __u64 r12, r13, r14, r15;
242         __u64 rip, rflags;
243 };
244
245 4.11 KVM_SET_REGS
246
247 Capability: basic
248 Architectures: all
249 Type: vcpu ioctl
250 Parameters: struct kvm_regs (in)
251 Returns: 0 on success, -1 on error
252
253 Writes the general purpose registers into the vcpu.
254
255 See KVM_GET_REGS for the data structure.
256
257 4.12 KVM_GET_SREGS
258
259 Capability: basic
260 Architectures: x86
261 Type: vcpu ioctl
262 Parameters: struct kvm_sregs (out)
263 Returns: 0 on success, -1 on error
264
265 Reads special registers from the vcpu.
266
267 /* x86 */
268 struct kvm_sregs {
269         struct kvm_segment cs, ds, es, fs, gs, ss;
270         struct kvm_segment tr, ldt;
271         struct kvm_dtable gdt, idt;
272         __u64 cr0, cr2, cr3, cr4, cr8;
273         __u64 efer;
274         __u64 apic_base;
275         __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
276 };
277
278 interrupt_bitmap is a bitmap of pending external interrupts.  At most
279 one bit may be set.  This interrupt has been acknowledged by the APIC
280 but not yet injected into the cpu core.
281
282 4.13 KVM_SET_SREGS
283
284 Capability: basic
285 Architectures: x86
286 Type: vcpu ioctl
287 Parameters: struct kvm_sregs (in)
288 Returns: 0 on success, -1 on error
289
290 Writes special registers into the vcpu.  See KVM_GET_SREGS for the
291 data structures.
292
293 4.14 KVM_TRANSLATE
294
295 Capability: basic
296 Architectures: x86
297 Type: vcpu ioctl
298 Parameters: struct kvm_translation (in/out)
299 Returns: 0 on success, -1 on error
300
301 Translates a virtual address according to the vcpu's current address
302 translation mode.
303
304 struct kvm_translation {
305         /* in */
306         __u64 linear_address;
307
308         /* out */
309         __u64 physical_address;
310         __u8  valid;
311         __u8  writeable;
312         __u8  usermode;
313         __u8  pad[5];
314 };
315
316 4.15 KVM_INTERRUPT
317
318 Capability: basic
319 Architectures: x86
320 Type: vcpu ioctl
321 Parameters: struct kvm_interrupt (in)
322 Returns: 0 on success, -1 on error
323
324 Queues a hardware interrupt vector to be injected.  This is only
325 useful if in-kernel local APIC is not used.
326
327 /* for KVM_INTERRUPT */
328 struct kvm_interrupt {
329         /* in */
330         __u32 irq;
331 };
332
333 Note 'irq' is an interrupt vector, not an interrupt pin or line.
334
335 4.16 KVM_DEBUG_GUEST
336
337 Capability: basic
338 Architectures: none
339 Type: vcpu ioctl
340 Parameters: none)
341 Returns: -1 on error
342
343 Support for this has been removed.  Use KVM_SET_GUEST_DEBUG instead.
344
345 4.17 KVM_GET_MSRS
346
347 Capability: basic
348 Architectures: x86
349 Type: vcpu ioctl
350 Parameters: struct kvm_msrs (in/out)
351 Returns: 0 on success, -1 on error
352
353 Reads model-specific registers from the vcpu.  Supported msr indices can
354 be obtained using KVM_GET_MSR_INDEX_LIST.
355
356 struct kvm_msrs {
357         __u32 nmsrs; /* number of msrs in entries */
358         __u32 pad;
359
360         struct kvm_msr_entry entries[0];
361 };
362
363 struct kvm_msr_entry {
364         __u32 index;
365         __u32 reserved;
366         __u64 data;
367 };
368
369 Application code should set the 'nmsrs' member (which indicates the
370 size of the entries array) and the 'index' member of each array entry.
371 kvm will fill in the 'data' member.
372
373 4.18 KVM_SET_MSRS
374
375 Capability: basic
376 Architectures: x86
377 Type: vcpu ioctl
378 Parameters: struct kvm_msrs (in)
379 Returns: 0 on success, -1 on error
380
381 Writes model-specific registers to the vcpu.  See KVM_GET_MSRS for the
382 data structures.
383
384 Application code should set the 'nmsrs' member (which indicates the
385 size of the entries array), and the 'index' and 'data' members of each
386 array entry.
387
388 4.19 KVM_SET_CPUID
389
390 Capability: basic
391 Architectures: x86
392 Type: vcpu ioctl
393 Parameters: struct kvm_cpuid (in)
394 Returns: 0 on success, -1 on error
395
396 Defines the vcpu responses to the cpuid instruction.  Applications
397 should use the KVM_SET_CPUID2 ioctl if available.
398
399
400 struct kvm_cpuid_entry {
401         __u32 function;
402         __u32 eax;
403         __u32 ebx;
404         __u32 ecx;
405         __u32 edx;
406         __u32 padding;
407 };
408
409 /* for KVM_SET_CPUID */
410 struct kvm_cpuid {
411         __u32 nent;
412         __u32 padding;
413         struct kvm_cpuid_entry entries[0];
414 };
415
416 4.20 KVM_SET_SIGNAL_MASK
417
418 Capability: basic
419 Architectures: x86
420 Type: vcpu ioctl
421 Parameters: struct kvm_signal_mask (in)
422 Returns: 0 on success, -1 on error
423
424 Defines which signals are blocked during execution of KVM_RUN.  This
425 signal mask temporarily overrides the threads signal mask.  Any
426 unblocked signal received (except SIGKILL and SIGSTOP, which retain
427 their traditional behaviour) will cause KVM_RUN to return with -EINTR.
428
429 Note the signal will only be delivered if not blocked by the original
430 signal mask.
431
432 /* for KVM_SET_SIGNAL_MASK */
433 struct kvm_signal_mask {
434         __u32 len;
435         __u8  sigset[0];
436 };
437
438 4.21 KVM_GET_FPU
439
440 Capability: basic
441 Architectures: x86
442 Type: vcpu ioctl
443 Parameters: struct kvm_fpu (out)
444 Returns: 0 on success, -1 on error
445
446 Reads the floating point state from the vcpu.
447
448 /* for KVM_GET_FPU and KVM_SET_FPU */
449 struct kvm_fpu {
450         __u8  fpr[8][16];
451         __u16 fcw;
452         __u16 fsw;
453         __u8  ftwx;  /* in fxsave format */
454         __u8  pad1;
455         __u16 last_opcode;
456         __u64 last_ip;
457         __u64 last_dp;
458         __u8  xmm[16][16];
459         __u32 mxcsr;
460         __u32 pad2;
461 };
462
463 4.22 KVM_SET_FPU
464
465 Capability: basic
466 Architectures: x86
467 Type: vcpu ioctl
468 Parameters: struct kvm_fpu (in)
469 Returns: 0 on success, -1 on error
470
471 Writes the floating point state to the vcpu.
472
473 /* for KVM_GET_FPU and KVM_SET_FPU */
474 struct kvm_fpu {
475         __u8  fpr[8][16];
476         __u16 fcw;
477         __u16 fsw;
478         __u8  ftwx;  /* in fxsave format */
479         __u8  pad1;
480         __u16 last_opcode;
481         __u64 last_ip;
482         __u64 last_dp;
483         __u8  xmm[16][16];
484         __u32 mxcsr;
485         __u32 pad2;
486 };
487
488 4.23 KVM_CREATE_IRQCHIP
489
490 Capability: KVM_CAP_IRQCHIP
491 Architectures: x86, ia64
492 Type: vm ioctl
493 Parameters: none
494 Returns: 0 on success, -1 on error
495
496 Creates an interrupt controller model in the kernel.  On x86, creates a virtual
497 ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a
498 local APIC.  IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23
499 only go to the IOAPIC.  On ia64, a IOSAPIC is created.
500
501 4.24 KVM_IRQ_LINE
502
503 Capability: KVM_CAP_IRQCHIP
504 Architectures: x86, ia64
505 Type: vm ioctl
506 Parameters: struct kvm_irq_level
507 Returns: 0 on success, -1 on error
508
509 Sets the level of a GSI input to the interrupt controller model in the kernel.
510 Requires that an interrupt controller model has been previously created with
511 KVM_CREATE_IRQCHIP.  Note that edge-triggered interrupts require the level
512 to be set to 1 and then back to 0.
513
514 struct kvm_irq_level {
515         union {
516                 __u32 irq;     /* GSI */
517                 __s32 status;  /* not used for KVM_IRQ_LEVEL */
518         };
519         __u32 level;           /* 0 or 1 */
520 };
521
522 4.25 KVM_GET_IRQCHIP
523
524 Capability: KVM_CAP_IRQCHIP
525 Architectures: x86, ia64
526 Type: vm ioctl
527 Parameters: struct kvm_irqchip (in/out)
528 Returns: 0 on success, -1 on error
529
530 Reads the state of a kernel interrupt controller created with
531 KVM_CREATE_IRQCHIP into a buffer provided by the caller.
532
533 struct kvm_irqchip {
534         __u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
535         __u32 pad;
536         union {
537                 char dummy[512];  /* reserving space */
538                 struct kvm_pic_state pic;
539                 struct kvm_ioapic_state ioapic;
540         } chip;
541 };
542
543 4.26 KVM_SET_IRQCHIP
544
545 Capability: KVM_CAP_IRQCHIP
546 Architectures: x86, ia64
547 Type: vm ioctl
548 Parameters: struct kvm_irqchip (in)
549 Returns: 0 on success, -1 on error
550
551 Sets the state of a kernel interrupt controller created with
552 KVM_CREATE_IRQCHIP from a buffer provided by the caller.
553
554 struct kvm_irqchip {
555         __u32 chip_id;  /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
556         __u32 pad;
557         union {
558                 char dummy[512];  /* reserving space */
559                 struct kvm_pic_state pic;
560                 struct kvm_ioapic_state ioapic;
561         } chip;
562 };
563
564 4.27 KVM_XEN_HVM_CONFIG
565
566 Capability: KVM_CAP_XEN_HVM
567 Architectures: x86
568 Type: vm ioctl
569 Parameters: struct kvm_xen_hvm_config (in)
570 Returns: 0 on success, -1 on error
571
572 Sets the MSR that the Xen HVM guest uses to initialize its hypercall
573 page, and provides the starting address and size of the hypercall
574 blobs in userspace.  When the guest writes the MSR, kvm copies one
575 page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
576 memory.
577
578 struct kvm_xen_hvm_config {
579         __u32 flags;
580         __u32 msr;
581         __u64 blob_addr_32;
582         __u64 blob_addr_64;
583         __u8 blob_size_32;
584         __u8 blob_size_64;
585         __u8 pad2[30];
586 };
587
588 4.27 KVM_GET_CLOCK
589
590 Capability: KVM_CAP_ADJUST_CLOCK
591 Architectures: x86
592 Type: vm ioctl
593 Parameters: struct kvm_clock_data (out)
594 Returns: 0 on success, -1 on error
595
596 Gets the current timestamp of kvmclock as seen by the current guest. In
597 conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
598 such as migration.
599
600 struct kvm_clock_data {
601         __u64 clock;  /* kvmclock current value */
602         __u32 flags;
603         __u32 pad[9];
604 };
605
606 4.28 KVM_SET_CLOCK
607
608 Capability: KVM_CAP_ADJUST_CLOCK
609 Architectures: x86
610 Type: vm ioctl
611 Parameters: struct kvm_clock_data (in)
612 Returns: 0 on success, -1 on error
613
614 Sets the current timestamp of kvmclock to the value specified in its parameter.
615 In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
616 such as migration.
617
618 struct kvm_clock_data {
619         __u64 clock;  /* kvmclock current value */
620         __u32 flags;
621         __u32 pad[9];
622 };
623
624 4.29 KVM_GET_VCPU_EVENTS
625
626 Capability: KVM_CAP_VCPU_EVENTS
627 Extended by: KVM_CAP_INTR_SHADOW
628 Architectures: x86
629 Type: vm ioctl
630 Parameters: struct kvm_vcpu_event (out)
631 Returns: 0 on success, -1 on error
632
633 Gets currently pending exceptions, interrupts, and NMIs as well as related
634 states of the vcpu.
635
636 struct kvm_vcpu_events {
637         struct {
638                 __u8 injected;
639                 __u8 nr;
640                 __u8 has_error_code;
641                 __u8 pad;
642                 __u32 error_code;
643         } exception;
644         struct {
645                 __u8 injected;
646                 __u8 nr;
647                 __u8 soft;
648                 __u8 shadow;
649         } interrupt;
650         struct {
651                 __u8 injected;
652                 __u8 pending;
653                 __u8 masked;
654                 __u8 pad;
655         } nmi;
656         __u32 sipi_vector;
657         __u32 flags;
658 };
659
660 KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
661 interrupt.shadow contains a valid state. Otherwise, this field is undefined.
662
663 4.30 KVM_SET_VCPU_EVENTS
664
665 Capability: KVM_CAP_VCPU_EVENTS
666 Extended by: KVM_CAP_INTR_SHADOW
667 Architectures: x86
668 Type: vm ioctl
669 Parameters: struct kvm_vcpu_event (in)
670 Returns: 0 on success, -1 on error
671
672 Set pending exceptions, interrupts, and NMIs as well as related states of the
673 vcpu.
674
675 See KVM_GET_VCPU_EVENTS for the data structure.
676
677 Fields that may be modified asynchronously by running VCPUs can be excluded
678 from the update. These fields are nmi.pending and sipi_vector. Keep the
679 corresponding bits in the flags field cleared to suppress overwriting the
680 current in-kernel state. The bits are:
681
682 KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
683 KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
684
685 If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
686 the flags field to signal that interrupt.shadow contains a valid state and
687 shall be written into the VCPU.
688
689 4.32 KVM_GET_DEBUGREGS
690
691 Capability: KVM_CAP_DEBUGREGS
692 Architectures: x86
693 Type: vm ioctl
694 Parameters: struct kvm_debugregs (out)
695 Returns: 0 on success, -1 on error
696
697 Reads debug registers from the vcpu.
698
699 struct kvm_debugregs {
700         __u64 db[4];
701         __u64 dr6;
702         __u64 dr7;
703         __u64 flags;
704         __u64 reserved[9];
705 };
706
707 4.33 KVM_SET_DEBUGREGS
708
709 Capability: KVM_CAP_DEBUGREGS
710 Architectures: x86
711 Type: vm ioctl
712 Parameters: struct kvm_debugregs (in)
713 Returns: 0 on success, -1 on error
714
715 Writes debug registers into the vcpu.
716
717 See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
718 yet and must be cleared on entry.
719
720 4.34 KVM_SET_USER_MEMORY_REGION
721
722 Capability: KVM_CAP_USER_MEM
723 Architectures: all
724 Type: vm ioctl
725 Parameters: struct kvm_userspace_memory_region (in)
726 Returns: 0 on success, -1 on error
727
728 struct kvm_userspace_memory_region {
729         __u32 slot;
730         __u32 flags;
731         __u64 guest_phys_addr;
732         __u64 memory_size; /* bytes */
733         __u64 userspace_addr; /* start of the userspace allocated memory */
734 };
735
736 /* for kvm_memory_region::flags */
737 #define KVM_MEM_LOG_DIRTY_PAGES  1UL
738
739 This ioctl allows the user to create or modify a guest physical memory
740 slot.  When changing an existing slot, it may be moved in the guest
741 physical memory space, or its flags may be modified.  It may not be
742 resized.  Slots may not overlap in guest physical address space.
743
744 Memory for the region is taken starting at the address denoted by the
745 field userspace_addr, which must point at user addressable memory for
746 the entire memory slot size.  Any object may back this memory, including
747 anonymous memory, ordinary files, and hugetlbfs.
748
749 It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
750 be identical.  This allows large pages in the guest to be backed by large
751 pages in the host.
752
753 The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which
754 instructs kvm to keep track of writes to memory within the slot.  See
755 the KVM_GET_DIRTY_LOG ioctl.
756
757 When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory
758 region are automatically reflected into the guest.  For example, an mmap()
759 that affects the region will be made visible immediately.  Another example
760 is madvise(MADV_DROP).
761
762 It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
763 The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
764 allocation and is deprecated.
765
766 4.35 KVM_SET_TSS_ADDR
767
768 Capability: KVM_CAP_SET_TSS_ADDR
769 Architectures: x86
770 Type: vm ioctl
771 Parameters: unsigned long tss_address (in)
772 Returns: 0 on success, -1 on error
773
774 This ioctl defines the physical address of a three-page region in the guest
775 physical address space.  The region must be within the first 4GB of the
776 guest physical address space and must not conflict with any memory slot
777 or any mmio address.  The guest may malfunction if it accesses this memory
778 region.
779
780 This ioctl is required on Intel-based hosts.  This is needed on Intel hardware
781 because of a quirk in the virtualization implementation (see the internals
782 documentation when it pops into existence).
783
784 4.36 KVM_ENABLE_CAP
785
786 Capability: KVM_CAP_ENABLE_CAP
787 Architectures: ppc
788 Type: vcpu ioctl
789 Parameters: struct kvm_enable_cap (in)
790 Returns: 0 on success; -1 on error
791
792 +Not all extensions are enabled by default. Using this ioctl the application
793 can enable an extension, making it available to the guest.
794
795 On systems that do not support this ioctl, it always fails. On systems that
796 do support it, it only works for extensions that are supported for enablement.
797
798 To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
799 be used.
800
801 struct kvm_enable_cap {
802        /* in */
803        __u32 cap;
804
805 The capability that is supposed to get enabled.
806
807        __u32 flags;
808
809 A bitfield indicating future enhancements. Has to be 0 for now.
810
811        __u64 args[4];
812
813 Arguments for enabling a feature. If a feature needs initial values to
814 function properly, this is the place to put them.
815
816        __u8  pad[64];
817 };
818
819 4.37 KVM_GET_MP_STATE
820
821 Capability: KVM_CAP_MP_STATE
822 Architectures: x86, ia64
823 Type: vcpu ioctl
824 Parameters: struct kvm_mp_state (out)
825 Returns: 0 on success; -1 on error
826
827 struct kvm_mp_state {
828         __u32 mp_state;
829 };
830
831 Returns the vcpu's current "multiprocessing state" (though also valid on
832 uniprocessor guests).
833
834 Possible values are:
835
836  - KVM_MP_STATE_RUNNABLE:        the vcpu is currently running
837  - KVM_MP_STATE_UNINITIALIZED:   the vcpu is an application processor (AP)
838                                  which has not yet received an INIT signal
839  - KVM_MP_STATE_INIT_RECEIVED:   the vcpu has received an INIT signal, and is
840                                  now ready for a SIPI
841  - KVM_MP_STATE_HALTED:          the vcpu has executed a HLT instruction and
842                                  is waiting for an interrupt
843  - KVM_MP_STATE_SIPI_RECEIVED:   the vcpu has just received a SIPI (vector
844                                  accesible via KVM_GET_VCPU_EVENTS)
845
846 This ioctl is only useful after KVM_CREATE_IRQCHIP.  Without an in-kernel
847 irqchip, the multiprocessing state must be maintained by userspace.
848
849 4.38 KVM_SET_MP_STATE
850
851 Capability: KVM_CAP_MP_STATE
852 Architectures: x86, ia64
853 Type: vcpu ioctl
854 Parameters: struct kvm_mp_state (in)
855 Returns: 0 on success; -1 on error
856
857 Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
858 arguments.
859
860 This ioctl is only useful after KVM_CREATE_IRQCHIP.  Without an in-kernel
861 irqchip, the multiprocessing state must be maintained by userspace.
862
863 4.39 KVM_SET_IDENTITY_MAP_ADDR
864
865 Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
866 Architectures: x86
867 Type: vm ioctl
868 Parameters: unsigned long identity (in)
869 Returns: 0 on success, -1 on error
870
871 This ioctl defines the physical address of a one-page region in the guest
872 physical address space.  The region must be within the first 4GB of the
873 guest physical address space and must not conflict with any memory slot
874 or any mmio address.  The guest may malfunction if it accesses this memory
875 region.
876
877 This ioctl is required on Intel-based hosts.  This is needed on Intel hardware
878 because of a quirk in the virtualization implementation (see the internals
879 documentation when it pops into existence).
880
881 4.40 KVM_SET_BOOT_CPU_ID
882
883 Capability: KVM_CAP_SET_BOOT_CPU_ID
884 Architectures: x86, ia64
885 Type: vm ioctl
886 Parameters: unsigned long vcpu_id
887 Returns: 0 on success, -1 on error
888
889 Define which vcpu is the Bootstrap Processor (BSP).  Values are the same
890 as the vcpu id in KVM_CREATE_VCPU.  If this ioctl is not called, the default
891 is vcpu 0.
892
893 4.41 KVM_GET_XSAVE
894
895 Capability: KVM_CAP_XSAVE
896 Architectures: x86
897 Type: vcpu ioctl
898 Parameters: struct kvm_xsave (out)
899 Returns: 0 on success, -1 on error
900
901 struct kvm_xsave {
902         __u32 region[1024];
903 };
904
905 This ioctl would copy current vcpu's xsave struct to the userspace.
906
907 4.42 KVM_SET_XSAVE
908
909 Capability: KVM_CAP_XSAVE
910 Architectures: x86
911 Type: vcpu ioctl
912 Parameters: struct kvm_xsave (in)
913 Returns: 0 on success, -1 on error
914
915 struct kvm_xsave {
916         __u32 region[1024];
917 };
918
919 This ioctl would copy userspace's xsave struct to the kernel.
920
921 4.43 KVM_GET_XCRS
922
923 Capability: KVM_CAP_XCRS
924 Architectures: x86
925 Type: vcpu ioctl
926 Parameters: struct kvm_xcrs (out)
927 Returns: 0 on success, -1 on error
928
929 struct kvm_xcr {
930         __u32 xcr;
931         __u32 reserved;
932         __u64 value;
933 };
934
935 struct kvm_xcrs {
936         __u32 nr_xcrs;
937         __u32 flags;
938         struct kvm_xcr xcrs[KVM_MAX_XCRS];
939         __u64 padding[16];
940 };
941
942 This ioctl would copy current vcpu's xcrs to the userspace.
943
944 4.44 KVM_SET_XCRS
945
946 Capability: KVM_CAP_XCRS
947 Architectures: x86
948 Type: vcpu ioctl
949 Parameters: struct kvm_xcrs (in)
950 Returns: 0 on success, -1 on error
951
952 struct kvm_xcr {
953         __u32 xcr;
954         __u32 reserved;
955         __u64 value;
956 };
957
958 struct kvm_xcrs {
959         __u32 nr_xcrs;
960         __u32 flags;
961         struct kvm_xcr xcrs[KVM_MAX_XCRS];
962         __u64 padding[16];
963 };
964
965 This ioctl would set vcpu's xcr to the value userspace specified.
966
967 5. The kvm_run structure
968
969 Application code obtains a pointer to the kvm_run structure by
970 mmap()ing a vcpu fd.  From that point, application code can control
971 execution by changing fields in kvm_run prior to calling the KVM_RUN
972 ioctl, and obtain information about the reason KVM_RUN returned by
973 looking up structure members.
974
975 struct kvm_run {
976         /* in */
977         __u8 request_interrupt_window;
978
979 Request that KVM_RUN return when it becomes possible to inject external
980 interrupts into the guest.  Useful in conjunction with KVM_INTERRUPT.
981
982         __u8 padding1[7];
983
984         /* out */
985         __u32 exit_reason;
986
987 When KVM_RUN has returned successfully (return value 0), this informs
988 application code why KVM_RUN has returned.  Allowable values for this
989 field are detailed below.
990
991         __u8 ready_for_interrupt_injection;
992
993 If request_interrupt_window has been specified, this field indicates
994 an interrupt can be injected now with KVM_INTERRUPT.
995
996         __u8 if_flag;
997
998 The value of the current interrupt flag.  Only valid if in-kernel
999 local APIC is not used.
1000
1001         __u8 padding2[2];
1002
1003         /* in (pre_kvm_run), out (post_kvm_run) */
1004         __u64 cr8;
1005
1006 The value of the cr8 register.  Only valid if in-kernel local APIC is
1007 not used.  Both input and output.
1008
1009         __u64 apic_base;
1010
1011 The value of the APIC BASE msr.  Only valid if in-kernel local
1012 APIC is not used.  Both input and output.
1013
1014         union {
1015                 /* KVM_EXIT_UNKNOWN */
1016                 struct {
1017                         __u64 hardware_exit_reason;
1018                 } hw;
1019
1020 If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
1021 reasons.  Further architecture-specific information is available in
1022 hardware_exit_reason.
1023
1024                 /* KVM_EXIT_FAIL_ENTRY */
1025                 struct {
1026                         __u64 hardware_entry_failure_reason;
1027                 } fail_entry;
1028
1029 If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
1030 to unknown reasons.  Further architecture-specific information is
1031 available in hardware_entry_failure_reason.
1032
1033                 /* KVM_EXIT_EXCEPTION */
1034                 struct {
1035                         __u32 exception;
1036                         __u32 error_code;
1037                 } ex;
1038
1039 Unused.
1040
1041                 /* KVM_EXIT_IO */
1042                 struct {
1043 #define KVM_EXIT_IO_IN  0
1044 #define KVM_EXIT_IO_OUT 1
1045                         __u8 direction;
1046                         __u8 size; /* bytes */
1047                         __u16 port;
1048                         __u32 count;
1049                         __u64 data_offset; /* relative to kvm_run start */
1050                 } io;
1051
1052 If exit_reason is KVM_EXIT_IO, then the vcpu has
1053 executed a port I/O instruction which could not be satisfied by kvm.
1054 data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
1055 where kvm expects application code to place the data for the next
1056 KVM_RUN invocation (KVM_EXIT_IO_IN).  Data format is a packed array.
1057
1058                 struct {
1059                         struct kvm_debug_exit_arch arch;
1060                 } debug;
1061
1062 Unused.
1063
1064                 /* KVM_EXIT_MMIO */
1065                 struct {
1066                         __u64 phys_addr;
1067                         __u8  data[8];
1068                         __u32 len;
1069                         __u8  is_write;
1070                 } mmio;
1071
1072 If exit_reason is KVM_EXIT_MMIO, then the vcpu has
1073 executed a memory-mapped I/O instruction which could not be satisfied
1074 by kvm.  The 'data' member contains the written data if 'is_write' is
1075 true, and should be filled by application code otherwise.
1076
1077 NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO and KVM_EXIT_OSI, the corresponding
1078 operations are complete (and guest state is consistent) only after userspace
1079 has re-entered the kernel with KVM_RUN.  The kernel side will first finish
1080 incomplete operations and then check for pending signals.  Userspace
1081 can re-enter the guest with an unmasked signal pending to complete
1082 pending operations.
1083
1084                 /* KVM_EXIT_HYPERCALL */
1085                 struct {
1086                         __u64 nr;
1087                         __u64 args[6];
1088                         __u64 ret;
1089                         __u32 longmode;
1090                         __u32 pad;
1091                 } hypercall;
1092
1093 Unused.  This was once used for 'hypercall to userspace'.  To implement
1094 such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
1095 Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
1096
1097                 /* KVM_EXIT_TPR_ACCESS */
1098                 struct {
1099                         __u64 rip;
1100                         __u32 is_write;
1101                         __u32 pad;
1102                 } tpr_access;
1103
1104 To be documented (KVM_TPR_ACCESS_REPORTING).
1105
1106                 /* KVM_EXIT_S390_SIEIC */
1107                 struct {
1108                         __u8 icptcode;
1109                         __u64 mask; /* psw upper half */
1110                         __u64 addr; /* psw lower half */
1111                         __u16 ipa;
1112                         __u32 ipb;
1113                 } s390_sieic;
1114
1115 s390 specific.
1116
1117                 /* KVM_EXIT_S390_RESET */
1118 #define KVM_S390_RESET_POR       1
1119 #define KVM_S390_RESET_CLEAR     2
1120 #define KVM_S390_RESET_SUBSYSTEM 4
1121 #define KVM_S390_RESET_CPU_INIT  8
1122 #define KVM_S390_RESET_IPL       16
1123                 __u64 s390_reset_flags;
1124
1125 s390 specific.
1126
1127                 /* KVM_EXIT_DCR */
1128                 struct {
1129                         __u32 dcrn;
1130                         __u32 data;
1131                         __u8  is_write;
1132                 } dcr;
1133
1134 powerpc specific.
1135
1136                 /* KVM_EXIT_OSI */
1137                 struct {
1138                         __u64 gprs[32];
1139                 } osi;
1140
1141 MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
1142 hypercalls and exit with this exit struct that contains all the guest gprs.
1143
1144 If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
1145 Userspace can now handle the hypercall and when it's done modify the gprs as
1146 necessary. Upon guest entry all guest GPRs will then be replaced by the values
1147 in this struct.
1148
1149                 /* Fix the size of the union. */
1150                 char padding[256];
1151         };
1152 };