blob: 4237c27ea61227655467758fb035aa90cdeb1e4d [file] [log] [blame]
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001The Definitive KVM (Kernel-based Virtual Machine) API Documentation
2===================================================================
3
41. General description
Jan Kiszka414fa982012-04-24 16:40:15 +02005----------------------
Avi Kivity9c1b96e2009-06-09 12:37:58 +03006
7The kvm API is a set of ioctls that are issued to control various aspects
8of a virtual machine. The ioctls belong to three classes
9
10 - System ioctls: These query and set global attributes which affect the
11 whole kvm subsystem. In addition a system ioctl is used to create
12 virtual machines
13
14 - VM ioctls: These query and set attributes that affect an entire virtual
15 machine, for example memory layout. In addition a VM ioctl is used to
16 create virtual cpus (vcpus).
17
18 Only run VM ioctls from the same process (address space) that was used
19 to create the VM.
20
21 - vcpu ioctls: These query and set attributes that control the operation
22 of a single virtual cpu.
23
24 Only run vcpu ioctls from the same thread that was used to create the
25 vcpu.
26
Jan Kiszka414fa982012-04-24 16:40:15 +020027
Wu Fengguang2044892d2009-12-24 09:04:16 +0800282. File descriptors
Jan Kiszka414fa982012-04-24 16:40:15 +020029-------------------
Avi Kivity9c1b96e2009-06-09 12:37:58 +030030
31The kvm API is centered around file descriptors. An initial
32open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
33can be used to issue system ioctls. A KVM_CREATE_VM ioctl on this
Wu Fengguang2044892d2009-12-24 09:04:16 +080034handle will create a VM file descriptor which can be used to issue VM
Avi Kivity9c1b96e2009-06-09 12:37:58 +030035ioctls. A KVM_CREATE_VCPU ioctl on a VM fd will create a virtual cpu
36and return a file descriptor pointing to it. Finally, ioctls on a vcpu
37fd can be used to control the vcpu, including the important task of
38actually running guest code.
39
40In general file descriptors can be migrated among processes by means
41of fork() and the SCM_RIGHTS facility of unix domain socket. These
42kinds of tricks are explicitly not supported by kvm. While they will
43not cause harm to the host, their actual behavior is not guaranteed by
44the API. The only supported use is one virtual machine per process,
45and one vcpu per thread.
46
Jan Kiszka414fa982012-04-24 16:40:15 +020047
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300483. Extensions
Jan Kiszka414fa982012-04-24 16:40:15 +020049-------------
Avi Kivity9c1b96e2009-06-09 12:37:58 +030050
51As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
52incompatible change are allowed. However, there is an extension
53facility that allows backward-compatible extensions to the API to be
54queried and used.
55
56The extension mechanism is not based on on the Linux version number.
57Instead, kvm defines extension identifiers and a facility to query
58whether a particular extension identifier is available. If it is, a
59set of ioctls is available for application use.
60
Jan Kiszka414fa982012-04-24 16:40:15 +020061
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300624. API description
Jan Kiszka414fa982012-04-24 16:40:15 +020063------------------
Avi Kivity9c1b96e2009-06-09 12:37:58 +030064
65This section describes ioctls that can be used to control kvm guests.
66For each ioctl, the following information is provided along with a
67description:
68
69 Capability: which KVM extension provides this ioctl. Can be 'basic',
70 which means that is will be provided by any kernel that supports
71 API version 12 (see section 4.1), or a KVM_CAP_xyz constant, which
72 means availability needs to be checked with KVM_CHECK_EXTENSION
73 (see section 4.4).
74
75 Architectures: which instruction set architectures provide this ioctl.
76 x86 includes both i386 and x86_64.
77
78 Type: system, vm, or vcpu.
79
80 Parameters: what parameters are accepted by the ioctl.
81
82 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
83 are not detailed, but errors with specific meanings are.
84
Jan Kiszka414fa982012-04-24 16:40:15 +020085
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300864.1 KVM_GET_API_VERSION
87
88Capability: basic
89Architectures: all
90Type: system ioctl
91Parameters: none
92Returns: the constant KVM_API_VERSION (=12)
93
94This identifies the API version as the stable kvm API. It is not
95expected that this number will change. However, Linux 2.6.20 and
962.6.21 report earlier versions; these are not documented and not
97supported. Applications should refuse to run if KVM_GET_API_VERSION
98returns a value other than 12. If this check passes, all ioctls
99described as 'basic' will be available.
100
Jan Kiszka414fa982012-04-24 16:40:15 +0200101
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001024.2 KVM_CREATE_VM
103
104Capability: basic
105Architectures: all
106Type: system ioctl
Carsten Ottee08b9632012-01-04 10:25:20 +0100107Parameters: machine type identifier (KVM_VM_*)
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300108Returns: a VM fd that can be used to control the new virtual machine.
109
110The new VM has no virtual cpus and no memory. An mmap() of a VM fd
111will access the virtual machine's physical address space; offset zero
112corresponds to guest physical address zero. Use of mmap() on a VM fd
113is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is
114available.
Carsten Ottee08b9632012-01-04 10:25:20 +0100115You most certainly want to use 0 as machine type.
116
117In order to create user controlled virtual machines on S390, check
118KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as
119privileged user (CAP_SYS_ADMIN).
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300120
Jan Kiszka414fa982012-04-24 16:40:15 +0200121
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001224.3 KVM_GET_MSR_INDEX_LIST
123
124Capability: basic
125Architectures: x86
126Type: system
127Parameters: struct kvm_msr_list (in/out)
128Returns: 0 on success; -1 on error
129Errors:
130 E2BIG: the msr index list is to be to fit in the array specified by
131 the user.
132
133struct kvm_msr_list {
134 __u32 nmsrs; /* number of msrs in entries */
135 __u32 indices[0];
136};
137
138This ioctl returns the guest msrs that are supported. The list varies
139by kvm version and host processor, but does not change otherwise. The
140user fills in the size of the indices array in nmsrs, and in return
141kvm adjusts nmsrs to reflect the actual number of msrs and fills in
142the indices array with their numbers.
143
Avi Kivity2e2602c2010-07-07 14:09:39 +0300144Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
145not returned in the MSR list, as different vcpus can have a different number
146of banks, as set via the KVM_X86_SETUP_MCE ioctl.
147
Jan Kiszka414fa982012-04-24 16:40:15 +0200148
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001494.4 KVM_CHECK_EXTENSION
150
151Capability: basic
152Architectures: all
153Type: system ioctl
154Parameters: extension identifier (KVM_CAP_*)
155Returns: 0 if unsupported; 1 (or some other positive integer) if supported
156
157The API allows the application to query about extensions to the core
158kvm API. Userspace passes an extension identifier (an integer) and
159receives an integer that describes the extension availability.
160Generally 0 means no and 1 means yes, but some extensions may report
161additional information in the integer return value.
162
Jan Kiszka414fa982012-04-24 16:40:15 +0200163
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001644.5 KVM_GET_VCPU_MMAP_SIZE
165
166Capability: basic
167Architectures: all
168Type: system ioctl
169Parameters: none
170Returns: size of vcpu mmap area, in bytes
171
172The KVM_RUN ioctl (cf.) communicates with userspace via a shared
173memory region. This ioctl returns the size of that region. See the
174KVM_RUN documentation for details.
175
Jan Kiszka414fa982012-04-24 16:40:15 +0200176
Avi Kivity9c1b96e2009-06-09 12:37:58 +03001774.6 KVM_SET_MEMORY_REGION
178
179Capability: basic
180Architectures: all
181Type: vm ioctl
182Parameters: struct kvm_memory_region (in)
183Returns: 0 on success, -1 on error
184
Avi Kivityb74a07b2010-06-21 11:48:05 +0300185This ioctl is obsolete and has been removed.
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300186
Jan Kiszka414fa982012-04-24 16:40:15 +0200187
Paul Bolle68ba6972011-02-15 00:05:59 +01001884.7 KVM_CREATE_VCPU
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300189
190Capability: basic
191Architectures: all
192Type: vm ioctl
193Parameters: vcpu id (apic id on x86)
194Returns: vcpu fd on success, -1 on error
195
196This API adds a vcpu to a virtual machine. The vcpu id is a small integer
Sasha Levin8c3ba332011-07-18 17:17:15 +0300197in the range [0, max_vcpus).
198
199The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of
200the KVM_CHECK_EXTENSION ioctl() at run-time.
201The maximum possible value for max_vcpus can be retrieved using the
202KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.
203
Pekka Enberg76d25402011-05-09 22:48:54 +0300204If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
205cpus max.
Sasha Levin8c3ba332011-07-18 17:17:15 +0300206If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is
207same as the value returned from KVM_CAP_NR_VCPUS.
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300208
Paul Mackerras371fefd2011-06-29 00:23:08 +0000209On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
210threads in one or more virtual CPU cores. (This is because the
211hardware requires all the hardware threads in a CPU core to be in the
212same partition.) The KVM_CAP_PPC_SMT capability indicates the number
213of vcpus per virtual core (vcore). The vcore id is obtained by
214dividing the vcpu id by the number of vcpus per vcore. The vcpus in a
215given vcore will always be in the same physical core as each other
216(though that might be a different physical core from time to time).
217Userspace can control the threading (SMT) mode of the guest by its
218allocation of vcpu ids. For example, if userspace wants
219single-threaded guest vcpus, it should make all vcpu ids be a multiple
220of the number of vcpus per vcore.
221
Avi Kivity36442682011-08-29 16:27:08 +0300222On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
223threads in one or more virtual CPU cores. (This is because the
224hardware requires all the hardware threads in a CPU core to be in the
225same partition.) The KVM_CAP_PPC_SMT capability indicates the number
226of vcpus per virtual core (vcore). The vcore id is obtained by
227dividing the vcpu id by the number of vcpus per vcore. The vcpus in a
228given vcore will always be in the same physical core as each other
229(though that might be a different physical core from time to time).
230Userspace can control the threading (SMT) mode of the guest by its
231allocation of vcpu ids. For example, if userspace wants
232single-threaded guest vcpus, it should make all vcpu ids be a multiple
233of the number of vcpus per vcore.
234
Carsten Otte5b1c1492012-01-04 10:25:23 +0100235For virtual cpus that have been created with S390 user controlled virtual
236machines, the resulting vcpu fd can be memory mapped at page offset
237KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtual
238cpu's hardware control block.
239
Jan Kiszka414fa982012-04-24 16:40:15 +0200240
Paul Bolle68ba6972011-02-15 00:05:59 +01002414.8 KVM_GET_DIRTY_LOG (vm ioctl)
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300242
243Capability: basic
244Architectures: x86
245Type: vm ioctl
246Parameters: struct kvm_dirty_log (in/out)
247Returns: 0 on success, -1 on error
248
249/* for KVM_GET_DIRTY_LOG */
250struct kvm_dirty_log {
251 __u32 slot;
252 __u32 padding;
253 union {
254 void __user *dirty_bitmap; /* one bit per page */
255 __u64 padding;
256 };
257};
258
259Given a memory slot, return a bitmap containing any pages dirtied
260since the last call to this ioctl. Bit 0 is the first page in the
261memory slot. Ensure the entire structure is cleared to avoid padding
262issues.
263
Jan Kiszka414fa982012-04-24 16:40:15 +0200264
Paul Bolle68ba6972011-02-15 00:05:59 +01002654.9 KVM_SET_MEMORY_ALIAS
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300266
267Capability: basic
268Architectures: x86
269Type: vm ioctl
270Parameters: struct kvm_memory_alias (in)
271Returns: 0 (success), -1 (error)
272
Avi Kivitya1f4d3952010-06-21 11:44:20 +0300273This ioctl is obsolete and has been removed.
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300274
Jan Kiszka414fa982012-04-24 16:40:15 +0200275
Paul Bolle68ba6972011-02-15 00:05:59 +01002764.10 KVM_RUN
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300277
278Capability: basic
279Architectures: all
280Type: vcpu ioctl
281Parameters: none
282Returns: 0 on success, -1 on error
283Errors:
284 EINTR: an unmasked signal is pending
285
286This ioctl is used to run a guest virtual cpu. While there are no
287explicit parameters, there is an implicit parameter block that can be
288obtained by mmap()ing the vcpu fd at offset 0, with the size given by
289KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct
290kvm_run' (see below).
291
Jan Kiszka414fa982012-04-24 16:40:15 +0200292
Paul Bolle68ba6972011-02-15 00:05:59 +01002934.11 KVM_GET_REGS
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300294
295Capability: basic
Christoffer Dall749cf76c2013-01-20 18:28:06 -0500296Architectures: all except ARM
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300297Type: vcpu ioctl
298Parameters: struct kvm_regs (out)
299Returns: 0 on success, -1 on error
300
301Reads the general purpose registers from the vcpu.
302
303/* x86 */
304struct kvm_regs {
305 /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
306 __u64 rax, rbx, rcx, rdx;
307 __u64 rsi, rdi, rsp, rbp;
308 __u64 r8, r9, r10, r11;
309 __u64 r12, r13, r14, r15;
310 __u64 rip, rflags;
311};
312
Jan Kiszka414fa982012-04-24 16:40:15 +0200313
Paul Bolle68ba6972011-02-15 00:05:59 +01003144.12 KVM_SET_REGS
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300315
316Capability: basic
Christoffer Dall749cf76c2013-01-20 18:28:06 -0500317Architectures: all except ARM
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300318Type: vcpu ioctl
319Parameters: struct kvm_regs (in)
320Returns: 0 on success, -1 on error
321
322Writes the general purpose registers into the vcpu.
323
324See KVM_GET_REGS for the data structure.
325
Jan Kiszka414fa982012-04-24 16:40:15 +0200326
Paul Bolle68ba6972011-02-15 00:05:59 +01003274.13 KVM_GET_SREGS
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300328
329Capability: basic
Scott Wood5ce941e2011-04-27 17:24:21 -0500330Architectures: x86, ppc
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300331Type: vcpu ioctl
332Parameters: struct kvm_sregs (out)
333Returns: 0 on success, -1 on error
334
335Reads special registers from the vcpu.
336
337/* x86 */
338struct kvm_sregs {
339 struct kvm_segment cs, ds, es, fs, gs, ss;
340 struct kvm_segment tr, ldt;
341 struct kvm_dtable gdt, idt;
342 __u64 cr0, cr2, cr3, cr4, cr8;
343 __u64 efer;
344 __u64 apic_base;
345 __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
346};
347
Scott Wood5ce941e2011-04-27 17:24:21 -0500348/* ppc -- see arch/powerpc/include/asm/kvm.h */
349
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300350interrupt_bitmap is a bitmap of pending external interrupts. At most
351one bit may be set. This interrupt has been acknowledged by the APIC
352but not yet injected into the cpu core.
353
Jan Kiszka414fa982012-04-24 16:40:15 +0200354
Paul Bolle68ba6972011-02-15 00:05:59 +01003554.14 KVM_SET_SREGS
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300356
357Capability: basic
Scott Wood5ce941e2011-04-27 17:24:21 -0500358Architectures: x86, ppc
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300359Type: vcpu ioctl
360Parameters: struct kvm_sregs (in)
361Returns: 0 on success, -1 on error
362
363Writes special registers into the vcpu. See KVM_GET_SREGS for the
364data structures.
365
Jan Kiszka414fa982012-04-24 16:40:15 +0200366
Paul Bolle68ba6972011-02-15 00:05:59 +01003674.15 KVM_TRANSLATE
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300368
369Capability: basic
370Architectures: x86
371Type: vcpu ioctl
372Parameters: struct kvm_translation (in/out)
373Returns: 0 on success, -1 on error
374
375Translates a virtual address according to the vcpu's current address
376translation mode.
377
378struct kvm_translation {
379 /* in */
380 __u64 linear_address;
381
382 /* out */
383 __u64 physical_address;
384 __u8 valid;
385 __u8 writeable;
386 __u8 usermode;
387 __u8 pad[5];
388};
389
Jan Kiszka414fa982012-04-24 16:40:15 +0200390
Paul Bolle68ba6972011-02-15 00:05:59 +01003914.16 KVM_INTERRUPT
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300392
393Capability: basic
Alexander Graf6f7a2bd2010-08-31 02:03:32 +0200394Architectures: x86, ppc
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300395Type: vcpu ioctl
396Parameters: struct kvm_interrupt (in)
397Returns: 0 on success, -1 on error
398
399Queues a hardware interrupt vector to be injected. This is only
Alexander Graf6f7a2bd2010-08-31 02:03:32 +0200400useful if in-kernel local APIC or equivalent is not used.
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300401
402/* for KVM_INTERRUPT */
403struct kvm_interrupt {
404 /* in */
405 __u32 irq;
406};
407
Alexander Graf6f7a2bd2010-08-31 02:03:32 +0200408X86:
409
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300410Note 'irq' is an interrupt vector, not an interrupt pin or line.
411
Alexander Graf6f7a2bd2010-08-31 02:03:32 +0200412PPC:
413
414Queues an external interrupt to be injected. This ioctl is overleaded
415with 3 different irq values:
416
417a) KVM_INTERRUPT_SET
418
419 This injects an edge type external interrupt into the guest once it's ready
420 to receive interrupts. When injected, the interrupt is done.
421
422b) KVM_INTERRUPT_UNSET
423
424 This unsets any pending interrupt.
425
426 Only available with KVM_CAP_PPC_UNSET_IRQ.
427
428c) KVM_INTERRUPT_SET_LEVEL
429
430 This injects a level type external interrupt into the guest context. The
431 interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
432 is triggered.
433
434 Only available with KVM_CAP_PPC_IRQ_LEVEL.
435
436Note that any value for 'irq' other than the ones stated above is invalid
437and incurs unexpected behavior.
438
Jan Kiszka414fa982012-04-24 16:40:15 +0200439
Paul Bolle68ba6972011-02-15 00:05:59 +01004404.17 KVM_DEBUG_GUEST
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300441
442Capability: basic
443Architectures: none
444Type: vcpu ioctl
445Parameters: none)
446Returns: -1 on error
447
448Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.
449
Jan Kiszka414fa982012-04-24 16:40:15 +0200450
Paul Bolle68ba6972011-02-15 00:05:59 +01004514.18 KVM_GET_MSRS
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300452
453Capability: basic
454Architectures: x86
455Type: vcpu ioctl
456Parameters: struct kvm_msrs (in/out)
457Returns: 0 on success, -1 on error
458
459Reads model-specific registers from the vcpu. Supported msr indices can
460be obtained using KVM_GET_MSR_INDEX_LIST.
461
462struct kvm_msrs {
463 __u32 nmsrs; /* number of msrs in entries */
464 __u32 pad;
465
466 struct kvm_msr_entry entries[0];
467};
468
469struct kvm_msr_entry {
470 __u32 index;
471 __u32 reserved;
472 __u64 data;
473};
474
475Application code should set the 'nmsrs' member (which indicates the
476size of the entries array) and the 'index' member of each array entry.
477kvm will fill in the 'data' member.
478
Jan Kiszka414fa982012-04-24 16:40:15 +0200479
Paul Bolle68ba6972011-02-15 00:05:59 +01004804.19 KVM_SET_MSRS
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300481
482Capability: basic
483Architectures: x86
484Type: vcpu ioctl
485Parameters: struct kvm_msrs (in)
486Returns: 0 on success, -1 on error
487
488Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
489data structures.
490
491Application code should set the 'nmsrs' member (which indicates the
492size of the entries array), and the 'index' and 'data' members of each
493array entry.
494
Jan Kiszka414fa982012-04-24 16:40:15 +0200495
Paul Bolle68ba6972011-02-15 00:05:59 +01004964.20 KVM_SET_CPUID
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300497
498Capability: basic
499Architectures: x86
500Type: vcpu ioctl
501Parameters: struct kvm_cpuid (in)
502Returns: 0 on success, -1 on error
503
504Defines the vcpu responses to the cpuid instruction. Applications
505should use the KVM_SET_CPUID2 ioctl if available.
506
507
508struct kvm_cpuid_entry {
509 __u32 function;
510 __u32 eax;
511 __u32 ebx;
512 __u32 ecx;
513 __u32 edx;
514 __u32 padding;
515};
516
517/* for KVM_SET_CPUID */
518struct kvm_cpuid {
519 __u32 nent;
520 __u32 padding;
521 struct kvm_cpuid_entry entries[0];
522};
523
Jan Kiszka414fa982012-04-24 16:40:15 +0200524
Paul Bolle68ba6972011-02-15 00:05:59 +01005254.21 KVM_SET_SIGNAL_MASK
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300526
527Capability: basic
528Architectures: x86
529Type: vcpu ioctl
530Parameters: struct kvm_signal_mask (in)
531Returns: 0 on success, -1 on error
532
533Defines which signals are blocked during execution of KVM_RUN. This
534signal mask temporarily overrides the threads signal mask. Any
535unblocked signal received (except SIGKILL and SIGSTOP, which retain
536their traditional behaviour) will cause KVM_RUN to return with -EINTR.
537
538Note the signal will only be delivered if not blocked by the original
539signal mask.
540
541/* for KVM_SET_SIGNAL_MASK */
542struct kvm_signal_mask {
543 __u32 len;
544 __u8 sigset[0];
545};
546
Jan Kiszka414fa982012-04-24 16:40:15 +0200547
Paul Bolle68ba6972011-02-15 00:05:59 +01005484.22 KVM_GET_FPU
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300549
550Capability: basic
551Architectures: x86
552Type: vcpu ioctl
553Parameters: struct kvm_fpu (out)
554Returns: 0 on success, -1 on error
555
556Reads the floating point state from the vcpu.
557
558/* for KVM_GET_FPU and KVM_SET_FPU */
559struct kvm_fpu {
560 __u8 fpr[8][16];
561 __u16 fcw;
562 __u16 fsw;
563 __u8 ftwx; /* in fxsave format */
564 __u8 pad1;
565 __u16 last_opcode;
566 __u64 last_ip;
567 __u64 last_dp;
568 __u8 xmm[16][16];
569 __u32 mxcsr;
570 __u32 pad2;
571};
572
Jan Kiszka414fa982012-04-24 16:40:15 +0200573
Paul Bolle68ba6972011-02-15 00:05:59 +01005744.23 KVM_SET_FPU
Avi Kivity9c1b96e2009-06-09 12:37:58 +0300575
576Capability: basic
577Architectures: x86
578Type: vcpu ioctl
579Parameters: struct kvm_fpu (in)
580Returns: 0 on success, -1 on error
581
582Writes the floating point state to the vcpu.
583
584/* for KVM_GET_FPU and KVM_SET_FPU */
585struct kvm_fpu {
586 __u8 fpr[8][16];
587 __u16 fcw;
588 __u16 fsw;
589 __u8 ftwx; /* in fxsave format */
590 __u8 pad1;
591 __u16 last_opcode;
592 __u64 last_ip;
593 __u64 last_dp;
594 __u8 xmm[16][16];
595 __u32 mxcsr;
596 __u32 pad2;
597};
598
Jan Kiszka414fa982012-04-24 16:40:15 +0200599
Paul Bolle68ba6972011-02-15 00:05:59 +01006004.24 KVM_CREATE_IRQCHIP
Avi Kivity5dadbfd2009-08-23 17:08:04 +0300601
602Capability: KVM_CAP_IRQCHIP
Christoffer Dall749cf76c2013-01-20 18:28:06 -0500603Architectures: x86, ia64, ARM
Avi Kivity5dadbfd2009-08-23 17:08:04 +0300604Type: vm ioctl
605Parameters: none
606Returns: 0 on success, -1 on error
607
608Creates an interrupt controller model in the kernel. On x86, creates a virtual
609ioapic, a virtual PIC (two PICs, nested), and sets up future vcpus to have a
610local APIC. IRQ routing for GSIs 0-15 is set to both PIC and IOAPIC; GSI 16-23
Christoffer Dall749cf76c2013-01-20 18:28:06 -0500611only go to the IOAPIC. On ia64, a IOSAPIC is created. On ARM, a GIC is
612created.
Avi Kivity5dadbfd2009-08-23 17:08:04 +0300613
Jan Kiszka414fa982012-04-24 16:40:15 +0200614
Paul Bolle68ba6972011-02-15 00:05:59 +01006154.25 KVM_IRQ_LINE
Avi Kivity5dadbfd2009-08-23 17:08:04 +0300616
617Capability: KVM_CAP_IRQCHIP
618Architectures: x86, ia64
619Type: vm ioctl
620Parameters: struct kvm_irq_level
621Returns: 0 on success, -1 on error
622
623Sets the level of a GSI input to the interrupt controller model in the kernel.
624Requires that an interrupt controller model has been previously created with
625KVM_CREATE_IRQCHIP. Note that edge-triggered interrupts require the level
626to be set to 1 and then back to 0.
627
628struct kvm_irq_level {
629 union {
630 __u32 irq; /* GSI */
631 __s32 status; /* not used for KVM_IRQ_LEVEL */
632 };
633 __u32 level; /* 0 or 1 */
634};
635
Jan Kiszka414fa982012-04-24 16:40:15 +0200636
Paul Bolle68ba6972011-02-15 00:05:59 +01006374.26 KVM_GET_IRQCHIP
Avi Kivity5dadbfd2009-08-23 17:08:04 +0300638
639Capability: KVM_CAP_IRQCHIP
640Architectures: x86, ia64
641Type: vm ioctl
642Parameters: struct kvm_irqchip (in/out)
643Returns: 0 on success, -1 on error
644
645Reads the state of a kernel interrupt controller created with
646KVM_CREATE_IRQCHIP into a buffer provided by the caller.
647
648struct kvm_irqchip {
649 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
650 __u32 pad;
651 union {
652 char dummy[512]; /* reserving space */
653 struct kvm_pic_state pic;
654 struct kvm_ioapic_state ioapic;
655 } chip;
656};
657
Jan Kiszka414fa982012-04-24 16:40:15 +0200658
Paul Bolle68ba6972011-02-15 00:05:59 +01006594.27 KVM_SET_IRQCHIP
Avi Kivity5dadbfd2009-08-23 17:08:04 +0300660
661Capability: KVM_CAP_IRQCHIP
662Architectures: x86, ia64
663Type: vm ioctl
664Parameters: struct kvm_irqchip (in)
665Returns: 0 on success, -1 on error
666
667Sets the state of a kernel interrupt controller created with
668KVM_CREATE_IRQCHIP from a buffer provided by the caller.
669
670struct kvm_irqchip {
671 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
672 __u32 pad;
673 union {
674 char dummy[512]; /* reserving space */
675 struct kvm_pic_state pic;
676 struct kvm_ioapic_state ioapic;
677 } chip;
678};
679
Jan Kiszka414fa982012-04-24 16:40:15 +0200680
Paul Bolle68ba6972011-02-15 00:05:59 +01006814.28 KVM_XEN_HVM_CONFIG
Ed Swierkffde22a2009-10-15 15:21:43 -0700682
683Capability: KVM_CAP_XEN_HVM
684Architectures: x86
685Type: vm ioctl
686Parameters: struct kvm_xen_hvm_config (in)
687Returns: 0 on success, -1 on error
688
689Sets the MSR that the Xen HVM guest uses to initialize its hypercall
690page, and provides the starting address and size of the hypercall
691blobs in userspace. When the guest writes the MSR, kvm copies one
692page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
693memory.
694
695struct kvm_xen_hvm_config {
696 __u32 flags;
697 __u32 msr;
698 __u64 blob_addr_32;
699 __u64 blob_addr_64;
700 __u8 blob_size_32;
701 __u8 blob_size_64;
702 __u8 pad2[30];
703};
704
Jan Kiszka414fa982012-04-24 16:40:15 +0200705
Paul Bolle68ba6972011-02-15 00:05:59 +01007064.29 KVM_GET_CLOCK
Glauber Costaafbcf7a2009-10-16 15:28:36 -0400707
708Capability: KVM_CAP_ADJUST_CLOCK
709Architectures: x86
710Type: vm ioctl
711Parameters: struct kvm_clock_data (out)
712Returns: 0 on success, -1 on error
713
714Gets the current timestamp of kvmclock as seen by the current guest. In
715conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
716such as migration.
717
718struct kvm_clock_data {
719 __u64 clock; /* kvmclock current value */
720 __u32 flags;
721 __u32 pad[9];
722};
723
Jan Kiszka414fa982012-04-24 16:40:15 +0200724
Paul Bolle68ba6972011-02-15 00:05:59 +01007254.30 KVM_SET_CLOCK
Glauber Costaafbcf7a2009-10-16 15:28:36 -0400726
727Capability: KVM_CAP_ADJUST_CLOCK
728Architectures: x86
729Type: vm ioctl
730Parameters: struct kvm_clock_data (in)
731Returns: 0 on success, -1 on error
732
Wu Fengguang2044892d2009-12-24 09:04:16 +0800733Sets the current timestamp of kvmclock to the value specified in its parameter.
Glauber Costaafbcf7a2009-10-16 15:28:36 -0400734In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
735such as migration.
736
737struct kvm_clock_data {
738 __u64 clock; /* kvmclock current value */
739 __u32 flags;
740 __u32 pad[9];
741};
742
Jan Kiszka414fa982012-04-24 16:40:15 +0200743
Paul Bolle68ba6972011-02-15 00:05:59 +01007444.31 KVM_GET_VCPU_EVENTS
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100745
746Capability: KVM_CAP_VCPU_EVENTS
Jan Kiszka48005f62010-02-19 19:38:07 +0100747Extended by: KVM_CAP_INTR_SHADOW
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100748Architectures: x86
749Type: vm ioctl
750Parameters: struct kvm_vcpu_event (out)
751Returns: 0 on success, -1 on error
752
753Gets currently pending exceptions, interrupts, and NMIs as well as related
754states of the vcpu.
755
756struct kvm_vcpu_events {
757 struct {
758 __u8 injected;
759 __u8 nr;
760 __u8 has_error_code;
761 __u8 pad;
762 __u32 error_code;
763 } exception;
764 struct {
765 __u8 injected;
766 __u8 nr;
767 __u8 soft;
Jan Kiszka48005f62010-02-19 19:38:07 +0100768 __u8 shadow;
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100769 } interrupt;
770 struct {
771 __u8 injected;
772 __u8 pending;
773 __u8 masked;
774 __u8 pad;
775 } nmi;
776 __u32 sipi_vector;
Jan Kiszkadab4b912009-12-06 18:24:15 +0100777 __u32 flags;
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100778};
779
Jan Kiszka48005f62010-02-19 19:38:07 +0100780KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
781interrupt.shadow contains a valid state. Otherwise, this field is undefined.
782
Jan Kiszka414fa982012-04-24 16:40:15 +0200783
Paul Bolle68ba6972011-02-15 00:05:59 +01007844.32 KVM_SET_VCPU_EVENTS
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100785
786Capability: KVM_CAP_VCPU_EVENTS
Jan Kiszka48005f62010-02-19 19:38:07 +0100787Extended by: KVM_CAP_INTR_SHADOW
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100788Architectures: x86
789Type: vm ioctl
790Parameters: struct kvm_vcpu_event (in)
791Returns: 0 on success, -1 on error
792
793Set pending exceptions, interrupts, and NMIs as well as related states of the
794vcpu.
795
796See KVM_GET_VCPU_EVENTS for the data structure.
797
Jan Kiszkadab4b912009-12-06 18:24:15 +0100798Fields that may be modified asynchronously by running VCPUs can be excluded
799from the update. These fields are nmi.pending and sipi_vector. Keep the
800corresponding bits in the flags field cleared to suppress overwriting the
801current in-kernel state. The bits are:
802
803KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
804KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
805
Jan Kiszka48005f62010-02-19 19:38:07 +0100806If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
807the flags field to signal that interrupt.shadow contains a valid state and
808shall be written into the VCPU.
809
Jan Kiszka414fa982012-04-24 16:40:15 +0200810
Paul Bolle68ba6972011-02-15 00:05:59 +01008114.33 KVM_GET_DEBUGREGS
Jan Kiszkaa1efbe72010-02-15 10:45:43 +0100812
813Capability: KVM_CAP_DEBUGREGS
814Architectures: x86
815Type: vm ioctl
816Parameters: struct kvm_debugregs (out)
817Returns: 0 on success, -1 on error
818
819Reads debug registers from the vcpu.
820
821struct kvm_debugregs {
822 __u64 db[4];
823 __u64 dr6;
824 __u64 dr7;
825 __u64 flags;
826 __u64 reserved[9];
827};
828
Jan Kiszka414fa982012-04-24 16:40:15 +0200829
Paul Bolle68ba6972011-02-15 00:05:59 +01008304.34 KVM_SET_DEBUGREGS
Jan Kiszkaa1efbe72010-02-15 10:45:43 +0100831
832Capability: KVM_CAP_DEBUGREGS
833Architectures: x86
834Type: vm ioctl
835Parameters: struct kvm_debugregs (in)
836Returns: 0 on success, -1 on error
837
838Writes debug registers into the vcpu.
839
840See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
841yet and must be cleared on entry.
842
Jan Kiszka414fa982012-04-24 16:40:15 +0200843
Paul Bolle68ba6972011-02-15 00:05:59 +01008444.35 KVM_SET_USER_MEMORY_REGION
Avi Kivity0f2d8f42010-03-25 12:16:48 +0200845
846Capability: KVM_CAP_USER_MEM
847Architectures: all
848Type: vm ioctl
849Parameters: struct kvm_userspace_memory_region (in)
850Returns: 0 on success, -1 on error
851
852struct kvm_userspace_memory_region {
853 __u32 slot;
854 __u32 flags;
855 __u64 guest_phys_addr;
856 __u64 memory_size; /* bytes */
857 __u64 userspace_addr; /* start of the userspace allocated memory */
858};
859
860/* for kvm_memory_region::flags */
Xiao Guangrong4d8b81a2012-08-21 11:02:51 +0800861#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
862#define KVM_MEM_READONLY (1UL << 1)
Avi Kivity0f2d8f42010-03-25 12:16:48 +0200863
864This ioctl allows the user to create or modify a guest physical memory
865slot. When changing an existing slot, it may be moved in the guest
866physical memory space, or its flags may be modified. It may not be
867resized. Slots may not overlap in guest physical address space.
868
869Memory for the region is taken starting at the address denoted by the
870field userspace_addr, which must point at user addressable memory for
871the entire memory slot size. Any object may back this memory, including
872anonymous memory, ordinary files, and hugetlbfs.
873
874It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
875be identical. This allows large pages in the guest to be backed by large
876pages in the host.
877
Jan Kiszka7efd8fa2012-09-07 13:17:47 +0200878The flags field supports two flag, KVM_MEM_LOG_DIRTY_PAGES, which instructs
879kvm to keep track of writes to memory within the slot. See KVM_GET_DIRTY_LOG
880ioctl. The KVM_CAP_READONLY_MEM capability indicates the availability of the
881KVM_MEM_READONLY flag. When this flag is set for a memory region, KVM only
882allows read accesses. Writes will be posted to userspace as KVM_EXIT_MMIO
883exits.
Avi Kivity0f2d8f42010-03-25 12:16:48 +0200884
Jan Kiszka7efd8fa2012-09-07 13:17:47 +0200885When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of
886the memory region are automatically reflected into the guest. For example, an
887mmap() that affects the region will be made visible immediately. Another
888example is madvise(MADV_DROP).
Avi Kivity0f2d8f42010-03-25 12:16:48 +0200889
890It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
891The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
892allocation and is deprecated.
Jan Kiszka3cfc3092009-11-12 01:04:25 +0100893
Jan Kiszka414fa982012-04-24 16:40:15 +0200894
Paul Bolle68ba6972011-02-15 00:05:59 +01008954.36 KVM_SET_TSS_ADDR
Avi Kivity8a5416d2010-03-25 12:27:30 +0200896
897Capability: KVM_CAP_SET_TSS_ADDR
898Architectures: x86
899Type: vm ioctl
900Parameters: unsigned long tss_address (in)
901Returns: 0 on success, -1 on error
902
903This ioctl defines the physical address of a three-page region in the guest
904physical address space. The region must be within the first 4GB of the
905guest physical address space and must not conflict with any memory slot
906or any mmio address. The guest may malfunction if it accesses this memory
907region.
908
909This ioctl is required on Intel-based hosts. This is needed on Intel hardware
910because of a quirk in the virtualization implementation (see the internals
911documentation when it pops into existence).
912
Jan Kiszka414fa982012-04-24 16:40:15 +0200913
Paul Bolle68ba6972011-02-15 00:05:59 +01009144.37 KVM_ENABLE_CAP
Alexander Graf71fbfd52010-03-24 21:48:29 +0100915
916Capability: KVM_CAP_ENABLE_CAP
917Architectures: ppc
918Type: vcpu ioctl
919Parameters: struct kvm_enable_cap (in)
920Returns: 0 on success; -1 on error
921
922+Not all extensions are enabled by default. Using this ioctl the application
923can enable an extension, making it available to the guest.
924
925On systems that do not support this ioctl, it always fails. On systems that
926do support it, it only works for extensions that are supported for enablement.
927
928To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
929be used.
930
931struct kvm_enable_cap {
932 /* in */
933 __u32 cap;
934
935The capability that is supposed to get enabled.
936
937 __u32 flags;
938
939A bitfield indicating future enhancements. Has to be 0 for now.
940
941 __u64 args[4];
942
943Arguments for enabling a feature. If a feature needs initial values to
944function properly, this is the place to put them.
945
946 __u8 pad[64];
947};
948
Jan Kiszka414fa982012-04-24 16:40:15 +0200949
Paul Bolle68ba6972011-02-15 00:05:59 +01009504.38 KVM_GET_MP_STATE
Avi Kivityb843f062010-04-25 15:51:46 +0300951
952Capability: KVM_CAP_MP_STATE
953Architectures: x86, ia64
954Type: vcpu ioctl
955Parameters: struct kvm_mp_state (out)
956Returns: 0 on success; -1 on error
957
958struct kvm_mp_state {
959 __u32 mp_state;
960};
961
962Returns the vcpu's current "multiprocessing state" (though also valid on
963uniprocessor guests).
964
965Possible values are:
966
967 - KVM_MP_STATE_RUNNABLE: the vcpu is currently running
968 - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP)
969 which has not yet received an INIT signal
970 - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is
971 now ready for a SIPI
972 - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and
973 is waiting for an interrupt
974 - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector
Uwe Kleine-Königb5950762010-11-01 15:38:34 -0400975 accessible via KVM_GET_VCPU_EVENTS)
Avi Kivityb843f062010-04-25 15:51:46 +0300976
977This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
978irqchip, the multiprocessing state must be maintained by userspace.
979
Jan Kiszka414fa982012-04-24 16:40:15 +0200980
Paul Bolle68ba6972011-02-15 00:05:59 +01009814.39 KVM_SET_MP_STATE
Avi Kivityb843f062010-04-25 15:51:46 +0300982
983Capability: KVM_CAP_MP_STATE
984Architectures: x86, ia64
985Type: vcpu ioctl
986Parameters: struct kvm_mp_state (in)
987Returns: 0 on success; -1 on error
988
989Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
990arguments.
991
992This ioctl is only useful after KVM_CREATE_IRQCHIP. Without an in-kernel
993irqchip, the multiprocessing state must be maintained by userspace.
994
Jan Kiszka414fa982012-04-24 16:40:15 +0200995
Paul Bolle68ba6972011-02-15 00:05:59 +01009964.40 KVM_SET_IDENTITY_MAP_ADDR
Avi Kivity47dbb842010-04-29 12:08:56 +0300997
998Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
999Architectures: x86
1000Type: vm ioctl
1001Parameters: unsigned long identity (in)
1002Returns: 0 on success, -1 on error
1003
1004This ioctl defines the physical address of a one-page region in the guest
1005physical address space. The region must be within the first 4GB of the
1006guest physical address space and must not conflict with any memory slot
1007or any mmio address. The guest may malfunction if it accesses this memory
1008region.
1009
1010This ioctl is required on Intel-based hosts. This is needed on Intel hardware
1011because of a quirk in the virtualization implementation (see the internals
1012documentation when it pops into existence).
1013
Jan Kiszka414fa982012-04-24 16:40:15 +02001014
Paul Bolle68ba6972011-02-15 00:05:59 +010010154.41 KVM_SET_BOOT_CPU_ID
Avi Kivity57bc24c2010-04-29 12:12:57 +03001016
1017Capability: KVM_CAP_SET_BOOT_CPU_ID
1018Architectures: x86, ia64
1019Type: vm ioctl
1020Parameters: unsigned long vcpu_id
1021Returns: 0 on success, -1 on error
1022
1023Define which vcpu is the Bootstrap Processor (BSP). Values are the same
1024as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
1025is vcpu 0.
1026
Jan Kiszka414fa982012-04-24 16:40:15 +02001027
Paul Bolle68ba6972011-02-15 00:05:59 +010010284.42 KVM_GET_XSAVE
Sheng Yang2d5b5a62010-06-13 17:29:39 +08001029
1030Capability: KVM_CAP_XSAVE
1031Architectures: x86
1032Type: vcpu ioctl
1033Parameters: struct kvm_xsave (out)
1034Returns: 0 on success, -1 on error
1035
1036struct kvm_xsave {
1037 __u32 region[1024];
1038};
1039
1040This ioctl would copy current vcpu's xsave struct to the userspace.
1041
Jan Kiszka414fa982012-04-24 16:40:15 +02001042
Paul Bolle68ba6972011-02-15 00:05:59 +010010434.43 KVM_SET_XSAVE
Sheng Yang2d5b5a62010-06-13 17:29:39 +08001044
1045Capability: KVM_CAP_XSAVE
1046Architectures: x86
1047Type: vcpu ioctl
1048Parameters: struct kvm_xsave (in)
1049Returns: 0 on success, -1 on error
1050
1051struct kvm_xsave {
1052 __u32 region[1024];
1053};
1054
1055This ioctl would copy userspace's xsave struct to the kernel.
1056
Jan Kiszka414fa982012-04-24 16:40:15 +02001057
Paul Bolle68ba6972011-02-15 00:05:59 +010010584.44 KVM_GET_XCRS
Sheng Yang2d5b5a62010-06-13 17:29:39 +08001059
1060Capability: KVM_CAP_XCRS
1061Architectures: x86
1062Type: vcpu ioctl
1063Parameters: struct kvm_xcrs (out)
1064Returns: 0 on success, -1 on error
1065
1066struct kvm_xcr {
1067 __u32 xcr;
1068 __u32 reserved;
1069 __u64 value;
1070};
1071
1072struct kvm_xcrs {
1073 __u32 nr_xcrs;
1074 __u32 flags;
1075 struct kvm_xcr xcrs[KVM_MAX_XCRS];
1076 __u64 padding[16];
1077};
1078
1079This ioctl would copy current vcpu's xcrs to the userspace.
1080
Jan Kiszka414fa982012-04-24 16:40:15 +02001081
Paul Bolle68ba6972011-02-15 00:05:59 +010010824.45 KVM_SET_XCRS
Sheng Yang2d5b5a62010-06-13 17:29:39 +08001083
1084Capability: KVM_CAP_XCRS
1085Architectures: x86
1086Type: vcpu ioctl
1087Parameters: struct kvm_xcrs (in)
1088Returns: 0 on success, -1 on error
1089
1090struct kvm_xcr {
1091 __u32 xcr;
1092 __u32 reserved;
1093 __u64 value;
1094};
1095
1096struct kvm_xcrs {
1097 __u32 nr_xcrs;
1098 __u32 flags;
1099 struct kvm_xcr xcrs[KVM_MAX_XCRS];
1100 __u64 padding[16];
1101};
1102
1103This ioctl would set vcpu's xcr to the value userspace specified.
1104
Jan Kiszka414fa982012-04-24 16:40:15 +02001105
Paul Bolle68ba6972011-02-15 00:05:59 +010011064.46 KVM_GET_SUPPORTED_CPUID
Avi Kivityd1535132010-07-14 09:45:21 +03001107
1108Capability: KVM_CAP_EXT_CPUID
1109Architectures: x86
1110Type: system ioctl
1111Parameters: struct kvm_cpuid2 (in/out)
1112Returns: 0 on success, -1 on error
1113
1114struct kvm_cpuid2 {
1115 __u32 nent;
1116 __u32 padding;
1117 struct kvm_cpuid_entry2 entries[0];
1118};
1119
1120#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX 1
1121#define KVM_CPUID_FLAG_STATEFUL_FUNC 2
1122#define KVM_CPUID_FLAG_STATE_READ_NEXT 4
1123
1124struct kvm_cpuid_entry2 {
1125 __u32 function;
1126 __u32 index;
1127 __u32 flags;
1128 __u32 eax;
1129 __u32 ebx;
1130 __u32 ecx;
1131 __u32 edx;
1132 __u32 padding[3];
1133};
1134
1135This ioctl returns x86 cpuid features which are supported by both the hardware
1136and kvm. Userspace can use the information returned by this ioctl to
1137construct cpuid information (for KVM_SET_CPUID2) that is consistent with
1138hardware, kernel, and userspace capabilities, and with user requirements (for
1139example, the user may wish to constrain cpuid to emulate older hardware,
1140or for feature consistency across a cluster).
1141
1142Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1143with the 'nent' field indicating the number of entries in the variable-size
1144array 'entries'. If the number of entries is too low to describe the cpu
1145capabilities, an error (E2BIG) is returned. If the number is too high,
1146the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
1147number is just right, the 'nent' field is adjusted to the number of valid
1148entries in the 'entries' array, which is then filled.
1149
1150The entries returned are the host cpuid as returned by the cpuid instruction,
Avi Kivityc39cbd22010-09-12 16:39:11 +02001151with unknown or unsupported features masked out. Some features (for example,
1152x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1153emulate them efficiently. The fields in each entry are defined as follows:
Avi Kivityd1535132010-07-14 09:45:21 +03001154
1155 function: the eax value used to obtain the entry
1156 index: the ecx value used to obtain the entry (for entries that are
1157 affected by ecx)
1158 flags: an OR of zero or more of the following:
1159 KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
1160 if the index field is valid
1161 KVM_CPUID_FLAG_STATEFUL_FUNC:
1162 if cpuid for this function returns different values for successive
1163 invocations; there will be several entries with the same function,
1164 all with this flag set
1165 KVM_CPUID_FLAG_STATE_READ_NEXT:
1166 for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
1167 the first entry to be read by a cpu
1168 eax, ebx, ecx, edx: the values returned by the cpuid instruction for
1169 this function/index combination
1170
Jan Kiszka4d25a0662011-12-21 12:28:29 +01001171The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned
1172as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC
1173support. Instead it is reported via
1174
1175 ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)
1176
1177if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the
1178feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
1179
Jan Kiszka414fa982012-04-24 16:40:15 +02001180
Paul Bolle68ba6972011-02-15 00:05:59 +010011814.47 KVM_PPC_GET_PVINFO
Alexander Graf15711e92010-07-29 14:48:08 +02001182
1183Capability: KVM_CAP_PPC_GET_PVINFO
1184Architectures: ppc
1185Type: vm ioctl
1186Parameters: struct kvm_ppc_pvinfo (out)
1187Returns: 0 on success, !0 on error
1188
1189struct kvm_ppc_pvinfo {
1190 __u32 flags;
1191 __u32 hcall[4];
1192 __u8 pad[108];
1193};
1194
1195This ioctl fetches PV specific information that need to be passed to the guest
1196using the device tree or other means from vm context.
1197
Liu Yu-B132019202e072012-07-03 05:48:52 +00001198The hcall array defines 4 instructions that make up a hypercall.
Alexander Graf15711e92010-07-29 14:48:08 +02001199
1200If any additional field gets added to this structure later on, a bit for that
1201additional piece of information will be set in the flags bitmap.
1202
Liu Yu-B132019202e072012-07-03 05:48:52 +00001203The flags bitmap is defined as:
1204
1205 /* the host supports the ePAPR idle hcall
1206 #define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0)
Jan Kiszka414fa982012-04-24 16:40:15 +02001207
Paul Bolle68ba6972011-02-15 00:05:59 +010012084.48 KVM_ASSIGN_PCI_DEVICE
Jan Kiszka49f48172010-11-16 22:30:07 +01001209
1210Capability: KVM_CAP_DEVICE_ASSIGNMENT
1211Architectures: x86 ia64
1212Type: vm ioctl
1213Parameters: struct kvm_assigned_pci_dev (in)
1214Returns: 0 on success, -1 on error
1215
1216Assigns a host PCI device to the VM.
1217
1218struct kvm_assigned_pci_dev {
1219 __u32 assigned_dev_id;
1220 __u32 busnr;
1221 __u32 devfn;
1222 __u32 flags;
1223 __u32 segnr;
1224 union {
1225 __u32 reserved[11];
1226 };
1227};
1228
1229The PCI device is specified by the triple segnr, busnr, and devfn.
1230Identification in succeeding service requests is done via assigned_dev_id. The
1231following flags are specified:
1232
1233/* Depends on KVM_CAP_IOMMU */
1234#define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0)
Jan Kiszka07700a92012-02-28 14:19:54 +01001235/* The following two depend on KVM_CAP_PCI_2_3 */
1236#define KVM_DEV_ASSIGN_PCI_2_3 (1 << 1)
1237#define KVM_DEV_ASSIGN_MASK_INTX (1 << 2)
1238
1239If KVM_DEV_ASSIGN_PCI_2_3 is set, the kernel will manage legacy INTx interrupts
1240via the PCI-2.3-compliant device-level mask, thus enable IRQ sharing with other
1241assigned devices or host devices. KVM_DEV_ASSIGN_MASK_INTX specifies the
1242guest's view on the INTx mask, see KVM_ASSIGN_SET_INTX_MASK for details.
Jan Kiszka49f48172010-11-16 22:30:07 +01001243
Alex Williamson42387372011-12-20 21:59:03 -07001244The KVM_DEV_ASSIGN_ENABLE_IOMMU flag is a mandatory option to ensure
1245isolation of the device. Usages not specifying this flag are deprecated.
1246
Alex Williamson3d27e232011-12-20 21:59:09 -07001247Only PCI header type 0 devices with PCI BAR resources are supported by
1248device assignment. The user requesting this ioctl must have read/write
1249access to the PCI sysfs resource files associated with the device.
1250
Jan Kiszka414fa982012-04-24 16:40:15 +02001251
Paul Bolle68ba6972011-02-15 00:05:59 +010012524.49 KVM_DEASSIGN_PCI_DEVICE
Jan Kiszka49f48172010-11-16 22:30:07 +01001253
1254Capability: KVM_CAP_DEVICE_DEASSIGNMENT
1255Architectures: x86 ia64
1256Type: vm ioctl
1257Parameters: struct kvm_assigned_pci_dev (in)
1258Returns: 0 on success, -1 on error
1259
1260Ends PCI device assignment, releasing all associated resources.
1261
1262See KVM_CAP_DEVICE_ASSIGNMENT for the data structure. Only assigned_dev_id is
1263used in kvm_assigned_pci_dev to identify the device.
1264
Jan Kiszka414fa982012-04-24 16:40:15 +02001265
Paul Bolle68ba6972011-02-15 00:05:59 +010012664.50 KVM_ASSIGN_DEV_IRQ
Jan Kiszka49f48172010-11-16 22:30:07 +01001267
1268Capability: KVM_CAP_ASSIGN_DEV_IRQ
1269Architectures: x86 ia64
1270Type: vm ioctl
1271Parameters: struct kvm_assigned_irq (in)
1272Returns: 0 on success, -1 on error
1273
1274Assigns an IRQ to a passed-through device.
1275
1276struct kvm_assigned_irq {
1277 __u32 assigned_dev_id;
Jan Kiszka91e3d712011-06-03 08:51:05 +02001278 __u32 host_irq; /* ignored (legacy field) */
Jan Kiszka49f48172010-11-16 22:30:07 +01001279 __u32 guest_irq;
1280 __u32 flags;
1281 union {
Jan Kiszka49f48172010-11-16 22:30:07 +01001282 __u32 reserved[12];
1283 };
1284};
1285
1286The following flags are defined:
1287
1288#define KVM_DEV_IRQ_HOST_INTX (1 << 0)
1289#define KVM_DEV_IRQ_HOST_MSI (1 << 1)
1290#define KVM_DEV_IRQ_HOST_MSIX (1 << 2)
1291
1292#define KVM_DEV_IRQ_GUEST_INTX (1 << 8)
1293#define KVM_DEV_IRQ_GUEST_MSI (1 << 9)
1294#define KVM_DEV_IRQ_GUEST_MSIX (1 << 10)
1295
1296It is not valid to specify multiple types per host or guest IRQ. However, the
1297IRQ type of host and guest can differ or can even be null.
1298
Jan Kiszka414fa982012-04-24 16:40:15 +02001299
Paul Bolle68ba6972011-02-15 00:05:59 +010013004.51 KVM_DEASSIGN_DEV_IRQ
Jan Kiszka49f48172010-11-16 22:30:07 +01001301
1302Capability: KVM_CAP_ASSIGN_DEV_IRQ
1303Architectures: x86 ia64
1304Type: vm ioctl
1305Parameters: struct kvm_assigned_irq (in)
1306Returns: 0 on success, -1 on error
1307
1308Ends an IRQ assignment to a passed-through device.
1309
1310See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1311by assigned_dev_id, flags must correspond to the IRQ type specified on
1312KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed.
1313
Jan Kiszka414fa982012-04-24 16:40:15 +02001314
Paul Bolle68ba6972011-02-15 00:05:59 +010013154.52 KVM_SET_GSI_ROUTING
Jan Kiszka49f48172010-11-16 22:30:07 +01001316
1317Capability: KVM_CAP_IRQ_ROUTING
1318Architectures: x86 ia64
1319Type: vm ioctl
1320Parameters: struct kvm_irq_routing (in)
1321Returns: 0 on success, -1 on error
1322
1323Sets the GSI routing table entries, overwriting any previously set entries.
1324
1325struct kvm_irq_routing {
1326 __u32 nr;
1327 __u32 flags;
1328 struct kvm_irq_routing_entry entries[0];
1329};
1330
1331No flags are specified so far, the corresponding field must be set to zero.
1332
1333struct kvm_irq_routing_entry {
1334 __u32 gsi;
1335 __u32 type;
1336 __u32 flags;
1337 __u32 pad;
1338 union {
1339 struct kvm_irq_routing_irqchip irqchip;
1340 struct kvm_irq_routing_msi msi;
1341 __u32 pad[8];
1342 } u;
1343};
1344
1345/* gsi routing entry types */
1346#define KVM_IRQ_ROUTING_IRQCHIP 1
1347#define KVM_IRQ_ROUTING_MSI 2
1348
1349No flags are specified so far, the corresponding field must be set to zero.
1350
1351struct kvm_irq_routing_irqchip {
1352 __u32 irqchip;
1353 __u32 pin;
1354};
1355
1356struct kvm_irq_routing_msi {
1357 __u32 address_lo;
1358 __u32 address_hi;
1359 __u32 data;
1360 __u32 pad;
1361};
1362
Jan Kiszka414fa982012-04-24 16:40:15 +02001363
Paul Bolle68ba6972011-02-15 00:05:59 +010013644.53 KVM_ASSIGN_SET_MSIX_NR
Jan Kiszka49f48172010-11-16 22:30:07 +01001365
1366Capability: KVM_CAP_DEVICE_MSIX
1367Architectures: x86 ia64
1368Type: vm ioctl
1369Parameters: struct kvm_assigned_msix_nr (in)
1370Returns: 0 on success, -1 on error
1371
Jan Kiszka58f09642011-06-11 12:24:24 +02001372Set the number of MSI-X interrupts for an assigned device. The number is
1373reset again by terminating the MSI-X assignment of the device via
1374KVM_DEASSIGN_DEV_IRQ. Calling this service more than once at any earlier
1375point will fail.
Jan Kiszka49f48172010-11-16 22:30:07 +01001376
1377struct kvm_assigned_msix_nr {
1378 __u32 assigned_dev_id;
1379 __u16 entry_nr;
1380 __u16 padding;
1381};
1382
1383#define KVM_MAX_MSIX_PER_DEV 256
1384
Jan Kiszka414fa982012-04-24 16:40:15 +02001385
Paul Bolle68ba6972011-02-15 00:05:59 +010013864.54 KVM_ASSIGN_SET_MSIX_ENTRY
Jan Kiszka49f48172010-11-16 22:30:07 +01001387
1388Capability: KVM_CAP_DEVICE_MSIX
1389Architectures: x86 ia64
1390Type: vm ioctl
1391Parameters: struct kvm_assigned_msix_entry (in)
1392Returns: 0 on success, -1 on error
1393
1394Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1395the GSI vector to zero means disabling the interrupt.
1396
1397struct kvm_assigned_msix_entry {
1398 __u32 assigned_dev_id;
1399 __u32 gsi;
1400 __u16 entry; /* The index of entry in the MSI-X table */
1401 __u16 padding[3];
1402};
1403
Jan Kiszka414fa982012-04-24 16:40:15 +02001404
14054.55 KVM_SET_TSC_KHZ
Joerg Roedel92a1f122011-03-25 09:44:51 +01001406
1407Capability: KVM_CAP_TSC_CONTROL
1408Architectures: x86
1409Type: vcpu ioctl
1410Parameters: virtual tsc_khz
1411Returns: 0 on success, -1 on error
1412
1413Specifies the tsc frequency for the virtual machine. The unit of the
1414frequency is KHz.
1415
Jan Kiszka414fa982012-04-24 16:40:15 +02001416
14174.56 KVM_GET_TSC_KHZ
Joerg Roedel92a1f122011-03-25 09:44:51 +01001418
1419Capability: KVM_CAP_GET_TSC_KHZ
1420Architectures: x86
1421Type: vcpu ioctl
1422Parameters: none
1423Returns: virtual tsc-khz on success, negative value on error
1424
1425Returns the tsc frequency of the guest. The unit of the return value is
1426KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
1427error.
1428
Jan Kiszka414fa982012-04-24 16:40:15 +02001429
14304.57 KVM_GET_LAPIC
Avi Kivitye7677932011-05-11 08:30:51 -04001431
1432Capability: KVM_CAP_IRQCHIP
1433Architectures: x86
1434Type: vcpu ioctl
1435Parameters: struct kvm_lapic_state (out)
1436Returns: 0 on success, -1 on error
1437
1438#define KVM_APIC_REG_SIZE 0x400
1439struct kvm_lapic_state {
1440 char regs[KVM_APIC_REG_SIZE];
1441};
1442
1443Reads the Local APIC registers and copies them into the input argument. The
1444data format and layout are the same as documented in the architecture manual.
1445
Jan Kiszka414fa982012-04-24 16:40:15 +02001446
14474.58 KVM_SET_LAPIC
Avi Kivitye7677932011-05-11 08:30:51 -04001448
1449Capability: KVM_CAP_IRQCHIP
1450Architectures: x86
1451Type: vcpu ioctl
1452Parameters: struct kvm_lapic_state (in)
1453Returns: 0 on success, -1 on error
1454
1455#define KVM_APIC_REG_SIZE 0x400
1456struct kvm_lapic_state {
1457 char regs[KVM_APIC_REG_SIZE];
1458};
1459
1460Copies the input argument into the the Local APIC registers. The data format
1461and layout are the same as documented in the architecture manual.
1462
Jan Kiszka414fa982012-04-24 16:40:15 +02001463
14644.59 KVM_IOEVENTFD
Sasha Levin55399a02011-05-28 14:12:30 +03001465
1466Capability: KVM_CAP_IOEVENTFD
1467Architectures: all
1468Type: vm ioctl
1469Parameters: struct kvm_ioeventfd (in)
1470Returns: 0 on success, !0 on error
1471
1472This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
1473within the guest. A guest write in the registered address will signal the
1474provided event instead of triggering an exit.
1475
1476struct kvm_ioeventfd {
1477 __u64 datamatch;
1478 __u64 addr; /* legal pio/mmio address */
1479 __u32 len; /* 1, 2, 4, or 8 bytes */
1480 __s32 fd;
1481 __u32 flags;
1482 __u8 pad[36];
1483};
1484
1485The following flags are defined:
1486
1487#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
1488#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
1489#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
1490
1491If datamatch flag is set, the event will be signaled only if the written value
1492to the registered address is equal to datamatch in struct kvm_ioeventfd.
1493
Jan Kiszka414fa982012-04-24 16:40:15 +02001494
14954.60 KVM_DIRTY_TLB
Scott Wooddc83b8b2011-08-18 15:25:21 -05001496
1497Capability: KVM_CAP_SW_TLB
1498Architectures: ppc
1499Type: vcpu ioctl
1500Parameters: struct kvm_dirty_tlb (in)
1501Returns: 0 on success, -1 on error
1502
1503struct kvm_dirty_tlb {
1504 __u64 bitmap;
1505 __u32 num_dirty;
1506};
1507
1508This must be called whenever userspace has changed an entry in the shared
1509TLB, prior to calling KVM_RUN on the associated vcpu.
1510
1511The "bitmap" field is the userspace address of an array. This array
1512consists of a number of bits, equal to the total number of TLB entries as
1513determined by the last successful call to KVM_CONFIG_TLB, rounded up to the
1514nearest multiple of 64.
1515
1516Each bit corresponds to one TLB entry, ordered the same as in the shared TLB
1517array.
1518
1519The array is little-endian: the bit 0 is the least significant bit of the
1520first byte, bit 8 is the least significant bit of the second byte, etc.
1521This avoids any complications with differing word sizes.
1522
1523The "num_dirty" field is a performance hint for KVM to determine whether it
1524should skip processing the bitmap and just invalidate everything. It must
1525be set to the number of set bits in the bitmap.
1526
Jan Kiszka414fa982012-04-24 16:40:15 +02001527
15284.61 KVM_ASSIGN_SET_INTX_MASK
Jan Kiszka07700a92012-02-28 14:19:54 +01001529
1530Capability: KVM_CAP_PCI_2_3
1531Architectures: x86
1532Type: vm ioctl
1533Parameters: struct kvm_assigned_pci_dev (in)
1534Returns: 0 on success, -1 on error
1535
1536Allows userspace to mask PCI INTx interrupts from the assigned device. The
1537kernel will not deliver INTx interrupts to the guest between setting and
1538clearing of KVM_ASSIGN_SET_INTX_MASK via this interface. This enables use of
1539and emulation of PCI 2.3 INTx disable command register behavior.
1540
1541This may be used for both PCI 2.3 devices supporting INTx disable natively and
1542older devices lacking this support. Userspace is responsible for emulating the
1543read value of the INTx disable bit in the guest visible PCI command register.
1544When modifying the INTx disable state, userspace should precede updating the
1545physical device command register by calling this ioctl to inform the kernel of
1546the new intended INTx mask state.
1547
1548Note that the kernel uses the device INTx disable bit to internally manage the
1549device interrupt state for PCI 2.3 devices. Reads of this register may
1550therefore not match the expected value. Writes should always use the guest
1551intended INTx disable value rather than attempting to read-copy-update the
1552current physical device state. Races between user and kernel updates to the
1553INTx disable bit are handled lazily in the kernel. It's possible the device
1554may generate unintended interrupts, but they will not be injected into the
1555guest.
1556
1557See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1558by assigned_dev_id. In the flags field, only KVM_DEV_ASSIGN_MASK_INTX is
1559evaluated.
1560
Jan Kiszka414fa982012-04-24 16:40:15 +02001561
David Gibson54738c02011-06-29 00:22:41 +000015624.62 KVM_CREATE_SPAPR_TCE
1563
1564Capability: KVM_CAP_SPAPR_TCE
1565Architectures: powerpc
1566Type: vm ioctl
1567Parameters: struct kvm_create_spapr_tce (in)
1568Returns: file descriptor for manipulating the created TCE table
1569
1570This creates a virtual TCE (translation control entry) table, which
1571is an IOMMU for PAPR-style virtual I/O. It is used to translate
1572logical addresses used in virtual I/O into guest physical addresses,
1573and provides a scatter/gather capability for PAPR virtual I/O.
1574
1575/* for KVM_CAP_SPAPR_TCE */
1576struct kvm_create_spapr_tce {
1577 __u64 liobn;
1578 __u32 window_size;
1579};
1580
1581The liobn field gives the logical IO bus number for which to create a
1582TCE table. The window_size field specifies the size of the DMA window
1583which this TCE table will translate - the table will contain one 64
1584bit TCE entry for every 4kiB of the DMA window.
1585
1586When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
1587table has been created using this ioctl(), the kernel will handle it
1588in real mode, updating the TCE table. H_PUT_TCE calls for other
1589liobns will cause a vm exit and must be handled by userspace.
1590
1591The return value is a file descriptor which can be passed to mmap(2)
1592to map the created TCE table into userspace. This lets userspace read
1593the entries written by kernel-handled H_PUT_TCE calls, and also lets
1594userspace update the TCE table directly which is useful in some
1595circumstances.
1596
Jan Kiszka414fa982012-04-24 16:40:15 +02001597
Paul Mackerrasaa04b4c2011-06-29 00:25:44 +000015984.63 KVM_ALLOCATE_RMA
1599
1600Capability: KVM_CAP_PPC_RMA
1601Architectures: powerpc
1602Type: vm ioctl
1603Parameters: struct kvm_allocate_rma (out)
1604Returns: file descriptor for mapping the allocated RMA
1605
1606This allocates a Real Mode Area (RMA) from the pool allocated at boot
1607time by the kernel. An RMA is a physically-contiguous, aligned region
1608of memory used on older POWER processors to provide the memory which
1609will be accessed by real-mode (MMU off) accesses in a KVM guest.
1610POWER processors support a set of sizes for the RMA that usually
1611includes 64MB, 128MB, 256MB and some larger powers of two.
1612
1613/* for KVM_ALLOCATE_RMA */
1614struct kvm_allocate_rma {
1615 __u64 rma_size;
1616};
1617
1618The return value is a file descriptor which can be passed to mmap(2)
1619to map the allocated RMA into userspace. The mapped area can then be
1620passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the
1621RMA for a virtual machine. The size of the RMA in bytes (which is
1622fixed at host kernel boot time) is returned in the rma_size field of
1623the argument structure.
1624
1625The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl
1626is supported; 2 if the processor requires all virtual machines to have
1627an RMA, or 1 if the processor can use an RMA but doesn't require it,
1628because it supports the Virtual RMA (VRMA) facility.
1629
Jan Kiszka414fa982012-04-24 16:40:15 +02001630
Avi Kivity3f745f12011-12-07 12:42:47 +020016314.64 KVM_NMI
1632
1633Capability: KVM_CAP_USER_NMI
1634Architectures: x86
1635Type: vcpu ioctl
1636Parameters: none
1637Returns: 0 on success, -1 on error
1638
1639Queues an NMI on the thread's vcpu. Note this is well defined only
1640when KVM_CREATE_IRQCHIP has not been called, since this is an interface
1641between the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIP
1642has been called, this interface is completely emulated within the kernel.
1643
1644To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the
1645following algorithm:
1646
1647 - pause the vpcu
1648 - read the local APIC's state (KVM_GET_LAPIC)
1649 - check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1)
1650 - if so, issue KVM_NMI
1651 - resume the vcpu
1652
1653Some guests configure the LINT1 NMI input to cause a panic, aiding in
1654debugging.
1655
Jan Kiszka414fa982012-04-24 16:40:15 +02001656
Alexander Grafe24ed812011-09-14 10:02:41 +020016574.65 KVM_S390_UCAS_MAP
Carsten Otte27e03932012-01-04 10:25:21 +01001658
1659Capability: KVM_CAP_S390_UCONTROL
1660Architectures: s390
1661Type: vcpu ioctl
1662Parameters: struct kvm_s390_ucas_mapping (in)
1663Returns: 0 in case of success
1664
1665The parameter is defined like this:
1666 struct kvm_s390_ucas_mapping {
1667 __u64 user_addr;
1668 __u64 vcpu_addr;
1669 __u64 length;
1670 };
1671
1672This ioctl maps the memory at "user_addr" with the length "length" to
1673the vcpu's address space starting at "vcpu_addr". All parameters need to
1674be alligned by 1 megabyte.
1675
Jan Kiszka414fa982012-04-24 16:40:15 +02001676
Alexander Grafe24ed812011-09-14 10:02:41 +020016774.66 KVM_S390_UCAS_UNMAP
Carsten Otte27e03932012-01-04 10:25:21 +01001678
1679Capability: KVM_CAP_S390_UCONTROL
1680Architectures: s390
1681Type: vcpu ioctl
1682Parameters: struct kvm_s390_ucas_mapping (in)
1683Returns: 0 in case of success
1684
1685The parameter is defined like this:
1686 struct kvm_s390_ucas_mapping {
1687 __u64 user_addr;
1688 __u64 vcpu_addr;
1689 __u64 length;
1690 };
1691
1692This ioctl unmaps the memory in the vcpu's address space starting at
1693"vcpu_addr" with the length "length". The field "user_addr" is ignored.
1694All parameters need to be alligned by 1 megabyte.
1695
Jan Kiszka414fa982012-04-24 16:40:15 +02001696
Alexander Grafe24ed812011-09-14 10:02:41 +020016974.67 KVM_S390_VCPU_FAULT
Carsten Otteccc79102012-01-04 10:25:26 +01001698
1699Capability: KVM_CAP_S390_UCONTROL
1700Architectures: s390
1701Type: vcpu ioctl
1702Parameters: vcpu absolute address (in)
1703Returns: 0 in case of success
1704
1705This call creates a page table entry on the virtual cpu's address space
1706(for user controlled virtual machines) or the virtual machine's address
1707space (for regular virtual machines). This only works for minor faults,
1708thus it's recommended to access subject memory page via the user page
1709table upfront. This is useful to handle validity intercepts for user
1710controlled virtual machines to fault in the virtual cpu's lowcore pages
1711prior to calling the KVM_RUN ioctl.
1712
Jan Kiszka414fa982012-04-24 16:40:15 +02001713
Alexander Grafe24ed812011-09-14 10:02:41 +020017144.68 KVM_SET_ONE_REG
1715
1716Capability: KVM_CAP_ONE_REG
1717Architectures: all
1718Type: vcpu ioctl
1719Parameters: struct kvm_one_reg (in)
1720Returns: 0 on success, negative value on failure
1721
1722struct kvm_one_reg {
1723 __u64 id;
1724 __u64 addr;
1725};
1726
1727Using this ioctl, a single vcpu register can be set to a specific value
1728defined by user space with the passed in struct kvm_one_reg, where id
1729refers to the register identifier as described below and addr is a pointer
1730to a variable with the respective size. There can be architecture agnostic
1731and architecture specific registers. Each have their own range of operation
1732and their own constants and width. To keep track of the implemented
1733registers, find a list below:
1734
1735 Arch | Register | Width (bits)
1736 | |
Alexander Graf1022fc32011-09-14 21:45:23 +02001737 PPC | KVM_REG_PPC_HIOR | 64
Bharat Bhushan2e232702012-08-15 17:37:13 +00001738 PPC | KVM_REG_PPC_IAC1 | 64
1739 PPC | KVM_REG_PPC_IAC2 | 64
1740 PPC | KVM_REG_PPC_IAC3 | 64
1741 PPC | KVM_REG_PPC_IAC4 | 64
1742 PPC | KVM_REG_PPC_DAC1 | 64
1743 PPC | KVM_REG_PPC_DAC2 | 64
Paul Mackerrasa136a8b2012-09-25 20:31:56 +00001744 PPC | KVM_REG_PPC_DABR | 64
1745 PPC | KVM_REG_PPC_DSCR | 64
1746 PPC | KVM_REG_PPC_PURR | 64
1747 PPC | KVM_REG_PPC_SPURR | 64
1748 PPC | KVM_REG_PPC_DAR | 64
1749 PPC | KVM_REG_PPC_DSISR | 32
1750 PPC | KVM_REG_PPC_AMR | 64
1751 PPC | KVM_REG_PPC_UAMOR | 64
1752 PPC | KVM_REG_PPC_MMCR0 | 64
1753 PPC | KVM_REG_PPC_MMCR1 | 64
1754 PPC | KVM_REG_PPC_MMCRA | 64
1755 PPC | KVM_REG_PPC_PMC1 | 32
1756 PPC | KVM_REG_PPC_PMC2 | 32
1757 PPC | KVM_REG_PPC_PMC3 | 32
1758 PPC | KVM_REG_PPC_PMC4 | 32
1759 PPC | KVM_REG_PPC_PMC5 | 32
1760 PPC | KVM_REG_PPC_PMC6 | 32
1761 PPC | KVM_REG_PPC_PMC7 | 32
1762 PPC | KVM_REG_PPC_PMC8 | 32
Paul Mackerrasa8bd19e2012-09-25 20:32:30 +00001763 PPC | KVM_REG_PPC_FPR0 | 64
1764 ...
1765 PPC | KVM_REG_PPC_FPR31 | 64
1766 PPC | KVM_REG_PPC_VR0 | 128
1767 ...
1768 PPC | KVM_REG_PPC_VR31 | 128
1769 PPC | KVM_REG_PPC_VSR0 | 128
1770 ...
1771 PPC | KVM_REG_PPC_VSR31 | 128
1772 PPC | KVM_REG_PPC_FPSCR | 64
1773 PPC | KVM_REG_PPC_VSCR | 32
Paul Mackerras55b665b2012-09-25 20:33:06 +00001774 PPC | KVM_REG_PPC_VPA_ADDR | 64
1775 PPC | KVM_REG_PPC_VPA_SLB | 128
1776 PPC | KVM_REG_PPC_VPA_DTL | 128
Mihai Caraman352df1d2012-10-11 06:13:29 +00001777 PPC | KVM_REG_PPC_EPCR | 32
Jan Kiszka414fa982012-04-24 16:40:15 +02001778
Christoffer Dall749cf76c2013-01-20 18:28:06 -05001779ARM registers are mapped using the lower 32 bits. The upper 16 of that
1780is the register group type, or coprocessor number:
1781
1782ARM core registers have the following id bit patterns:
1783 0x4002 0000 0010 <index into the kvm_regs struct:16>
1784
1785
1786
Alexander Grafe24ed812011-09-14 10:02:41 +020017874.69 KVM_GET_ONE_REG
1788
1789Capability: KVM_CAP_ONE_REG
1790Architectures: all
1791Type: vcpu ioctl
1792Parameters: struct kvm_one_reg (in and out)
1793Returns: 0 on success, negative value on failure
1794
1795This ioctl allows to receive the value of a single register implemented
1796in a vcpu. The register to read is indicated by the "id" field of the
1797kvm_one_reg struct passed in. On success, the register value can be found
1798at the memory location pointed to by "addr".
1799
1800The list of registers accessible using this interface is identical to the
Bharat Bhushan2e232702012-08-15 17:37:13 +00001801list in 4.68.
Alexander Grafe24ed812011-09-14 10:02:41 +02001802
Jan Kiszka414fa982012-04-24 16:40:15 +02001803
Eric B Munson1c0b28c2012-03-10 14:37:27 -050018044.70 KVM_KVMCLOCK_CTRL
1805
1806Capability: KVM_CAP_KVMCLOCK_CTRL
1807Architectures: Any that implement pvclocks (currently x86 only)
1808Type: vcpu ioctl
1809Parameters: None
1810Returns: 0 on success, -1 on error
1811
1812This signals to the host kernel that the specified guest is being paused by
1813userspace. The host will set a flag in the pvclock structure that is checked
1814from the soft lockup watchdog. The flag is part of the pvclock structure that
1815is shared between guest and host, specifically the second bit of the flags
1816field of the pvclock_vcpu_time_info structure. It will be set exclusively by
1817the host and read/cleared exclusively by the guest. The guest operation of
1818checking and clearing the flag must an atomic operation so
1819load-link/store-conditional, or equivalent must be used. There are two cases
1820where the guest will clear the flag: when the soft lockup watchdog timer resets
1821itself or when a soft lockup is detected. This ioctl can be called any time
1822after pausing the vcpu, but before it is resumed.
1823
Jan Kiszka414fa982012-04-24 16:40:15 +02001824
Jan Kiszka07975ad2012-03-29 21:14:12 +020018254.71 KVM_SIGNAL_MSI
1826
1827Capability: KVM_CAP_SIGNAL_MSI
1828Architectures: x86
1829Type: vm ioctl
1830Parameters: struct kvm_msi (in)
1831Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
1832
1833Directly inject a MSI message. Only valid with in-kernel irqchip that handles
1834MSI messages.
1835
1836struct kvm_msi {
1837 __u32 address_lo;
1838 __u32 address_hi;
1839 __u32 data;
1840 __u32 flags;
1841 __u8 pad[16];
1842};
1843
1844No flags are defined so far. The corresponding field must be 0.
1845
Jan Kiszka414fa982012-04-24 16:40:15 +02001846
Jan Kiszka0589ff62012-04-24 16:40:16 +020018474.71 KVM_CREATE_PIT2
1848
1849Capability: KVM_CAP_PIT2
1850Architectures: x86
1851Type: vm ioctl
1852Parameters: struct kvm_pit_config (in)
1853Returns: 0 on success, -1 on error
1854
1855Creates an in-kernel device model for the i8254 PIT. This call is only valid
1856after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following
1857parameters have to be passed:
1858
1859struct kvm_pit_config {
1860 __u32 flags;
1861 __u32 pad[15];
1862};
1863
1864Valid flags are:
1865
1866#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */
1867
Jan Kiszkab6ddf052012-04-24 16:40:17 +02001868PIT timer interrupts may use a per-VM kernel thread for injection. If it
1869exists, this thread will have a name of the following pattern:
1870
1871kvm-pit/<owner-process-pid>
1872
1873When running a guest with elevated priorities, the scheduling parameters of
1874this thread may have to be adjusted accordingly.
1875
Jan Kiszka0589ff62012-04-24 16:40:16 +02001876This IOCTL replaces the obsolete KVM_CREATE_PIT.
1877
1878
18794.72 KVM_GET_PIT2
1880
1881Capability: KVM_CAP_PIT_STATE2
1882Architectures: x86
1883Type: vm ioctl
1884Parameters: struct kvm_pit_state2 (out)
1885Returns: 0 on success, -1 on error
1886
1887Retrieves the state of the in-kernel PIT model. Only valid after
1888KVM_CREATE_PIT2. The state is returned in the following structure:
1889
1890struct kvm_pit_state2 {
1891 struct kvm_pit_channel_state channels[3];
1892 __u32 flags;
1893 __u32 reserved[9];
1894};
1895
1896Valid flags are:
1897
1898/* disable PIT in HPET legacy mode */
1899#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001
1900
1901This IOCTL replaces the obsolete KVM_GET_PIT.
1902
1903
19044.73 KVM_SET_PIT2
1905
1906Capability: KVM_CAP_PIT_STATE2
1907Architectures: x86
1908Type: vm ioctl
1909Parameters: struct kvm_pit_state2 (in)
1910Returns: 0 on success, -1 on error
1911
1912Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
1913See KVM_GET_PIT2 for details on struct kvm_pit_state2.
1914
1915This IOCTL replaces the obsolete KVM_SET_PIT.
1916
1917
Benjamin Herrenschmidt5b747162012-04-26 19:43:42 +000019184.74 KVM_PPC_GET_SMMU_INFO
1919
1920Capability: KVM_CAP_PPC_GET_SMMU_INFO
1921Architectures: powerpc
1922Type: vm ioctl
1923Parameters: None
1924Returns: 0 on success, -1 on error
1925
1926This populates and returns a structure describing the features of
1927the "Server" class MMU emulation supported by KVM.
1928This can in turn be used by userspace to generate the appropariate
1929device-tree properties for the guest operating system.
1930
1931The structure contains some global informations, followed by an
1932array of supported segment page sizes:
1933
1934 struct kvm_ppc_smmu_info {
1935 __u64 flags;
1936 __u32 slb_size;
1937 __u32 pad;
1938 struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ];
1939 };
1940
1941The supported flags are:
1942
1943 - KVM_PPC_PAGE_SIZES_REAL:
1944 When that flag is set, guest page sizes must "fit" the backing
1945 store page sizes. When not set, any page size in the list can
1946 be used regardless of how they are backed by userspace.
1947
1948 - KVM_PPC_1T_SEGMENTS
1949 The emulated MMU supports 1T segments in addition to the
1950 standard 256M ones.
1951
1952The "slb_size" field indicates how many SLB entries are supported
1953
1954The "sps" array contains 8 entries indicating the supported base
1955page sizes for a segment in increasing order. Each entry is defined
1956as follow:
1957
1958 struct kvm_ppc_one_seg_page_size {
1959 __u32 page_shift; /* Base page shift of segment (or 0) */
1960 __u32 slb_enc; /* SLB encoding for BookS */
1961 struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ];
1962 };
1963
1964An entry with a "page_shift" of 0 is unused. Because the array is
1965organized in increasing order, a lookup can stop when encoutering
1966such an entry.
1967
1968The "slb_enc" field provides the encoding to use in the SLB for the
1969page size. The bits are in positions such as the value can directly
1970be OR'ed into the "vsid" argument of the slbmte instruction.
1971
1972The "enc" array is a list which for each of those segment base page
1973size provides the list of supported actual page sizes (which can be
1974only larger or equal to the base page size), along with the
1975corresponding encoding in the hash PTE. Similarily, the array is
19768 entries sorted by increasing sizes and an entry with a "0" shift
1977is an empty entry and a terminator:
1978
1979 struct kvm_ppc_one_page_size {
1980 __u32 page_shift; /* Page shift (or 0) */
1981 __u32 pte_enc; /* Encoding in the HPTE (>>12) */
1982 };
1983
1984The "pte_enc" field provides a value that can OR'ed into the hash
1985PTE's RPN field (ie, it needs to be shifted left by 12 to OR it
1986into the hash PTE second double word).
1987
Alex Williamsonf36992e2012-06-29 09:56:16 -060019884.75 KVM_IRQFD
1989
1990Capability: KVM_CAP_IRQFD
1991Architectures: x86
1992Type: vm ioctl
1993Parameters: struct kvm_irqfd (in)
1994Returns: 0 on success, -1 on error
1995
1996Allows setting an eventfd to directly trigger a guest interrupt.
1997kvm_irqfd.fd specifies the file descriptor to use as the eventfd and
1998kvm_irqfd.gsi specifies the irqchip pin toggled by this event. When
1999an event is tiggered on the eventfd, an interrupt is injected into
2000the guest using the specified gsi pin. The irqfd is removed using
2001the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd
2002and kvm_irqfd.gsi.
2003
Alex Williamson7a844282012-09-21 11:58:03 -06002004With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify
2005mechanism allowing emulation of level-triggered, irqfd-based
2006interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an
2007additional eventfd in the kvm_irqfd.resamplefd field. When operating
2008in resample mode, posting of an interrupt through kvm_irq.fd asserts
2009the specified gsi in the irqchip. When the irqchip is resampled, such
2010as from an EOI, the gsi is de-asserted and the user is notifed via
2011kvm_irqfd.resamplefd. It is the user's responsibility to re-queue
2012the interrupt if the device making use of it still requires service.
2013Note that closing the resamplefd is not sufficient to disable the
2014irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment
2015and need not be specified with KVM_IRQFD_FLAG_DEASSIGN.
2016
Linus Torvalds5fecc9d2012-07-24 12:01:20 -070020174.76 KVM_PPC_ALLOCATE_HTAB
Paul Mackerras32fad282012-05-04 02:32:53 +00002018
2019Capability: KVM_CAP_PPC_ALLOC_HTAB
2020Architectures: powerpc
2021Type: vm ioctl
2022Parameters: Pointer to u32 containing hash table order (in/out)
2023Returns: 0 on success, -1 on error
2024
2025This requests the host kernel to allocate an MMU hash table for a
2026guest using the PAPR paravirtualization interface. This only does
2027anything if the kernel is configured to use the Book 3S HV style of
2028virtualization. Otherwise the capability doesn't exist and the ioctl
2029returns an ENOTTY error. The rest of this description assumes Book 3S
2030HV.
2031
2032There must be no vcpus running when this ioctl is called; if there
2033are, it will do nothing and return an EBUSY error.
2034
2035The parameter is a pointer to a 32-bit unsigned integer variable
2036containing the order (log base 2) of the desired size of the hash
2037table, which must be between 18 and 46. On successful return from the
2038ioctl, it will have been updated with the order of the hash table that
2039was allocated.
2040
2041If no hash table has been allocated when any vcpu is asked to run
2042(with the KVM_RUN ioctl), the host kernel will allocate a
2043default-sized hash table (16 MB).
2044
2045If this ioctl is called when a hash table has already been allocated,
2046the kernel will clear out the existing hash table (zero all HPTEs) and
2047return the hash table order in the parameter. (If the guest is using
2048the virtualized real-mode area (VRMA) facility, the kernel will
2049re-create the VMRA HPTEs on the next KVM_RUN of any vcpu.)
2050
Cornelia Huck416ad652012-10-02 16:25:37 +020020514.77 KVM_S390_INTERRUPT
2052
2053Capability: basic
2054Architectures: s390
2055Type: vm ioctl, vcpu ioctl
2056Parameters: struct kvm_s390_interrupt (in)
2057Returns: 0 on success, -1 on error
2058
2059Allows to inject an interrupt to the guest. Interrupts can be floating
2060(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.
2061
2062Interrupt parameters are passed via kvm_s390_interrupt:
2063
2064struct kvm_s390_interrupt {
2065 __u32 type;
2066 __u32 parm;
2067 __u64 parm64;
2068};
2069
2070type can be one of the following:
2071
2072KVM_S390_SIGP_STOP (vcpu) - sigp restart
2073KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm
2074KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm
2075KVM_S390_RESTART (vcpu) - restart
2076KVM_S390_INT_VIRTIO (vm) - virtio external interrupt; external interrupt
2077 parameters in parm and parm64
2078KVM_S390_INT_SERVICE (vm) - sclp external interrupt; sclp parameter in parm
2079KVM_S390_INT_EMERGENCY (vcpu) - sigp emergency; source cpu in parm
2080KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm
2081
2082Note that the vcpu ioctl is asynchronous to vcpu execution.
2083
Paul Mackerrasa2932922012-11-19 22:57:20 +000020844.78 KVM_PPC_GET_HTAB_FD
2085
2086Capability: KVM_CAP_PPC_HTAB_FD
2087Architectures: powerpc
2088Type: vm ioctl
2089Parameters: Pointer to struct kvm_get_htab_fd (in)
2090Returns: file descriptor number (>= 0) on success, -1 on error
2091
2092This returns a file descriptor that can be used either to read out the
2093entries in the guest's hashed page table (HPT), or to write entries to
2094initialize the HPT. The returned fd can only be written to if the
2095KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
2096can only be read if that bit is clear. The argument struct looks like
2097this:
2098
2099/* For KVM_PPC_GET_HTAB_FD */
2100struct kvm_get_htab_fd {
2101 __u64 flags;
2102 __u64 start_index;
2103 __u64 reserved[2];
2104};
2105
2106/* Values for kvm_get_htab_fd.flags */
2107#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
2108#define KVM_GET_HTAB_WRITE ((__u64)0x2)
2109
2110The `start_index' field gives the index in the HPT of the entry at
2111which to start reading. It is ignored when writing.
2112
2113Reads on the fd will initially supply information about all
2114"interesting" HPT entries. Interesting entries are those with the
2115bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise
2116all entries. When the end of the HPT is reached, the read() will
2117return. If read() is called again on the fd, it will start again from
2118the beginning of the HPT, but will only return HPT entries that have
2119changed since they were last read.
2120
2121Data read or written is structured as a header (8 bytes) followed by a
2122series of valid HPT entries (16 bytes) each. The header indicates how
2123many valid HPT entries there are and how many invalid entries follow
2124the valid entries. The invalid entries are not represented explicitly
2125in the stream. The header format is:
2126
2127struct kvm_get_htab_header {
2128 __u32 index;
2129 __u16 n_valid;
2130 __u16 n_invalid;
2131};
2132
2133Writes to the fd create HPT entries starting at the index given in the
2134header; first `n_valid' valid entries with contents from the data
2135written, then `n_invalid' invalid entries, invalidating any previously
2136valid entries found.
2137
Alex Williamsonf36992e2012-06-29 09:56:16 -06002138
Christoffer Dall749cf76c2013-01-20 18:28:06 -050021394.77 KVM_ARM_VCPU_INIT
2140
2141Capability: basic
2142Architectures: arm
2143Type: vcpu ioctl
2144Parameters: struct struct kvm_vcpu_init (in)
2145Returns: 0 on success; -1 on error
2146Errors:
2147  EINVAL:    the target is unknown, or the combination of features is invalid.
2148  ENOENT:    a features bit specified is unknown.
2149
2150This tells KVM what type of CPU to present to the guest, and what
2151optional features it should have.  This will cause a reset of the cpu
2152registers to their initial values.  If this is not called, KVM_RUN will
2153return ENOEXEC for that vcpu.
2154
2155Note that because some registers reflect machine topology, all vcpus
2156should be created before this ioctl is invoked.
2157
2158
21594.78 KVM_GET_REG_LIST
2160
2161Capability: basic
2162Architectures: arm
2163Type: vcpu ioctl
2164Parameters: struct kvm_reg_list (in/out)
2165Returns: 0 on success; -1 on error
2166Errors:
2167  E2BIG:     the reg index list is too big to fit in the array specified by
2168             the user (the number required will be written into n).
2169
2170struct kvm_reg_list {
2171 __u64 n; /* number of registers in reg[] */
2172 __u64 reg[0];
2173};
2174
2175This ioctl returns the guest registers that are supported for the
2176KVM_GET_ONE_REG/KVM_SET_ONE_REG calls.
2177
2178
Avi Kivity9c1b96e2009-06-09 12:37:58 +030021795. The kvm_run structure
Jan Kiszka414fa982012-04-24 16:40:15 +02002180------------------------
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002181
2182Application code obtains a pointer to the kvm_run structure by
2183mmap()ing a vcpu fd. From that point, application code can control
2184execution by changing fields in kvm_run prior to calling the KVM_RUN
2185ioctl, and obtain information about the reason KVM_RUN returned by
2186looking up structure members.
2187
2188struct kvm_run {
2189 /* in */
2190 __u8 request_interrupt_window;
2191
2192Request that KVM_RUN return when it becomes possible to inject external
2193interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
2194
2195 __u8 padding1[7];
2196
2197 /* out */
2198 __u32 exit_reason;
2199
2200When KVM_RUN has returned successfully (return value 0), this informs
2201application code why KVM_RUN has returned. Allowable values for this
2202field are detailed below.
2203
2204 __u8 ready_for_interrupt_injection;
2205
2206If request_interrupt_window has been specified, this field indicates
2207an interrupt can be injected now with KVM_INTERRUPT.
2208
2209 __u8 if_flag;
2210
2211The value of the current interrupt flag. Only valid if in-kernel
2212local APIC is not used.
2213
2214 __u8 padding2[2];
2215
2216 /* in (pre_kvm_run), out (post_kvm_run) */
2217 __u64 cr8;
2218
2219The value of the cr8 register. Only valid if in-kernel local APIC is
2220not used. Both input and output.
2221
2222 __u64 apic_base;
2223
2224The value of the APIC BASE msr. Only valid if in-kernel local
2225APIC is not used. Both input and output.
2226
2227 union {
2228 /* KVM_EXIT_UNKNOWN */
2229 struct {
2230 __u64 hardware_exit_reason;
2231 } hw;
2232
2233If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
2234reasons. Further architecture-specific information is available in
2235hardware_exit_reason.
2236
2237 /* KVM_EXIT_FAIL_ENTRY */
2238 struct {
2239 __u64 hardware_entry_failure_reason;
2240 } fail_entry;
2241
2242If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
2243to unknown reasons. Further architecture-specific information is
2244available in hardware_entry_failure_reason.
2245
2246 /* KVM_EXIT_EXCEPTION */
2247 struct {
2248 __u32 exception;
2249 __u32 error_code;
2250 } ex;
2251
2252Unused.
2253
2254 /* KVM_EXIT_IO */
2255 struct {
2256#define KVM_EXIT_IO_IN 0
2257#define KVM_EXIT_IO_OUT 1
2258 __u8 direction;
2259 __u8 size; /* bytes */
2260 __u16 port;
2261 __u32 count;
2262 __u64 data_offset; /* relative to kvm_run start */
2263 } io;
2264
Wu Fengguang2044892d2009-12-24 09:04:16 +08002265If exit_reason is KVM_EXIT_IO, then the vcpu has
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002266executed a port I/O instruction which could not be satisfied by kvm.
2267data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
2268where kvm expects application code to place the data for the next
Wu Fengguang2044892d2009-12-24 09:04:16 +08002269KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002270
2271 struct {
2272 struct kvm_debug_exit_arch arch;
2273 } debug;
2274
2275Unused.
2276
2277 /* KVM_EXIT_MMIO */
2278 struct {
2279 __u64 phys_addr;
2280 __u8 data[8];
2281 __u32 len;
2282 __u8 is_write;
2283 } mmio;
2284
Wu Fengguang2044892d2009-12-24 09:04:16 +08002285If exit_reason is KVM_EXIT_MMIO, then the vcpu has
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002286executed a memory-mapped I/O instruction which could not be satisfied
2287by kvm. The 'data' member contains the written data if 'is_write' is
2288true, and should be filled by application code otherwise.
2289
Alexander Graf686de182012-10-07 15:22:59 +02002290NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_DCR
2291 and KVM_EXIT_PAPR the corresponding
Alexander Grafad0a0482010-03-24 21:48:30 +01002292operations are complete (and guest state is consistent) only after userspace
2293has re-entered the kernel with KVM_RUN. The kernel side will first finish
Marcelo Tosatti67961342010-02-13 16:10:26 -02002294incomplete operations and then check for pending signals. Userspace
2295can re-enter the guest with an unmasked signal pending to complete
2296pending operations.
2297
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002298 /* KVM_EXIT_HYPERCALL */
2299 struct {
2300 __u64 nr;
2301 __u64 args[6];
2302 __u64 ret;
2303 __u32 longmode;
2304 __u32 pad;
2305 } hypercall;
2306
Avi Kivity647dc492010-04-01 14:39:21 +03002307Unused. This was once used for 'hypercall to userspace'. To implement
2308such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
2309Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002310
2311 /* KVM_EXIT_TPR_ACCESS */
2312 struct {
2313 __u64 rip;
2314 __u32 is_write;
2315 __u32 pad;
2316 } tpr_access;
2317
2318To be documented (KVM_TPR_ACCESS_REPORTING).
2319
2320 /* KVM_EXIT_S390_SIEIC */
2321 struct {
2322 __u8 icptcode;
2323 __u64 mask; /* psw upper half */
2324 __u64 addr; /* psw lower half */
2325 __u16 ipa;
2326 __u32 ipb;
2327 } s390_sieic;
2328
2329s390 specific.
2330
2331 /* KVM_EXIT_S390_RESET */
2332#define KVM_S390_RESET_POR 1
2333#define KVM_S390_RESET_CLEAR 2
2334#define KVM_S390_RESET_SUBSYSTEM 4
2335#define KVM_S390_RESET_CPU_INIT 8
2336#define KVM_S390_RESET_IPL 16
2337 __u64 s390_reset_flags;
2338
2339s390 specific.
2340
Carsten Ottee168bf82012-01-04 10:25:22 +01002341 /* KVM_EXIT_S390_UCONTROL */
2342 struct {
2343 __u64 trans_exc_code;
2344 __u32 pgm_code;
2345 } s390_ucontrol;
2346
2347s390 specific. A page fault has occurred for a user controlled virtual
2348machine (KVM_VM_S390_UNCONTROL) on it's host page table that cannot be
2349resolved by the kernel.
2350The program code and the translation exception code that were placed
2351in the cpu's lowcore are presented here as defined by the z Architecture
2352Principles of Operation Book in the Chapter for Dynamic Address Translation
2353(DAT)
2354
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002355 /* KVM_EXIT_DCR */
2356 struct {
2357 __u32 dcrn;
2358 __u32 data;
2359 __u8 is_write;
2360 } dcr;
2361
2362powerpc specific.
2363
Alexander Grafad0a0482010-03-24 21:48:30 +01002364 /* KVM_EXIT_OSI */
2365 struct {
2366 __u64 gprs[32];
2367 } osi;
2368
2369MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
2370hypercalls and exit with this exit struct that contains all the guest gprs.
2371
2372If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
2373Userspace can now handle the hypercall and when it's done modify the gprs as
2374necessary. Upon guest entry all guest GPRs will then be replaced by the values
2375in this struct.
2376
Paul Mackerrasde56a942011-06-29 00:21:34 +00002377 /* KVM_EXIT_PAPR_HCALL */
2378 struct {
2379 __u64 nr;
2380 __u64 ret;
2381 __u64 args[9];
2382 } papr_hcall;
2383
2384This is used on 64-bit PowerPC when emulating a pSeries partition,
2385e.g. with the 'pseries' machine type in qemu. It occurs when the
2386guest does a hypercall using the 'sc 1' instruction. The 'nr' field
2387contains the hypercall number (from the guest R3), and 'args' contains
2388the arguments (from the guest R4 - R12). Userspace should put the
2389return code in 'ret' and any extra returned values in args[].
2390The possible hypercalls are defined in the Power Architecture Platform
2391Requirements (PAPR) document available from www.power.org (free
2392developer registration required to access it).
2393
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002394 /* Fix the size of the union. */
2395 char padding[256];
2396 };
Christian Borntraegerb9e5dc82012-01-11 11:20:30 +01002397
2398 /*
2399 * shared registers between kvm and userspace.
2400 * kvm_valid_regs specifies the register classes set by the host
2401 * kvm_dirty_regs specified the register classes dirtied by userspace
2402 * struct kvm_sync_regs is architecture specific, as well as the
2403 * bits for kvm_valid_regs and kvm_dirty_regs
2404 */
2405 __u64 kvm_valid_regs;
2406 __u64 kvm_dirty_regs;
2407 union {
2408 struct kvm_sync_regs regs;
2409 char padding[1024];
2410 } s;
2411
2412If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access
2413certain guest registers without having to call SET/GET_*REGS. Thus we can
2414avoid some system call overhead if userspace has to handle the exit.
2415Userspace can query the validity of the structure by checking
2416kvm_valid_regs for specific bits. These bits are architecture specific
2417and usually define the validity of a groups of registers. (e.g. one bit
2418 for general purpose registers)
2419
Avi Kivity9c1b96e2009-06-09 12:37:58 +03002420};
Alexander Graf821246a2011-08-31 10:58:55 +02002421
Jan Kiszka414fa982012-04-24 16:40:15 +02002422
Alexander Graf821246a2011-08-31 10:58:55 +020024236. Capabilities that can be enabled
Jan Kiszka414fa982012-04-24 16:40:15 +02002424-----------------------------------
Alexander Graf821246a2011-08-31 10:58:55 +02002425
2426There are certain capabilities that change the behavior of the virtual CPU when
2427enabled. To enable them, please see section 4.37. Below you can find a list of
2428capabilities and what their effect on the vCPU is when enabling them.
2429
2430The following information is provided along with the description:
2431
2432 Architectures: which instruction set architectures provide this ioctl.
2433 x86 includes both i386 and x86_64.
2434
2435 Parameters: what parameters are accepted by the capability.
2436
2437 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
2438 are not detailed, but errors with specific meanings are.
2439
Jan Kiszka414fa982012-04-24 16:40:15 +02002440
Alexander Graf821246a2011-08-31 10:58:55 +020024416.1 KVM_CAP_PPC_OSI
2442
2443Architectures: ppc
2444Parameters: none
2445Returns: 0 on success; -1 on error
2446
2447This capability enables interception of OSI hypercalls that otherwise would
2448be treated as normal system calls to be injected into the guest. OSI hypercalls
2449were invented by Mac-on-Linux to have a standardized communication mechanism
2450between the guest and the host.
2451
2452When this capability is enabled, KVM_EXIT_OSI can occur.
2453
Jan Kiszka414fa982012-04-24 16:40:15 +02002454
Alexander Graf821246a2011-08-31 10:58:55 +020024556.2 KVM_CAP_PPC_PAPR
2456
2457Architectures: ppc
2458Parameters: none
2459Returns: 0 on success; -1 on error
2460
2461This capability enables interception of PAPR hypercalls. PAPR hypercalls are
2462done using the hypercall instruction "sc 1".
2463
2464It also sets the guest privilege level to "supervisor" mode. Usually the guest
2465runs in "hypervisor" privilege mode with a few missing features.
2466
2467In addition to the above, it changes the semantics of SDR1. In this mode, the
2468HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
2469HTAB invisible to the guest.
2470
2471When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
Scott Wooddc83b8b2011-08-18 15:25:21 -05002472
Jan Kiszka414fa982012-04-24 16:40:15 +02002473
Scott Wooddc83b8b2011-08-18 15:25:21 -050024746.3 KVM_CAP_SW_TLB
2475
2476Architectures: ppc
2477Parameters: args[0] is the address of a struct kvm_config_tlb
2478Returns: 0 on success; -1 on error
2479
2480struct kvm_config_tlb {
2481 __u64 params;
2482 __u64 array;
2483 __u32 mmu_type;
2484 __u32 array_len;
2485};
2486
2487Configures the virtual CPU's TLB array, establishing a shared memory area
2488between userspace and KVM. The "params" and "array" fields are userspace
2489addresses of mmu-type-specific data structures. The "array_len" field is an
2490safety mechanism, and should be set to the size in bytes of the memory that
2491userspace has reserved for the array. It must be at least the size dictated
2492by "mmu_type" and "params".
2493
2494While KVM_RUN is active, the shared region is under control of KVM. Its
2495contents are undefined, and any modification by userspace results in
2496boundedly undefined behavior.
2497
2498On return from KVM_RUN, the shared region will reflect the current state of
2499the guest's TLB. If userspace makes any changes, it must call KVM_DIRTY_TLB
2500to tell KVM which entries have been changed, prior to calling KVM_RUN again
2501on this vcpu.
2502
2503For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
2504 - The "params" field is of type "struct kvm_book3e_206_tlb_params".
2505 - The "array" field points to an array of type "struct
2506 kvm_book3e_206_tlb_entry".
2507 - The array consists of all entries in the first TLB, followed by all
2508 entries in the second TLB.
2509 - Within a TLB, entries are ordered first by increasing set number. Within a
2510 set, entries are ordered by way (increasing ESEL).
2511 - The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1)
2512 where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value.
2513 - The tsize field of mas1 shall be set to 4K on TLB0, even though the
2514 hardware ignores this value for TLB0.