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