]> git.proxmox.com Git - mirror_ubuntu-jammy-kernel.git/blame - Documentation/virtual/kvm/api.txt
KVM: MIPS: Extend counters & events for VZ GExcCodes
[mirror_ubuntu-jammy-kernel.git] / Documentation / virtual / kvm / api.txt
CommitLineData
9c1b96e3
AK
1The Definitive KVM (Kernel-based Virtual Machine) API Documentation
2===================================================================
3
41. General description
414fa985 5----------------------
9c1b96e3
AK
6
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
414fa985 27
2044892d 282. File descriptors
414fa985 29-------------------
9c1b96e3
AK
30
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
2044892d 34handle will create a VM file descriptor which can be used to issue VM
9c1b96e3
AK
35ioctls. 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
414fa985 47
9c1b96e3 483. Extensions
414fa985 49-------------
9c1b96e3
AK
50
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
c9f3f2d8 56The extension mechanism is not based on the Linux version number.
9c1b96e3
AK
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
414fa985 61
9c1b96e3 624. API description
414fa985 63------------------
9c1b96e3
AK
64
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
7f05db6a 71 API version 12 (see section 4.1), a KVM_CAP_xyz constant, which
9c1b96e3 72 means availability needs to be checked with KVM_CHECK_EXTENSION
7f05db6a
MT
73 (see section 4.4), or 'none' which means that while not all kernels
74 support this ioctl, there's no capability bit to check its
75 availability: for kernels that don't support the ioctl,
76 the ioctl returns -ENOTTY.
9c1b96e3
AK
77
78 Architectures: which instruction set architectures provide this ioctl.
79 x86 includes both i386 and x86_64.
80
81 Type: system, vm, or vcpu.
82
83 Parameters: what parameters are accepted by the ioctl.
84
85 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
86 are not detailed, but errors with specific meanings are.
87
414fa985 88
9c1b96e3
AK
894.1 KVM_GET_API_VERSION
90
91Capability: basic
92Architectures: all
93Type: system ioctl
94Parameters: none
95Returns: the constant KVM_API_VERSION (=12)
96
97This identifies the API version as the stable kvm API. It is not
98expected that this number will change. However, Linux 2.6.20 and
992.6.21 report earlier versions; these are not documented and not
100supported. Applications should refuse to run if KVM_GET_API_VERSION
101returns a value other than 12. If this check passes, all ioctls
102described as 'basic' will be available.
103
414fa985 104
9c1b96e3
AK
1054.2 KVM_CREATE_VM
106
107Capability: basic
108Architectures: all
109Type: system ioctl
e08b9637 110Parameters: machine type identifier (KVM_VM_*)
9c1b96e3
AK
111Returns: a VM fd that can be used to control the new virtual machine.
112
113The new VM has no virtual cpus and no memory. An mmap() of a VM fd
114will access the virtual machine's physical address space; offset zero
115corresponds to guest physical address zero. Use of mmap() on a VM fd
116is discouraged if userspace memory allocation (KVM_CAP_USER_MEMORY) is
117available.
e08b9637
CO
118You most certainly want to use 0 as machine type.
119
120In order to create user controlled virtual machines on S390, check
121KVM_CAP_S390_UCONTROL and use the flag KVM_VM_S390_UCONTROL as
122privileged user (CAP_SYS_ADMIN).
9c1b96e3 123
414fa985 124
9c1b96e3
AK
1254.3 KVM_GET_MSR_INDEX_LIST
126
127Capability: basic
128Architectures: x86
129Type: system
130Parameters: struct kvm_msr_list (in/out)
131Returns: 0 on success; -1 on error
132Errors:
133 E2BIG: the msr index list is to be to fit in the array specified by
134 the user.
135
136struct kvm_msr_list {
137 __u32 nmsrs; /* number of msrs in entries */
138 __u32 indices[0];
139};
140
141This ioctl returns the guest msrs that are supported. The list varies
142by kvm version and host processor, but does not change otherwise. The
143user fills in the size of the indices array in nmsrs, and in return
144kvm adjusts nmsrs to reflect the actual number of msrs and fills in
145the indices array with their numbers.
146
2e2602ca
AK
147Note: if kvm indicates supports MCE (KVM_CAP_MCE), then the MCE bank MSRs are
148not returned in the MSR list, as different vcpus can have a different number
149of banks, as set via the KVM_X86_SETUP_MCE ioctl.
150
414fa985 151
9c1b96e3
AK
1524.4 KVM_CHECK_EXTENSION
153
92b591a4 154Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl
9c1b96e3 155Architectures: all
92b591a4 156Type: system ioctl, vm ioctl
9c1b96e3
AK
157Parameters: extension identifier (KVM_CAP_*)
158Returns: 0 if unsupported; 1 (or some other positive integer) if supported
159
160The API allows the application to query about extensions to the core
161kvm API. Userspace passes an extension identifier (an integer) and
162receives an integer that describes the extension availability.
163Generally 0 means no and 1 means yes, but some extensions may report
164additional information in the integer return value.
165
92b591a4
AG
166Based on their initialization different VMs may have different capabilities.
167It is thus encouraged to use the vm ioctl to query for capabilities (available
168with KVM_CAP_CHECK_EXTENSION_VM on the vm fd)
414fa985 169
9c1b96e3
AK
1704.5 KVM_GET_VCPU_MMAP_SIZE
171
172Capability: basic
173Architectures: all
174Type: system ioctl
175Parameters: none
176Returns: size of vcpu mmap area, in bytes
177
178The KVM_RUN ioctl (cf.) communicates with userspace via a shared
179memory region. This ioctl returns the size of that region. See the
180KVM_RUN documentation for details.
181
414fa985 182
9c1b96e3
AK
1834.6 KVM_SET_MEMORY_REGION
184
185Capability: basic
186Architectures: all
187Type: vm ioctl
188Parameters: struct kvm_memory_region (in)
189Returns: 0 on success, -1 on error
190
b74a07be 191This ioctl is obsolete and has been removed.
9c1b96e3 192
414fa985 193
68ba6974 1944.7 KVM_CREATE_VCPU
9c1b96e3
AK
195
196Capability: basic
197Architectures: all
198Type: vm ioctl
199Parameters: vcpu id (apic id on x86)
200Returns: vcpu fd on success, -1 on error
201
0b1b1dfd
GK
202This API adds a vcpu to a virtual machine. No more than max_vcpus may be added.
203The vcpu id is an integer in the range [0, max_vcpu_id).
8c3ba334
SL
204
205The recommended max_vcpus value can be retrieved using the KVM_CAP_NR_VCPUS of
206the KVM_CHECK_EXTENSION ioctl() at run-time.
207The maximum possible value for max_vcpus can be retrieved using the
208KVM_CAP_MAX_VCPUS of the KVM_CHECK_EXTENSION ioctl() at run-time.
209
76d25402
PE
210If the KVM_CAP_NR_VCPUS does not exist, you should assume that max_vcpus is 4
211cpus max.
8c3ba334
SL
212If the KVM_CAP_MAX_VCPUS does not exist, you should assume that max_vcpus is
213same as the value returned from KVM_CAP_NR_VCPUS.
9c1b96e3 214
0b1b1dfd
GK
215The maximum possible value for max_vcpu_id can be retrieved using the
216KVM_CAP_MAX_VCPU_ID of the KVM_CHECK_EXTENSION ioctl() at run-time.
217
218If the KVM_CAP_MAX_VCPU_ID does not exist, you should assume that max_vcpu_id
219is the same as the value returned from KVM_CAP_MAX_VCPUS.
220
371fefd6
PM
221On powerpc using book3s_hv mode, the vcpus are mapped onto virtual
222threads in one or more virtual CPU cores. (This is because the
223hardware requires all the hardware threads in a CPU core to be in the
224same partition.) The KVM_CAP_PPC_SMT capability indicates the number
36442687
AK
225of vcpus per virtual core (vcore). The vcore id is obtained by
226dividing the vcpu id by the number of vcpus per vcore. The vcpus in a
227given vcore will always be in the same physical core as each other
228(though that might be a different physical core from time to time).
229Userspace can control the threading (SMT) mode of the guest by its
230allocation of vcpu ids. For example, if userspace wants
231single-threaded guest vcpus, it should make all vcpu ids be a multiple
232of the number of vcpus per vcore.
233
5b1c1493
CO
234For virtual cpus that have been created with S390 user controlled virtual
235machines, the resulting vcpu fd can be memory mapped at page offset
236KVM_S390_SIE_PAGE_OFFSET in order to obtain a memory map of the virtual
237cpu's hardware control block.
238
414fa985 239
68ba6974 2404.8 KVM_GET_DIRTY_LOG (vm ioctl)
9c1b96e3
AK
241
242Capability: basic
243Architectures: x86
244Type: vm ioctl
245Parameters: struct kvm_dirty_log (in/out)
246Returns: 0 on success, -1 on error
247
248/* for KVM_GET_DIRTY_LOG */
249struct kvm_dirty_log {
250 __u32 slot;
251 __u32 padding;
252 union {
253 void __user *dirty_bitmap; /* one bit per page */
254 __u64 padding;
255 };
256};
257
258Given a memory slot, return a bitmap containing any pages dirtied
259since the last call to this ioctl. Bit 0 is the first page in the
260memory slot. Ensure the entire structure is cleared to avoid padding
261issues.
262
f481b069
PB
263If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 specifies
264the address space for which you want to return the dirty bitmap.
265They must be less than the value that KVM_CHECK_EXTENSION returns for
266the KVM_CAP_MULTI_ADDRESS_SPACE capability.
267
414fa985 268
68ba6974 2694.9 KVM_SET_MEMORY_ALIAS
9c1b96e3
AK
270
271Capability: basic
272Architectures: x86
273Type: vm ioctl
274Parameters: struct kvm_memory_alias (in)
275Returns: 0 (success), -1 (error)
276
a1f4d395 277This ioctl is obsolete and has been removed.
9c1b96e3 278
414fa985 279
68ba6974 2804.10 KVM_RUN
9c1b96e3
AK
281
282Capability: basic
283Architectures: all
284Type: vcpu ioctl
285Parameters: none
286Returns: 0 on success, -1 on error
287Errors:
288 EINTR: an unmasked signal is pending
289
290This ioctl is used to run a guest virtual cpu. While there are no
291explicit parameters, there is an implicit parameter block that can be
292obtained by mmap()ing the vcpu fd at offset 0, with the size given by
293KVM_GET_VCPU_MMAP_SIZE. The parameter block is formatted as a 'struct
294kvm_run' (see below).
295
414fa985 296
68ba6974 2974.11 KVM_GET_REGS
9c1b96e3
AK
298
299Capability: basic
379e04c7 300Architectures: all except ARM, arm64
9c1b96e3
AK
301Type: vcpu ioctl
302Parameters: struct kvm_regs (out)
303Returns: 0 on success, -1 on error
304
305Reads the general purpose registers from the vcpu.
306
307/* x86 */
308struct kvm_regs {
309 /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
310 __u64 rax, rbx, rcx, rdx;
311 __u64 rsi, rdi, rsp, rbp;
312 __u64 r8, r9, r10, r11;
313 __u64 r12, r13, r14, r15;
314 __u64 rip, rflags;
315};
316
c2d2c21b
JH
317/* mips */
318struct kvm_regs {
319 /* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
320 __u64 gpr[32];
321 __u64 hi;
322 __u64 lo;
323 __u64 pc;
324};
325
414fa985 326
68ba6974 3274.12 KVM_SET_REGS
9c1b96e3
AK
328
329Capability: basic
379e04c7 330Architectures: all except ARM, arm64
9c1b96e3
AK
331Type: vcpu ioctl
332Parameters: struct kvm_regs (in)
333Returns: 0 on success, -1 on error
334
335Writes the general purpose registers into the vcpu.
336
337See KVM_GET_REGS for the data structure.
338
414fa985 339
68ba6974 3404.13 KVM_GET_SREGS
9c1b96e3
AK
341
342Capability: basic
5ce941ee 343Architectures: x86, ppc
9c1b96e3
AK
344Type: vcpu ioctl
345Parameters: struct kvm_sregs (out)
346Returns: 0 on success, -1 on error
347
348Reads special registers from the vcpu.
349
350/* x86 */
351struct kvm_sregs {
352 struct kvm_segment cs, ds, es, fs, gs, ss;
353 struct kvm_segment tr, ldt;
354 struct kvm_dtable gdt, idt;
355 __u64 cr0, cr2, cr3, cr4, cr8;
356 __u64 efer;
357 __u64 apic_base;
358 __u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
359};
360
68e2ffed 361/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */
5ce941ee 362
9c1b96e3
AK
363interrupt_bitmap is a bitmap of pending external interrupts. At most
364one bit may be set. This interrupt has been acknowledged by the APIC
365but not yet injected into the cpu core.
366
414fa985 367
68ba6974 3684.14 KVM_SET_SREGS
9c1b96e3
AK
369
370Capability: basic
5ce941ee 371Architectures: x86, ppc
9c1b96e3
AK
372Type: vcpu ioctl
373Parameters: struct kvm_sregs (in)
374Returns: 0 on success, -1 on error
375
376Writes special registers into the vcpu. See KVM_GET_SREGS for the
377data structures.
378
414fa985 379
68ba6974 3804.15 KVM_TRANSLATE
9c1b96e3
AK
381
382Capability: basic
383Architectures: x86
384Type: vcpu ioctl
385Parameters: struct kvm_translation (in/out)
386Returns: 0 on success, -1 on error
387
388Translates a virtual address according to the vcpu's current address
389translation mode.
390
391struct kvm_translation {
392 /* in */
393 __u64 linear_address;
394
395 /* out */
396 __u64 physical_address;
397 __u8 valid;
398 __u8 writeable;
399 __u8 usermode;
400 __u8 pad[5];
401};
402
414fa985 403
68ba6974 4044.16 KVM_INTERRUPT
9c1b96e3
AK
405
406Capability: basic
c2d2c21b 407Architectures: x86, ppc, mips
9c1b96e3
AK
408Type: vcpu ioctl
409Parameters: struct kvm_interrupt (in)
1c1a9ce9 410Returns: 0 on success, negative on failure.
9c1b96e3 411
1c1a9ce9 412Queues a hardware interrupt vector to be injected.
9c1b96e3
AK
413
414/* for KVM_INTERRUPT */
415struct kvm_interrupt {
416 /* in */
417 __u32 irq;
418};
419
6f7a2bd4
AG
420X86:
421
1c1a9ce9
SR
422Returns: 0 on success,
423 -EEXIST if an interrupt is already enqueued
424 -EINVAL the the irq number is invalid
425 -ENXIO if the PIC is in the kernel
426 -EFAULT if the pointer is invalid
427
428Note 'irq' is an interrupt vector, not an interrupt pin or line. This
429ioctl is useful if the in-kernel PIC is not used.
9c1b96e3 430
6f7a2bd4
AG
431PPC:
432
433Queues an external interrupt to be injected. This ioctl is overleaded
434with 3 different irq values:
435
436a) KVM_INTERRUPT_SET
437
438 This injects an edge type external interrupt into the guest once it's ready
439 to receive interrupts. When injected, the interrupt is done.
440
441b) KVM_INTERRUPT_UNSET
442
443 This unsets any pending interrupt.
444
445 Only available with KVM_CAP_PPC_UNSET_IRQ.
446
447c) KVM_INTERRUPT_SET_LEVEL
448
449 This injects a level type external interrupt into the guest context. The
450 interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
451 is triggered.
452
453 Only available with KVM_CAP_PPC_IRQ_LEVEL.
454
455Note that any value for 'irq' other than the ones stated above is invalid
456and incurs unexpected behavior.
457
c2d2c21b
JH
458MIPS:
459
460Queues an external interrupt to be injected into the virtual CPU. A negative
461interrupt number dequeues the interrupt.
462
414fa985 463
68ba6974 4644.17 KVM_DEBUG_GUEST
9c1b96e3
AK
465
466Capability: basic
467Architectures: none
468Type: vcpu ioctl
469Parameters: none)
470Returns: -1 on error
471
472Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.
473
414fa985 474
68ba6974 4754.18 KVM_GET_MSRS
9c1b96e3
AK
476
477Capability: basic
478Architectures: x86
479Type: vcpu ioctl
480Parameters: struct kvm_msrs (in/out)
481Returns: 0 on success, -1 on error
482
483Reads model-specific registers from the vcpu. Supported msr indices can
484be obtained using KVM_GET_MSR_INDEX_LIST.
485
486struct kvm_msrs {
487 __u32 nmsrs; /* number of msrs in entries */
488 __u32 pad;
489
490 struct kvm_msr_entry entries[0];
491};
492
493struct kvm_msr_entry {
494 __u32 index;
495 __u32 reserved;
496 __u64 data;
497};
498
499Application code should set the 'nmsrs' member (which indicates the
500size of the entries array) and the 'index' member of each array entry.
501kvm will fill in the 'data' member.
502
414fa985 503
68ba6974 5044.19 KVM_SET_MSRS
9c1b96e3
AK
505
506Capability: basic
507Architectures: x86
508Type: vcpu ioctl
509Parameters: struct kvm_msrs (in)
510Returns: 0 on success, -1 on error
511
512Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
513data structures.
514
515Application code should set the 'nmsrs' member (which indicates the
516size of the entries array), and the 'index' and 'data' members of each
517array entry.
518
414fa985 519
68ba6974 5204.20 KVM_SET_CPUID
9c1b96e3
AK
521
522Capability: basic
523Architectures: x86
524Type: vcpu ioctl
525Parameters: struct kvm_cpuid (in)
526Returns: 0 on success, -1 on error
527
528Defines the vcpu responses to the cpuid instruction. Applications
529should use the KVM_SET_CPUID2 ioctl if available.
530
531
532struct kvm_cpuid_entry {
533 __u32 function;
534 __u32 eax;
535 __u32 ebx;
536 __u32 ecx;
537 __u32 edx;
538 __u32 padding;
539};
540
541/* for KVM_SET_CPUID */
542struct kvm_cpuid {
543 __u32 nent;
544 __u32 padding;
545 struct kvm_cpuid_entry entries[0];
546};
547
414fa985 548
68ba6974 5494.21 KVM_SET_SIGNAL_MASK
9c1b96e3
AK
550
551Capability: basic
572e0929 552Architectures: all
9c1b96e3
AK
553Type: vcpu ioctl
554Parameters: struct kvm_signal_mask (in)
555Returns: 0 on success, -1 on error
556
557Defines which signals are blocked during execution of KVM_RUN. This
558signal mask temporarily overrides the threads signal mask. Any
559unblocked signal received (except SIGKILL and SIGSTOP, which retain
560their traditional behaviour) will cause KVM_RUN to return with -EINTR.
561
562Note the signal will only be delivered if not blocked by the original
563signal mask.
564
565/* for KVM_SET_SIGNAL_MASK */
566struct kvm_signal_mask {
567 __u32 len;
568 __u8 sigset[0];
569};
570
414fa985 571
68ba6974 5724.22 KVM_GET_FPU
9c1b96e3
AK
573
574Capability: basic
575Architectures: x86
576Type: vcpu ioctl
577Parameters: struct kvm_fpu (out)
578Returns: 0 on success, -1 on error
579
580Reads the floating point state from the vcpu.
581
582/* for KVM_GET_FPU and KVM_SET_FPU */
583struct kvm_fpu {
584 __u8 fpr[8][16];
585 __u16 fcw;
586 __u16 fsw;
587 __u8 ftwx; /* in fxsave format */
588 __u8 pad1;
589 __u16 last_opcode;
590 __u64 last_ip;
591 __u64 last_dp;
592 __u8 xmm[16][16];
593 __u32 mxcsr;
594 __u32 pad2;
595};
596
414fa985 597
68ba6974 5984.23 KVM_SET_FPU
9c1b96e3
AK
599
600Capability: basic
601Architectures: x86
602Type: vcpu ioctl
603Parameters: struct kvm_fpu (in)
604Returns: 0 on success, -1 on error
605
606Writes the floating point state to the vcpu.
607
608/* for KVM_GET_FPU and KVM_SET_FPU */
609struct kvm_fpu {
610 __u8 fpr[8][16];
611 __u16 fcw;
612 __u16 fsw;
613 __u8 ftwx; /* in fxsave format */
614 __u8 pad1;
615 __u16 last_opcode;
616 __u64 last_ip;
617 __u64 last_dp;
618 __u8 xmm[16][16];
619 __u32 mxcsr;
620 __u32 pad2;
621};
622
414fa985 623
68ba6974 6244.24 KVM_CREATE_IRQCHIP
5dadbfd6 625
84223598 626Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390)
c32a4272 627Architectures: x86, ARM, arm64, s390
5dadbfd6
AK
628Type: vm ioctl
629Parameters: none
630Returns: 0 on success, -1 on error
631
ac3d3735
AP
632Creates an interrupt controller model in the kernel.
633On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up
634future vcpus to have a local APIC. IRQ routing for GSIs 0-15 is set to both
635PIC and IOAPIC; GSI 16-23 only go to the IOAPIC.
636On ARM/arm64, a GICv2 is created. Any other GIC versions require the usage of
637KVM_CREATE_DEVICE, which also supports creating a GICv2. Using
638KVM_CREATE_DEVICE is preferred over KVM_CREATE_IRQCHIP for GICv2.
639On s390, a dummy irq routing table is created.
84223598
CH
640
641Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled
642before KVM_CREATE_IRQCHIP can be used.
5dadbfd6 643
414fa985 644
68ba6974 6454.25 KVM_IRQ_LINE
5dadbfd6
AK
646
647Capability: KVM_CAP_IRQCHIP
c32a4272 648Architectures: x86, arm, arm64
5dadbfd6
AK
649Type: vm ioctl
650Parameters: struct kvm_irq_level
651Returns: 0 on success, -1 on error
652
653Sets the level of a GSI input to the interrupt controller model in the kernel.
86ce8535
CD
654On some architectures it is required that an interrupt controller model has
655been previously created with KVM_CREATE_IRQCHIP. Note that edge-triggered
656interrupts require the level to be set to 1 and then back to 0.
657
100943c5
GS
658On real hardware, interrupt pins can be active-low or active-high. This
659does not matter for the level field of struct kvm_irq_level: 1 always
660means active (asserted), 0 means inactive (deasserted).
661
662x86 allows the operating system to program the interrupt polarity
663(active-low/active-high) for level-triggered interrupts, and KVM used
664to consider the polarity. However, due to bitrot in the handling of
665active-low interrupts, the above convention is now valid on x86 too.
666This is signaled by KVM_CAP_X86_IOAPIC_POLARITY_IGNORED. Userspace
667should not present interrupts to the guest as active-low unless this
668capability is present (or unless it is not using the in-kernel irqchip,
669of course).
670
671
379e04c7
MZ
672ARM/arm64 can signal an interrupt either at the CPU level, or at the
673in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to
674use PPIs designated for specific cpus. The irq field is interpreted
675like this:
86ce8535
CD
676
677  bits: | 31 ... 24 | 23 ... 16 | 15 ... 0 |
678 field: | irq_type | vcpu_index | irq_id |
679
680The irq_type field has the following values:
681- irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
682- irq_type[1]: in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)
683 (the vcpu_index field is ignored)
684- irq_type[2]: in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)
685
686(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
687
100943c5 688In both cases, level is used to assert/deassert the line.
5dadbfd6
AK
689
690struct kvm_irq_level {
691 union {
692 __u32 irq; /* GSI */
693 __s32 status; /* not used for KVM_IRQ_LEVEL */
694 };
695 __u32 level; /* 0 or 1 */
696};
697
414fa985 698
68ba6974 6994.26 KVM_GET_IRQCHIP
5dadbfd6
AK
700
701Capability: KVM_CAP_IRQCHIP
c32a4272 702Architectures: x86
5dadbfd6
AK
703Type: vm ioctl
704Parameters: struct kvm_irqchip (in/out)
705Returns: 0 on success, -1 on error
706
707Reads the state of a kernel interrupt controller created with
708KVM_CREATE_IRQCHIP into a buffer provided by the caller.
709
710struct kvm_irqchip {
711 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
712 __u32 pad;
713 union {
714 char dummy[512]; /* reserving space */
715 struct kvm_pic_state pic;
716 struct kvm_ioapic_state ioapic;
717 } chip;
718};
719
414fa985 720
68ba6974 7214.27 KVM_SET_IRQCHIP
5dadbfd6
AK
722
723Capability: KVM_CAP_IRQCHIP
c32a4272 724Architectures: x86
5dadbfd6
AK
725Type: vm ioctl
726Parameters: struct kvm_irqchip (in)
727Returns: 0 on success, -1 on error
728
729Sets the state of a kernel interrupt controller created with
730KVM_CREATE_IRQCHIP from a buffer provided by the caller.
731
732struct kvm_irqchip {
733 __u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
734 __u32 pad;
735 union {
736 char dummy[512]; /* reserving space */
737 struct kvm_pic_state pic;
738 struct kvm_ioapic_state ioapic;
739 } chip;
740};
741
414fa985 742
68ba6974 7434.28 KVM_XEN_HVM_CONFIG
ffde22ac
ES
744
745Capability: KVM_CAP_XEN_HVM
746Architectures: x86
747Type: vm ioctl
748Parameters: struct kvm_xen_hvm_config (in)
749Returns: 0 on success, -1 on error
750
751Sets the MSR that the Xen HVM guest uses to initialize its hypercall
752page, and provides the starting address and size of the hypercall
753blobs in userspace. When the guest writes the MSR, kvm copies one
754page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
755memory.
756
757struct kvm_xen_hvm_config {
758 __u32 flags;
759 __u32 msr;
760 __u64 blob_addr_32;
761 __u64 blob_addr_64;
762 __u8 blob_size_32;
763 __u8 blob_size_64;
764 __u8 pad2[30];
765};
766
414fa985 767
68ba6974 7684.29 KVM_GET_CLOCK
afbcf7ab
GC
769
770Capability: KVM_CAP_ADJUST_CLOCK
771Architectures: x86
772Type: vm ioctl
773Parameters: struct kvm_clock_data (out)
774Returns: 0 on success, -1 on error
775
776Gets the current timestamp of kvmclock as seen by the current guest. In
777conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
778such as migration.
779
e3fd9a93
PB
780When KVM_CAP_ADJUST_CLOCK is passed to KVM_CHECK_EXTENSION, it returns the
781set of bits that KVM can return in struct kvm_clock_data's flag member.
782
783The only flag defined now is KVM_CLOCK_TSC_STABLE. If set, the returned
784value is the exact kvmclock value seen by all VCPUs at the instant
785when KVM_GET_CLOCK was called. If clear, the returned value is simply
786CLOCK_MONOTONIC plus a constant offset; the offset can be modified
787with KVM_SET_CLOCK. KVM will try to make all VCPUs follow this clock,
788but the exact value read by each VCPU could differ, because the host
789TSC is not stable.
790
afbcf7ab
GC
791struct kvm_clock_data {
792 __u64 clock; /* kvmclock current value */
793 __u32 flags;
794 __u32 pad[9];
795};
796
414fa985 797
68ba6974 7984.30 KVM_SET_CLOCK
afbcf7ab
GC
799
800Capability: KVM_CAP_ADJUST_CLOCK
801Architectures: x86
802Type: vm ioctl
803Parameters: struct kvm_clock_data (in)
804Returns: 0 on success, -1 on error
805
2044892d 806Sets the current timestamp of kvmclock to the value specified in its parameter.
afbcf7ab
GC
807In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
808such as migration.
809
810struct kvm_clock_data {
811 __u64 clock; /* kvmclock current value */
812 __u32 flags;
813 __u32 pad[9];
814};
815
414fa985 816
68ba6974 8174.31 KVM_GET_VCPU_EVENTS
3cfc3092
JK
818
819Capability: KVM_CAP_VCPU_EVENTS
48005f64 820Extended by: KVM_CAP_INTR_SHADOW
3cfc3092
JK
821Architectures: x86
822Type: vm ioctl
823Parameters: struct kvm_vcpu_event (out)
824Returns: 0 on success, -1 on error
825
826Gets currently pending exceptions, interrupts, and NMIs as well as related
827states of the vcpu.
828
829struct kvm_vcpu_events {
830 struct {
831 __u8 injected;
832 __u8 nr;
833 __u8 has_error_code;
834 __u8 pad;
835 __u32 error_code;
836 } exception;
837 struct {
838 __u8 injected;
839 __u8 nr;
840 __u8 soft;
48005f64 841 __u8 shadow;
3cfc3092
JK
842 } interrupt;
843 struct {
844 __u8 injected;
845 __u8 pending;
846 __u8 masked;
847 __u8 pad;
848 } nmi;
849 __u32 sipi_vector;
dab4b911 850 __u32 flags;
f077825a
PB
851 struct {
852 __u8 smm;
853 __u8 pending;
854 __u8 smm_inside_nmi;
855 __u8 latched_init;
856 } smi;
3cfc3092
JK
857};
858
f077825a
PB
859Only two fields are defined in the flags field:
860
861- KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that
862 interrupt.shadow contains a valid state.
48005f64 863
f077825a
PB
864- KVM_VCPUEVENT_VALID_SMM may be set in the flags field to signal that
865 smi contains a valid state.
414fa985 866
68ba6974 8674.32 KVM_SET_VCPU_EVENTS
3cfc3092
JK
868
869Capability: KVM_CAP_VCPU_EVENTS
48005f64 870Extended by: KVM_CAP_INTR_SHADOW
3cfc3092
JK
871Architectures: x86
872Type: vm ioctl
873Parameters: struct kvm_vcpu_event (in)
874Returns: 0 on success, -1 on error
875
876Set pending exceptions, interrupts, and NMIs as well as related states of the
877vcpu.
878
879See KVM_GET_VCPU_EVENTS for the data structure.
880
dab4b911 881Fields that may be modified asynchronously by running VCPUs can be excluded
f077825a
PB
882from the update. These fields are nmi.pending, sipi_vector, smi.smm,
883smi.pending. Keep the corresponding bits in the flags field cleared to
884suppress overwriting the current in-kernel state. The bits are:
dab4b911
JK
885
886KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
887KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
f077825a 888KVM_VCPUEVENT_VALID_SMM - transfer the smi sub-struct.
dab4b911 889
48005f64
JK
890If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
891the flags field to signal that interrupt.shadow contains a valid state and
892shall be written into the VCPU.
893
f077825a
PB
894KVM_VCPUEVENT_VALID_SMM can only be set if KVM_CAP_X86_SMM is available.
895
414fa985 896
68ba6974 8974.33 KVM_GET_DEBUGREGS
a1efbe77
JK
898
899Capability: KVM_CAP_DEBUGREGS
900Architectures: x86
901Type: vm ioctl
902Parameters: struct kvm_debugregs (out)
903Returns: 0 on success, -1 on error
904
905Reads debug registers from the vcpu.
906
907struct kvm_debugregs {
908 __u64 db[4];
909 __u64 dr6;
910 __u64 dr7;
911 __u64 flags;
912 __u64 reserved[9];
913};
914
414fa985 915
68ba6974 9164.34 KVM_SET_DEBUGREGS
a1efbe77
JK
917
918Capability: KVM_CAP_DEBUGREGS
919Architectures: x86
920Type: vm ioctl
921Parameters: struct kvm_debugregs (in)
922Returns: 0 on success, -1 on error
923
924Writes debug registers into the vcpu.
925
926See KVM_GET_DEBUGREGS for the data structure. The flags field is unused
927yet and must be cleared on entry.
928
414fa985 929
68ba6974 9304.35 KVM_SET_USER_MEMORY_REGION
0f2d8f4d
AK
931
932Capability: KVM_CAP_USER_MEM
933Architectures: all
934Type: vm ioctl
935Parameters: struct kvm_userspace_memory_region (in)
936Returns: 0 on success, -1 on error
937
938struct kvm_userspace_memory_region {
939 __u32 slot;
940 __u32 flags;
941 __u64 guest_phys_addr;
942 __u64 memory_size; /* bytes */
943 __u64 userspace_addr; /* start of the userspace allocated memory */
944};
945
946/* for kvm_memory_region::flags */
4d8b81ab
XG
947#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
948#define KVM_MEM_READONLY (1UL << 1)
0f2d8f4d
AK
949
950This ioctl allows the user to create or modify a guest physical memory
951slot. When changing an existing slot, it may be moved in the guest
952physical memory space, or its flags may be modified. It may not be
953resized. Slots may not overlap in guest physical address space.
a677e704
LC
954Bits 0-15 of "slot" specifies the slot id and this value should be
955less than the maximum number of user memory slots supported per VM.
956The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS,
957if this capability is supported by the architecture.
0f2d8f4d 958
f481b069
PB
959If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot"
960specifies the address space which is being modified. They must be
961less than the value that KVM_CHECK_EXTENSION returns for the
962KVM_CAP_MULTI_ADDRESS_SPACE capability. Slots in separate address spaces
963are unrelated; the restriction on overlapping slots only applies within
964each address space.
965
0f2d8f4d
AK
966Memory for the region is taken starting at the address denoted by the
967field userspace_addr, which must point at user addressable memory for
968the entire memory slot size. Any object may back this memory, including
969anonymous memory, ordinary files, and hugetlbfs.
970
971It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr
972be identical. This allows large pages in the guest to be backed by large
973pages in the host.
974
75d61fbc
TY
975The flags field supports two flags: KVM_MEM_LOG_DIRTY_PAGES and
976KVM_MEM_READONLY. The former can be set to instruct KVM to keep track of
977writes to memory within the slot. See KVM_GET_DIRTY_LOG ioctl to know how to
978use it. The latter can be set, if KVM_CAP_READONLY_MEM capability allows it,
979to make a new slot read-only. In this case, writes to this memory will be
980posted to userspace as KVM_EXIT_MMIO exits.
7efd8fa1
JK
981
982When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of
983the memory region are automatically reflected into the guest. For example, an
984mmap() that affects the region will be made visible immediately. Another
985example is madvise(MADV_DROP).
0f2d8f4d
AK
986
987It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl.
988The KVM_SET_MEMORY_REGION does not allow fine grained control over memory
989allocation and is deprecated.
3cfc3092 990
414fa985 991
68ba6974 9924.36 KVM_SET_TSS_ADDR
8a5416db
AK
993
994Capability: KVM_CAP_SET_TSS_ADDR
995Architectures: x86
996Type: vm ioctl
997Parameters: unsigned long tss_address (in)
998Returns: 0 on success, -1 on error
999
1000This ioctl defines the physical address of a three-page region in the guest
1001physical address space. The region must be within the first 4GB of the
1002guest physical address space and must not conflict with any memory slot
1003or any mmio address. The guest may malfunction if it accesses this memory
1004region.
1005
1006This ioctl is required on Intel-based hosts. This is needed on Intel hardware
1007because of a quirk in the virtualization implementation (see the internals
1008documentation when it pops into existence).
1009
414fa985 1010
68ba6974 10114.37 KVM_ENABLE_CAP
71fbfd5f 1012
d938dc55 1013Capability: KVM_CAP_ENABLE_CAP, KVM_CAP_ENABLE_CAP_VM
90de4a18
NA
1014Architectures: x86 (only KVM_CAP_ENABLE_CAP_VM),
1015 mips (only KVM_CAP_ENABLE_CAP), ppc, s390
d938dc55 1016Type: vcpu ioctl, vm ioctl (with KVM_CAP_ENABLE_CAP_VM)
71fbfd5f
AG
1017Parameters: struct kvm_enable_cap (in)
1018Returns: 0 on success; -1 on error
1019
1020+Not all extensions are enabled by default. Using this ioctl the application
1021can enable an extension, making it available to the guest.
1022
1023On systems that do not support this ioctl, it always fails. On systems that
1024do support it, it only works for extensions that are supported for enablement.
1025
1026To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
1027be used.
1028
1029struct kvm_enable_cap {
1030 /* in */
1031 __u32 cap;
1032
1033The capability that is supposed to get enabled.
1034
1035 __u32 flags;
1036
1037A bitfield indicating future enhancements. Has to be 0 for now.
1038
1039 __u64 args[4];
1040
1041Arguments for enabling a feature. If a feature needs initial values to
1042function properly, this is the place to put them.
1043
1044 __u8 pad[64];
1045};
1046
d938dc55
CH
1047The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl
1048for vm-wide capabilities.
414fa985 1049
68ba6974 10504.38 KVM_GET_MP_STATE
b843f065
AK
1051
1052Capability: KVM_CAP_MP_STATE
ecccf0cc 1053Architectures: x86, s390, arm, arm64
b843f065
AK
1054Type: vcpu ioctl
1055Parameters: struct kvm_mp_state (out)
1056Returns: 0 on success; -1 on error
1057
1058struct kvm_mp_state {
1059 __u32 mp_state;
1060};
1061
1062Returns the vcpu's current "multiprocessing state" (though also valid on
1063uniprocessor guests).
1064
1065Possible values are:
1066
ecccf0cc 1067 - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86,arm/arm64]
b843f065 1068 - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP)
c32a4272 1069 which has not yet received an INIT signal [x86]
b843f065 1070 - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is
c32a4272 1071 now ready for a SIPI [x86]
b843f065 1072 - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and
c32a4272 1073 is waiting for an interrupt [x86]
b843f065 1074 - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector
c32a4272 1075 accessible via KVM_GET_VCPU_EVENTS) [x86]
ecccf0cc 1076 - KVM_MP_STATE_STOPPED: the vcpu is stopped [s390,arm/arm64]
6352e4d2
DH
1077 - KVM_MP_STATE_CHECK_STOP: the vcpu is in a special error state [s390]
1078 - KVM_MP_STATE_OPERATING: the vcpu is operating (running or halted)
1079 [s390]
1080 - KVM_MP_STATE_LOAD: the vcpu is in a special load/startup state
1081 [s390]
b843f065 1082
c32a4272 1083On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an
0b4820d6
DH
1084in-kernel irqchip, the multiprocessing state must be maintained by userspace on
1085these architectures.
b843f065 1086
ecccf0cc
AB
1087For arm/arm64:
1088
1089The only states that are valid are KVM_MP_STATE_STOPPED and
1090KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not.
414fa985 1091
68ba6974 10924.39 KVM_SET_MP_STATE
b843f065
AK
1093
1094Capability: KVM_CAP_MP_STATE
ecccf0cc 1095Architectures: x86, s390, arm, arm64
b843f065
AK
1096Type: vcpu ioctl
1097Parameters: struct kvm_mp_state (in)
1098Returns: 0 on success; -1 on error
1099
1100Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
1101arguments.
1102
c32a4272 1103On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an
0b4820d6
DH
1104in-kernel irqchip, the multiprocessing state must be maintained by userspace on
1105these architectures.
b843f065 1106
ecccf0cc
AB
1107For arm/arm64:
1108
1109The only states that are valid are KVM_MP_STATE_STOPPED and
1110KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not.
414fa985 1111
68ba6974 11124.40 KVM_SET_IDENTITY_MAP_ADDR
47dbb84f
AK
1113
1114Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
1115Architectures: x86
1116Type: vm ioctl
1117Parameters: unsigned long identity (in)
1118Returns: 0 on success, -1 on error
1119
1120This ioctl defines the physical address of a one-page region in the guest
1121physical address space. The region must be within the first 4GB of the
1122guest physical address space and must not conflict with any memory slot
1123or any mmio address. The guest may malfunction if it accesses this memory
1124region.
1125
1126This ioctl is required on Intel-based hosts. This is needed on Intel hardware
1127because of a quirk in the virtualization implementation (see the internals
1128documentation when it pops into existence).
1129
414fa985 1130
68ba6974 11314.41 KVM_SET_BOOT_CPU_ID
57bc24cf
AK
1132
1133Capability: KVM_CAP_SET_BOOT_CPU_ID
c32a4272 1134Architectures: x86
57bc24cf
AK
1135Type: vm ioctl
1136Parameters: unsigned long vcpu_id
1137Returns: 0 on success, -1 on error
1138
1139Define which vcpu is the Bootstrap Processor (BSP). Values are the same
1140as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
1141is vcpu 0.
1142
414fa985 1143
68ba6974 11444.42 KVM_GET_XSAVE
2d5b5a66
SY
1145
1146Capability: KVM_CAP_XSAVE
1147Architectures: x86
1148Type: vcpu ioctl
1149Parameters: struct kvm_xsave (out)
1150Returns: 0 on success, -1 on error
1151
1152struct kvm_xsave {
1153 __u32 region[1024];
1154};
1155
1156This ioctl would copy current vcpu's xsave struct to the userspace.
1157
414fa985 1158
68ba6974 11594.43 KVM_SET_XSAVE
2d5b5a66
SY
1160
1161Capability: KVM_CAP_XSAVE
1162Architectures: x86
1163Type: vcpu ioctl
1164Parameters: struct kvm_xsave (in)
1165Returns: 0 on success, -1 on error
1166
1167struct kvm_xsave {
1168 __u32 region[1024];
1169};
1170
1171This ioctl would copy userspace's xsave struct to the kernel.
1172
414fa985 1173
68ba6974 11744.44 KVM_GET_XCRS
2d5b5a66
SY
1175
1176Capability: KVM_CAP_XCRS
1177Architectures: x86
1178Type: vcpu ioctl
1179Parameters: struct kvm_xcrs (out)
1180Returns: 0 on success, -1 on error
1181
1182struct kvm_xcr {
1183 __u32 xcr;
1184 __u32 reserved;
1185 __u64 value;
1186};
1187
1188struct kvm_xcrs {
1189 __u32 nr_xcrs;
1190 __u32 flags;
1191 struct kvm_xcr xcrs[KVM_MAX_XCRS];
1192 __u64 padding[16];
1193};
1194
1195This ioctl would copy current vcpu's xcrs to the userspace.
1196
414fa985 1197
68ba6974 11984.45 KVM_SET_XCRS
2d5b5a66
SY
1199
1200Capability: KVM_CAP_XCRS
1201Architectures: x86
1202Type: vcpu ioctl
1203Parameters: struct kvm_xcrs (in)
1204Returns: 0 on success, -1 on error
1205
1206struct kvm_xcr {
1207 __u32 xcr;
1208 __u32 reserved;
1209 __u64 value;
1210};
1211
1212struct kvm_xcrs {
1213 __u32 nr_xcrs;
1214 __u32 flags;
1215 struct kvm_xcr xcrs[KVM_MAX_XCRS];
1216 __u64 padding[16];
1217};
1218
1219This ioctl would set vcpu's xcr to the value userspace specified.
1220
414fa985 1221
68ba6974 12224.46 KVM_GET_SUPPORTED_CPUID
d153513d
AK
1223
1224Capability: KVM_CAP_EXT_CPUID
1225Architectures: x86
1226Type: system ioctl
1227Parameters: struct kvm_cpuid2 (in/out)
1228Returns: 0 on success, -1 on error
1229
1230struct kvm_cpuid2 {
1231 __u32 nent;
1232 __u32 padding;
1233 struct kvm_cpuid_entry2 entries[0];
1234};
1235
9c15bb1d
BP
1236#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
1237#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
1238#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
d153513d
AK
1239
1240struct kvm_cpuid_entry2 {
1241 __u32 function;
1242 __u32 index;
1243 __u32 flags;
1244 __u32 eax;
1245 __u32 ebx;
1246 __u32 ecx;
1247 __u32 edx;
1248 __u32 padding[3];
1249};
1250
1251This ioctl returns x86 cpuid features which are supported by both the hardware
1252and kvm. Userspace can use the information returned by this ioctl to
1253construct cpuid information (for KVM_SET_CPUID2) that is consistent with
1254hardware, kernel, and userspace capabilities, and with user requirements (for
1255example, the user may wish to constrain cpuid to emulate older hardware,
1256or for feature consistency across a cluster).
1257
1258Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure
1259with the 'nent' field indicating the number of entries in the variable-size
1260array 'entries'. If the number of entries is too low to describe the cpu
1261capabilities, an error (E2BIG) is returned. If the number is too high,
1262the 'nent' field is adjusted and an error (ENOMEM) is returned. If the
1263number is just right, the 'nent' field is adjusted to the number of valid
1264entries in the 'entries' array, which is then filled.
1265
1266The entries returned are the host cpuid as returned by the cpuid instruction,
c39cbd2a
AK
1267with unknown or unsupported features masked out. Some features (for example,
1268x2apic), may not be present in the host cpu, but are exposed by kvm if it can
1269emulate them efficiently. The fields in each entry are defined as follows:
d153513d
AK
1270
1271 function: the eax value used to obtain the entry
1272 index: the ecx value used to obtain the entry (for entries that are
1273 affected by ecx)
1274 flags: an OR of zero or more of the following:
1275 KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
1276 if the index field is valid
1277 KVM_CPUID_FLAG_STATEFUL_FUNC:
1278 if cpuid for this function returns different values for successive
1279 invocations; there will be several entries with the same function,
1280 all with this flag set
1281 KVM_CPUID_FLAG_STATE_READ_NEXT:
1282 for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
1283 the first entry to be read by a cpu
1284 eax, ebx, ecx, edx: the values returned by the cpuid instruction for
1285 this function/index combination
1286
4d25a066
JK
1287The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned
1288as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC
1289support. Instead it is reported via
1290
1291 ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)
1292
1293if that returns true and you use KVM_CREATE_IRQCHIP, or if you emulate the
1294feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
1295
414fa985 1296
68ba6974 12974.47 KVM_PPC_GET_PVINFO
15711e9c
AG
1298
1299Capability: KVM_CAP_PPC_GET_PVINFO
1300Architectures: ppc
1301Type: vm ioctl
1302Parameters: struct kvm_ppc_pvinfo (out)
1303Returns: 0 on success, !0 on error
1304
1305struct kvm_ppc_pvinfo {
1306 __u32 flags;
1307 __u32 hcall[4];
1308 __u8 pad[108];
1309};
1310
1311This ioctl fetches PV specific information that need to be passed to the guest
1312using the device tree or other means from vm context.
1313
9202e076 1314The hcall array defines 4 instructions that make up a hypercall.
15711e9c
AG
1315
1316If any additional field gets added to this structure later on, a bit for that
1317additional piece of information will be set in the flags bitmap.
1318
9202e076
LYB
1319The flags bitmap is defined as:
1320
1321 /* the host supports the ePAPR idle hcall
1322 #define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0)
414fa985 1323
e80a4a94 13244.48 KVM_ASSIGN_PCI_DEVICE (deprecated)
49f48172 1325
7f05db6a 1326Capability: none
c32a4272 1327Architectures: x86
49f48172
JK
1328Type: vm ioctl
1329Parameters: struct kvm_assigned_pci_dev (in)
1330Returns: 0 on success, -1 on error
1331
1332Assigns a host PCI device to the VM.
1333
1334struct kvm_assigned_pci_dev {
1335 __u32 assigned_dev_id;
1336 __u32 busnr;
1337 __u32 devfn;
1338 __u32 flags;
1339 __u32 segnr;
1340 union {
1341 __u32 reserved[11];
1342 };
1343};
1344
1345The PCI device is specified by the triple segnr, busnr, and devfn.
1346Identification in succeeding service requests is done via assigned_dev_id. The
1347following flags are specified:
1348
1349/* Depends on KVM_CAP_IOMMU */
1350#define KVM_DEV_ASSIGN_ENABLE_IOMMU (1 << 0)
07700a94
JK
1351/* The following two depend on KVM_CAP_PCI_2_3 */
1352#define KVM_DEV_ASSIGN_PCI_2_3 (1 << 1)
1353#define KVM_DEV_ASSIGN_MASK_INTX (1 << 2)
1354
1355If KVM_DEV_ASSIGN_PCI_2_3 is set, the kernel will manage legacy INTx interrupts
1356via the PCI-2.3-compliant device-level mask, thus enable IRQ sharing with other
1357assigned devices or host devices. KVM_DEV_ASSIGN_MASK_INTX specifies the
1358guest's view on the INTx mask, see KVM_ASSIGN_SET_INTX_MASK for details.
49f48172 1359
42387373
AW
1360The KVM_DEV_ASSIGN_ENABLE_IOMMU flag is a mandatory option to ensure
1361isolation of the device. Usages not specifying this flag are deprecated.
1362
3d27e23b
AW
1363Only PCI header type 0 devices with PCI BAR resources are supported by
1364device assignment. The user requesting this ioctl must have read/write
1365access to the PCI sysfs resource files associated with the device.
1366
7f05db6a
MT
1367Errors:
1368 ENOTTY: kernel does not support this ioctl
1369
1370 Other error conditions may be defined by individual device types or
1371 have their standard meanings.
1372
414fa985 1373
e80a4a94 13744.49 KVM_DEASSIGN_PCI_DEVICE (deprecated)
49f48172 1375
7f05db6a 1376Capability: none
c32a4272 1377Architectures: x86
49f48172
JK
1378Type: vm ioctl
1379Parameters: struct kvm_assigned_pci_dev (in)
1380Returns: 0 on success, -1 on error
1381
1382Ends PCI device assignment, releasing all associated resources.
1383
7f05db6a 1384See KVM_ASSIGN_PCI_DEVICE for the data structure. Only assigned_dev_id is
49f48172
JK
1385used in kvm_assigned_pci_dev to identify the device.
1386
7f05db6a
MT
1387Errors:
1388 ENOTTY: kernel does not support this ioctl
1389
1390 Other error conditions may be defined by individual device types or
1391 have their standard meanings.
414fa985 1392
e80a4a94 13934.50 KVM_ASSIGN_DEV_IRQ (deprecated)
49f48172
JK
1394
1395Capability: KVM_CAP_ASSIGN_DEV_IRQ
c32a4272 1396Architectures: x86
49f48172
JK
1397Type: vm ioctl
1398Parameters: struct kvm_assigned_irq (in)
1399Returns: 0 on success, -1 on error
1400
1401Assigns an IRQ to a passed-through device.
1402
1403struct kvm_assigned_irq {
1404 __u32 assigned_dev_id;
91e3d71d 1405 __u32 host_irq; /* ignored (legacy field) */
49f48172
JK
1406 __u32 guest_irq;
1407 __u32 flags;
1408 union {
49f48172
JK
1409 __u32 reserved[12];
1410 };
1411};
1412
1413The following flags are defined:
1414
1415#define KVM_DEV_IRQ_HOST_INTX (1 << 0)
1416#define KVM_DEV_IRQ_HOST_MSI (1 << 1)
1417#define KVM_DEV_IRQ_HOST_MSIX (1 << 2)
1418
1419#define KVM_DEV_IRQ_GUEST_INTX (1 << 8)
1420#define KVM_DEV_IRQ_GUEST_MSI (1 << 9)
1421#define KVM_DEV_IRQ_GUEST_MSIX (1 << 10)
1422
1423It is not valid to specify multiple types per host or guest IRQ. However, the
1424IRQ type of host and guest can differ or can even be null.
1425
7f05db6a
MT
1426Errors:
1427 ENOTTY: kernel does not support this ioctl
1428
1429 Other error conditions may be defined by individual device types or
1430 have their standard meanings.
1431
414fa985 1432
e80a4a94 14334.51 KVM_DEASSIGN_DEV_IRQ (deprecated)
49f48172
JK
1434
1435Capability: KVM_CAP_ASSIGN_DEV_IRQ
c32a4272 1436Architectures: x86
49f48172
JK
1437Type: vm ioctl
1438Parameters: struct kvm_assigned_irq (in)
1439Returns: 0 on success, -1 on error
1440
1441Ends an IRQ assignment to a passed-through device.
1442
1443See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1444by assigned_dev_id, flags must correspond to the IRQ type specified on
1445KVM_ASSIGN_DEV_IRQ. Partial deassignment of host or guest IRQ is allowed.
1446
414fa985 1447
68ba6974 14484.52 KVM_SET_GSI_ROUTING
49f48172
JK
1449
1450Capability: KVM_CAP_IRQ_ROUTING
180ae7b1 1451Architectures: x86 s390 arm arm64
49f48172
JK
1452Type: vm ioctl
1453Parameters: struct kvm_irq_routing (in)
1454Returns: 0 on success, -1 on error
1455
1456Sets the GSI routing table entries, overwriting any previously set entries.
1457
180ae7b1
EA
1458On arm/arm64, GSI routing has the following limitation:
1459- GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD.
1460
49f48172
JK
1461struct kvm_irq_routing {
1462 __u32 nr;
1463 __u32 flags;
1464 struct kvm_irq_routing_entry entries[0];
1465};
1466
1467No flags are specified so far, the corresponding field must be set to zero.
1468
1469struct kvm_irq_routing_entry {
1470 __u32 gsi;
1471 __u32 type;
1472 __u32 flags;
1473 __u32 pad;
1474 union {
1475 struct kvm_irq_routing_irqchip irqchip;
1476 struct kvm_irq_routing_msi msi;
84223598 1477 struct kvm_irq_routing_s390_adapter adapter;
5c919412 1478 struct kvm_irq_routing_hv_sint hv_sint;
49f48172
JK
1479 __u32 pad[8];
1480 } u;
1481};
1482
1483/* gsi routing entry types */
1484#define KVM_IRQ_ROUTING_IRQCHIP 1
1485#define KVM_IRQ_ROUTING_MSI 2
84223598 1486#define KVM_IRQ_ROUTING_S390_ADAPTER 3
5c919412 1487#define KVM_IRQ_ROUTING_HV_SINT 4
49f48172 1488
76a10b86 1489flags:
6f49b2f3
PB
1490- KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entry
1491 type, specifies that the devid field contains a valid value. The per-VM
1492 KVM_CAP_MSI_DEVID capability advertises the requirement to provide
1493 the device ID. If this capability is not available, userspace should
1494 never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
76a10b86 1495- zero otherwise
49f48172
JK
1496
1497struct kvm_irq_routing_irqchip {
1498 __u32 irqchip;
1499 __u32 pin;
1500};
1501
1502struct kvm_irq_routing_msi {
1503 __u32 address_lo;
1504 __u32 address_hi;
1505 __u32 data;
76a10b86
EA
1506 union {
1507 __u32 pad;
1508 __u32 devid;
1509 };
49f48172
JK
1510};
1511
6f49b2f3
PB
1512If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier
1513for the device that wrote the MSI message. For PCI, this is usually a
1514BFD identifier in the lower 16 bits.
76a10b86 1515
37131313
RK
1516On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS
1517feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,
1518address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of
1519address_hi must be zero.
1520
84223598
CH
1521struct kvm_irq_routing_s390_adapter {
1522 __u64 ind_addr;
1523 __u64 summary_addr;
1524 __u64 ind_offset;
1525 __u32 summary_offset;
1526 __u32 adapter_id;
1527};
1528
5c919412
AS
1529struct kvm_irq_routing_hv_sint {
1530 __u32 vcpu;
1531 __u32 sint;
1532};
414fa985 1533
e80a4a94 15344.53 KVM_ASSIGN_SET_MSIX_NR (deprecated)
49f48172 1535
7f05db6a 1536Capability: none
c32a4272 1537Architectures: x86
49f48172
JK
1538Type: vm ioctl
1539Parameters: struct kvm_assigned_msix_nr (in)
1540Returns: 0 on success, -1 on error
1541
58f0964e
JK
1542Set the number of MSI-X interrupts for an assigned device. The number is
1543reset again by terminating the MSI-X assignment of the device via
1544KVM_DEASSIGN_DEV_IRQ. Calling this service more than once at any earlier
1545point will fail.
49f48172
JK
1546
1547struct kvm_assigned_msix_nr {
1548 __u32 assigned_dev_id;
1549 __u16 entry_nr;
1550 __u16 padding;
1551};
1552
1553#define KVM_MAX_MSIX_PER_DEV 256
1554
414fa985 1555
e80a4a94 15564.54 KVM_ASSIGN_SET_MSIX_ENTRY (deprecated)
49f48172 1557
7f05db6a 1558Capability: none
c32a4272 1559Architectures: x86
49f48172
JK
1560Type: vm ioctl
1561Parameters: struct kvm_assigned_msix_entry (in)
1562Returns: 0 on success, -1 on error
1563
1564Specifies the routing of an MSI-X assigned device interrupt to a GSI. Setting
1565the GSI vector to zero means disabling the interrupt.
1566
1567struct kvm_assigned_msix_entry {
1568 __u32 assigned_dev_id;
1569 __u32 gsi;
1570 __u16 entry; /* The index of entry in the MSI-X table */
1571 __u16 padding[3];
1572};
1573
7f05db6a
MT
1574Errors:
1575 ENOTTY: kernel does not support this ioctl
1576
1577 Other error conditions may be defined by individual device types or
1578 have their standard meanings.
1579
414fa985
JK
1580
15814.55 KVM_SET_TSC_KHZ
92a1f12d
JR
1582
1583Capability: KVM_CAP_TSC_CONTROL
1584Architectures: x86
1585Type: vcpu ioctl
1586Parameters: virtual tsc_khz
1587Returns: 0 on success, -1 on error
1588
1589Specifies the tsc frequency for the virtual machine. The unit of the
1590frequency is KHz.
1591
414fa985
JK
1592
15934.56 KVM_GET_TSC_KHZ
92a1f12d
JR
1594
1595Capability: KVM_CAP_GET_TSC_KHZ
1596Architectures: x86
1597Type: vcpu ioctl
1598Parameters: none
1599Returns: virtual tsc-khz on success, negative value on error
1600
1601Returns the tsc frequency of the guest. The unit of the return value is
1602KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
1603error.
1604
414fa985
JK
1605
16064.57 KVM_GET_LAPIC
e7677933
AK
1607
1608Capability: KVM_CAP_IRQCHIP
1609Architectures: x86
1610Type: vcpu ioctl
1611Parameters: struct kvm_lapic_state (out)
1612Returns: 0 on success, -1 on error
1613
1614#define KVM_APIC_REG_SIZE 0x400
1615struct kvm_lapic_state {
1616 char regs[KVM_APIC_REG_SIZE];
1617};
1618
1619Reads the Local APIC registers and copies them into the input argument. The
1620data format and layout are the same as documented in the architecture manual.
1621
37131313
RK
1622If KVM_X2APIC_API_USE_32BIT_IDS feature of KVM_CAP_X2APIC_API is
1623enabled, then the format of APIC_ID register depends on the APIC mode
1624(reported by MSR_IA32_APICBASE) of its VCPU. x2APIC stores APIC ID in
1625the APIC_ID register (bytes 32-35). xAPIC only allows an 8-bit APIC ID
1626which is stored in bits 31-24 of the APIC register, or equivalently in
1627byte 35 of struct kvm_lapic_state's regs field. KVM_GET_LAPIC must then
1628be called after MSR_IA32_APICBASE has been set with KVM_SET_MSR.
1629
1630If KVM_X2APIC_API_USE_32BIT_IDS feature is disabled, struct kvm_lapic_state
1631always uses xAPIC format.
1632
414fa985
JK
1633
16344.58 KVM_SET_LAPIC
e7677933
AK
1635
1636Capability: KVM_CAP_IRQCHIP
1637Architectures: x86
1638Type: vcpu ioctl
1639Parameters: struct kvm_lapic_state (in)
1640Returns: 0 on success, -1 on error
1641
1642#define KVM_APIC_REG_SIZE 0x400
1643struct kvm_lapic_state {
1644 char regs[KVM_APIC_REG_SIZE];
1645};
1646
df5cbb27 1647Copies the input argument into the Local APIC registers. The data format
e7677933
AK
1648and layout are the same as documented in the architecture manual.
1649
37131313
RK
1650The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's
1651regs field) depends on the state of the KVM_CAP_X2APIC_API capability.
1652See the note in KVM_GET_LAPIC.
1653
414fa985
JK
1654
16554.59 KVM_IOEVENTFD
55399a02
SL
1656
1657Capability: KVM_CAP_IOEVENTFD
1658Architectures: all
1659Type: vm ioctl
1660Parameters: struct kvm_ioeventfd (in)
1661Returns: 0 on success, !0 on error
1662
1663This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
1664within the guest. A guest write in the registered address will signal the
1665provided event instead of triggering an exit.
1666
1667struct kvm_ioeventfd {
1668 __u64 datamatch;
1669 __u64 addr; /* legal pio/mmio address */
e9ea5069 1670 __u32 len; /* 0, 1, 2, 4, or 8 bytes */
55399a02
SL
1671 __s32 fd;
1672 __u32 flags;
1673 __u8 pad[36];
1674};
1675
2b83451b
CH
1676For the special case of virtio-ccw devices on s390, the ioevent is matched
1677to a subchannel/virtqueue tuple instead.
1678
55399a02
SL
1679The following flags are defined:
1680
1681#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
1682#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
1683#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
2b83451b
CH
1684#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \
1685 (1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify)
55399a02
SL
1686
1687If datamatch flag is set, the event will be signaled only if the written value
1688to the registered address is equal to datamatch in struct kvm_ioeventfd.
1689
2b83451b
CH
1690For virtio-ccw devices, addr contains the subchannel id and datamatch the
1691virtqueue index.
1692
e9ea5069
JW
1693With KVM_CAP_IOEVENTFD_ANY_LENGTH, a zero length ioeventfd is allowed, and
1694the kernel will ignore the length of guest write and may get a faster vmexit.
1695The speedup may only apply to specific architectures, but the ioeventfd will
1696work anyway.
414fa985
JK
1697
16984.60 KVM_DIRTY_TLB
dc83b8bc
SW
1699
1700Capability: KVM_CAP_SW_TLB
1701Architectures: ppc
1702Type: vcpu ioctl
1703Parameters: struct kvm_dirty_tlb (in)
1704Returns: 0 on success, -1 on error
1705
1706struct kvm_dirty_tlb {
1707 __u64 bitmap;
1708 __u32 num_dirty;
1709};
1710
1711This must be called whenever userspace has changed an entry in the shared
1712TLB, prior to calling KVM_RUN on the associated vcpu.
1713
1714The "bitmap" field is the userspace address of an array. This array
1715consists of a number of bits, equal to the total number of TLB entries as
1716determined by the last successful call to KVM_CONFIG_TLB, rounded up to the
1717nearest multiple of 64.
1718
1719Each bit corresponds to one TLB entry, ordered the same as in the shared TLB
1720array.
1721
1722The array is little-endian: the bit 0 is the least significant bit of the
1723first byte, bit 8 is the least significant bit of the second byte, etc.
1724This avoids any complications with differing word sizes.
1725
1726The "num_dirty" field is a performance hint for KVM to determine whether it
1727should skip processing the bitmap and just invalidate everything. It must
1728be set to the number of set bits in the bitmap.
1729
414fa985 1730
e80a4a94 17314.61 KVM_ASSIGN_SET_INTX_MASK (deprecated)
07700a94
JK
1732
1733Capability: KVM_CAP_PCI_2_3
1734Architectures: x86
1735Type: vm ioctl
1736Parameters: struct kvm_assigned_pci_dev (in)
1737Returns: 0 on success, -1 on error
1738
1739Allows userspace to mask PCI INTx interrupts from the assigned device. The
1740kernel will not deliver INTx interrupts to the guest between setting and
1741clearing of KVM_ASSIGN_SET_INTX_MASK via this interface. This enables use of
1742and emulation of PCI 2.3 INTx disable command register behavior.
1743
1744This may be used for both PCI 2.3 devices supporting INTx disable natively and
1745older devices lacking this support. Userspace is responsible for emulating the
1746read value of the INTx disable bit in the guest visible PCI command register.
1747When modifying the INTx disable state, userspace should precede updating the
1748physical device command register by calling this ioctl to inform the kernel of
1749the new intended INTx mask state.
1750
1751Note that the kernel uses the device INTx disable bit to internally manage the
1752device interrupt state for PCI 2.3 devices. Reads of this register may
1753therefore not match the expected value. Writes should always use the guest
1754intended INTx disable value rather than attempting to read-copy-update the
1755current physical device state. Races between user and kernel updates to the
1756INTx disable bit are handled lazily in the kernel. It's possible the device
1757may generate unintended interrupts, but they will not be injected into the
1758guest.
1759
1760See KVM_ASSIGN_DEV_IRQ for the data structure. The target device is specified
1761by assigned_dev_id. In the flags field, only KVM_DEV_ASSIGN_MASK_INTX is
1762evaluated.
1763
414fa985 1764
54738c09
DG
17654.62 KVM_CREATE_SPAPR_TCE
1766
1767Capability: KVM_CAP_SPAPR_TCE
1768Architectures: powerpc
1769Type: vm ioctl
1770Parameters: struct kvm_create_spapr_tce (in)
1771Returns: file descriptor for manipulating the created TCE table
1772
1773This creates a virtual TCE (translation control entry) table, which
1774is an IOMMU for PAPR-style virtual I/O. It is used to translate
1775logical addresses used in virtual I/O into guest physical addresses,
1776and provides a scatter/gather capability for PAPR virtual I/O.
1777
1778/* for KVM_CAP_SPAPR_TCE */
1779struct kvm_create_spapr_tce {
1780 __u64 liobn;
1781 __u32 window_size;
1782};
1783
1784The liobn field gives the logical IO bus number for which to create a
1785TCE table. The window_size field specifies the size of the DMA window
1786which this TCE table will translate - the table will contain one 64
1787bit TCE entry for every 4kiB of the DMA window.
1788
1789When the guest issues an H_PUT_TCE hcall on a liobn for which a TCE
1790table has been created using this ioctl(), the kernel will handle it
1791in real mode, updating the TCE table. H_PUT_TCE calls for other
1792liobns will cause a vm exit and must be handled by userspace.
1793
1794The return value is a file descriptor which can be passed to mmap(2)
1795to map the created TCE table into userspace. This lets userspace read
1796the entries written by kernel-handled H_PUT_TCE calls, and also lets
1797userspace update the TCE table directly which is useful in some
1798circumstances.
1799
414fa985 1800
aa04b4cc
PM
18014.63 KVM_ALLOCATE_RMA
1802
1803Capability: KVM_CAP_PPC_RMA
1804Architectures: powerpc
1805Type: vm ioctl
1806Parameters: struct kvm_allocate_rma (out)
1807Returns: file descriptor for mapping the allocated RMA
1808
1809This allocates a Real Mode Area (RMA) from the pool allocated at boot
1810time by the kernel. An RMA is a physically-contiguous, aligned region
1811of memory used on older POWER processors to provide the memory which
1812will be accessed by real-mode (MMU off) accesses in a KVM guest.
1813POWER processors support a set of sizes for the RMA that usually
1814includes 64MB, 128MB, 256MB and some larger powers of two.
1815
1816/* for KVM_ALLOCATE_RMA */
1817struct kvm_allocate_rma {
1818 __u64 rma_size;
1819};
1820
1821The return value is a file descriptor which can be passed to mmap(2)
1822to map the allocated RMA into userspace. The mapped area can then be
1823passed to the KVM_SET_USER_MEMORY_REGION ioctl to establish it as the
1824RMA for a virtual machine. The size of the RMA in bytes (which is
1825fixed at host kernel boot time) is returned in the rma_size field of
1826the argument structure.
1827
1828The KVM_CAP_PPC_RMA capability is 1 or 2 if the KVM_ALLOCATE_RMA ioctl
1829is supported; 2 if the processor requires all virtual machines to have
1830an RMA, or 1 if the processor can use an RMA but doesn't require it,
1831because it supports the Virtual RMA (VRMA) facility.
1832
414fa985 1833
3f745f1e
AK
18344.64 KVM_NMI
1835
1836Capability: KVM_CAP_USER_NMI
1837Architectures: x86
1838Type: vcpu ioctl
1839Parameters: none
1840Returns: 0 on success, -1 on error
1841
1842Queues an NMI on the thread's vcpu. Note this is well defined only
1843when KVM_CREATE_IRQCHIP has not been called, since this is an interface
1844between the virtual cpu core and virtual local APIC. After KVM_CREATE_IRQCHIP
1845has been called, this interface is completely emulated within the kernel.
1846
1847To use this to emulate the LINT1 input with KVM_CREATE_IRQCHIP, use the
1848following algorithm:
1849
5d4f6f3d 1850 - pause the vcpu
3f745f1e
AK
1851 - read the local APIC's state (KVM_GET_LAPIC)
1852 - check whether changing LINT1 will queue an NMI (see the LVT entry for LINT1)
1853 - if so, issue KVM_NMI
1854 - resume the vcpu
1855
1856Some guests configure the LINT1 NMI input to cause a panic, aiding in
1857debugging.
1858
414fa985 1859
e24ed81f 18604.65 KVM_S390_UCAS_MAP
27e0393f
CO
1861
1862Capability: KVM_CAP_S390_UCONTROL
1863Architectures: s390
1864Type: vcpu ioctl
1865Parameters: struct kvm_s390_ucas_mapping (in)
1866Returns: 0 in case of success
1867
1868The parameter is defined like this:
1869 struct kvm_s390_ucas_mapping {
1870 __u64 user_addr;
1871 __u64 vcpu_addr;
1872 __u64 length;
1873 };
1874
1875This ioctl maps the memory at "user_addr" with the length "length" to
1876the vcpu's address space starting at "vcpu_addr". All parameters need to
f884ab15 1877be aligned by 1 megabyte.
27e0393f 1878
414fa985 1879
e24ed81f 18804.66 KVM_S390_UCAS_UNMAP
27e0393f
CO
1881
1882Capability: KVM_CAP_S390_UCONTROL
1883Architectures: s390
1884Type: vcpu ioctl
1885Parameters: struct kvm_s390_ucas_mapping (in)
1886Returns: 0 in case of success
1887
1888The parameter is defined like this:
1889 struct kvm_s390_ucas_mapping {
1890 __u64 user_addr;
1891 __u64 vcpu_addr;
1892 __u64 length;
1893 };
1894
1895This ioctl unmaps the memory in the vcpu's address space starting at
1896"vcpu_addr" with the length "length". The field "user_addr" is ignored.
f884ab15 1897All parameters need to be aligned by 1 megabyte.
27e0393f 1898
414fa985 1899
e24ed81f 19004.67 KVM_S390_VCPU_FAULT
ccc7910f
CO
1901
1902Capability: KVM_CAP_S390_UCONTROL
1903Architectures: s390
1904Type: vcpu ioctl
1905Parameters: vcpu absolute address (in)
1906Returns: 0 in case of success
1907
1908This call creates a page table entry on the virtual cpu's address space
1909(for user controlled virtual machines) or the virtual machine's address
1910space (for regular virtual machines). This only works for minor faults,
1911thus it's recommended to access subject memory page via the user page
1912table upfront. This is useful to handle validity intercepts for user
1913controlled virtual machines to fault in the virtual cpu's lowcore pages
1914prior to calling the KVM_RUN ioctl.
1915
414fa985 1916
e24ed81f
AG
19174.68 KVM_SET_ONE_REG
1918
1919Capability: KVM_CAP_ONE_REG
1920Architectures: all
1921Type: vcpu ioctl
1922Parameters: struct kvm_one_reg (in)
1923Returns: 0 on success, negative value on failure
1924
1925struct kvm_one_reg {
1926 __u64 id;
1927 __u64 addr;
1928};
1929
1930Using this ioctl, a single vcpu register can be set to a specific value
1931defined by user space with the passed in struct kvm_one_reg, where id
1932refers to the register identifier as described below and addr is a pointer
1933to a variable with the respective size. There can be architecture agnostic
1934and architecture specific registers. Each have their own range of operation
1935and their own constants and width. To keep track of the implemented
1936registers, find a list below:
1937
bf5590f3
JH
1938 Arch | Register | Width (bits)
1939 | |
1940 PPC | KVM_REG_PPC_HIOR | 64
1941 PPC | KVM_REG_PPC_IAC1 | 64
1942 PPC | KVM_REG_PPC_IAC2 | 64
1943 PPC | KVM_REG_PPC_IAC3 | 64
1944 PPC | KVM_REG_PPC_IAC4 | 64
1945 PPC | KVM_REG_PPC_DAC1 | 64
1946 PPC | KVM_REG_PPC_DAC2 | 64
1947 PPC | KVM_REG_PPC_DABR | 64
1948 PPC | KVM_REG_PPC_DSCR | 64
1949 PPC | KVM_REG_PPC_PURR | 64
1950 PPC | KVM_REG_PPC_SPURR | 64
1951 PPC | KVM_REG_PPC_DAR | 64
1952 PPC | KVM_REG_PPC_DSISR | 32
1953 PPC | KVM_REG_PPC_AMR | 64
1954 PPC | KVM_REG_PPC_UAMOR | 64
1955 PPC | KVM_REG_PPC_MMCR0 | 64
1956 PPC | KVM_REG_PPC_MMCR1 | 64
1957 PPC | KVM_REG_PPC_MMCRA | 64
1958 PPC | KVM_REG_PPC_MMCR2 | 64
1959 PPC | KVM_REG_PPC_MMCRS | 64
1960 PPC | KVM_REG_PPC_SIAR | 64
1961 PPC | KVM_REG_PPC_SDAR | 64
1962 PPC | KVM_REG_PPC_SIER | 64
1963 PPC | KVM_REG_PPC_PMC1 | 32
1964 PPC | KVM_REG_PPC_PMC2 | 32
1965 PPC | KVM_REG_PPC_PMC3 | 32
1966 PPC | KVM_REG_PPC_PMC4 | 32
1967 PPC | KVM_REG_PPC_PMC5 | 32
1968 PPC | KVM_REG_PPC_PMC6 | 32
1969 PPC | KVM_REG_PPC_PMC7 | 32
1970 PPC | KVM_REG_PPC_PMC8 | 32
1971 PPC | KVM_REG_PPC_FPR0 | 64
a8bd19ef 1972 ...
bf5590f3
JH
1973 PPC | KVM_REG_PPC_FPR31 | 64
1974 PPC | KVM_REG_PPC_VR0 | 128
a8bd19ef 1975 ...
bf5590f3
JH
1976 PPC | KVM_REG_PPC_VR31 | 128
1977 PPC | KVM_REG_PPC_VSR0 | 128
a8bd19ef 1978 ...
bf5590f3
JH
1979 PPC | KVM_REG_PPC_VSR31 | 128
1980 PPC | KVM_REG_PPC_FPSCR | 64
1981 PPC | KVM_REG_PPC_VSCR | 32
1982 PPC | KVM_REG_PPC_VPA_ADDR | 64
1983 PPC | KVM_REG_PPC_VPA_SLB | 128
1984 PPC | KVM_REG_PPC_VPA_DTL | 128
1985 PPC | KVM_REG_PPC_EPCR | 32
1986 PPC | KVM_REG_PPC_EPR | 32
1987 PPC | KVM_REG_PPC_TCR | 32
1988 PPC | KVM_REG_PPC_TSR | 32
1989 PPC | KVM_REG_PPC_OR_TSR | 32
1990 PPC | KVM_REG_PPC_CLEAR_TSR | 32
1991 PPC | KVM_REG_PPC_MAS0 | 32
1992 PPC | KVM_REG_PPC_MAS1 | 32
1993 PPC | KVM_REG_PPC_MAS2 | 64
1994 PPC | KVM_REG_PPC_MAS7_3 | 64
1995 PPC | KVM_REG_PPC_MAS4 | 32
1996 PPC | KVM_REG_PPC_MAS6 | 32
1997 PPC | KVM_REG_PPC_MMUCFG | 32
1998 PPC | KVM_REG_PPC_TLB0CFG | 32
1999 PPC | KVM_REG_PPC_TLB1CFG | 32
2000 PPC | KVM_REG_PPC_TLB2CFG | 32
2001 PPC | KVM_REG_PPC_TLB3CFG | 32
2002 PPC | KVM_REG_PPC_TLB0PS | 32
2003 PPC | KVM_REG_PPC_TLB1PS | 32
2004 PPC | KVM_REG_PPC_TLB2PS | 32
2005 PPC | KVM_REG_PPC_TLB3PS | 32
2006 PPC | KVM_REG_PPC_EPTCFG | 32
2007 PPC | KVM_REG_PPC_ICP_STATE | 64
2008 PPC | KVM_REG_PPC_TB_OFFSET | 64
2009 PPC | KVM_REG_PPC_SPMC1 | 32
2010 PPC | KVM_REG_PPC_SPMC2 | 32
2011 PPC | KVM_REG_PPC_IAMR | 64
2012 PPC | KVM_REG_PPC_TFHAR | 64
2013 PPC | KVM_REG_PPC_TFIAR | 64
2014 PPC | KVM_REG_PPC_TEXASR | 64
2015 PPC | KVM_REG_PPC_FSCR | 64
2016 PPC | KVM_REG_PPC_PSPB | 32
2017 PPC | KVM_REG_PPC_EBBHR | 64
2018 PPC | KVM_REG_PPC_EBBRR | 64
2019 PPC | KVM_REG_PPC_BESCR | 64
2020 PPC | KVM_REG_PPC_TAR | 64
2021 PPC | KVM_REG_PPC_DPDES | 64
2022 PPC | KVM_REG_PPC_DAWR | 64
2023 PPC | KVM_REG_PPC_DAWRX | 64
2024 PPC | KVM_REG_PPC_CIABR | 64
2025 PPC | KVM_REG_PPC_IC | 64
2026 PPC | KVM_REG_PPC_VTB | 64
2027 PPC | KVM_REG_PPC_CSIGR | 64
2028 PPC | KVM_REG_PPC_TACR | 64
2029 PPC | KVM_REG_PPC_TCSCR | 64
2030 PPC | KVM_REG_PPC_PID | 64
2031 PPC | KVM_REG_PPC_ACOP | 64
2032 PPC | KVM_REG_PPC_VRSAVE | 32
cc568ead
PB
2033 PPC | KVM_REG_PPC_LPCR | 32
2034 PPC | KVM_REG_PPC_LPCR_64 | 64
bf5590f3
JH
2035 PPC | KVM_REG_PPC_PPR | 64
2036 PPC | KVM_REG_PPC_ARCH_COMPAT | 32
2037 PPC | KVM_REG_PPC_DABRX | 32
2038 PPC | KVM_REG_PPC_WORT | 64
bc8a4e5c
BB
2039 PPC | KVM_REG_PPC_SPRG9 | 64
2040 PPC | KVM_REG_PPC_DBSR | 32
e9cf1e08
PM
2041 PPC | KVM_REG_PPC_TIDR | 64
2042 PPC | KVM_REG_PPC_PSSCR | 64
bf5590f3 2043 PPC | KVM_REG_PPC_TM_GPR0 | 64
3b783474 2044 ...
bf5590f3
JH
2045 PPC | KVM_REG_PPC_TM_GPR31 | 64
2046 PPC | KVM_REG_PPC_TM_VSR0 | 128
3b783474 2047 ...
bf5590f3
JH
2048 PPC | KVM_REG_PPC_TM_VSR63 | 128
2049 PPC | KVM_REG_PPC_TM_CR | 64
2050 PPC | KVM_REG_PPC_TM_LR | 64
2051 PPC | KVM_REG_PPC_TM_CTR | 64
2052 PPC | KVM_REG_PPC_TM_FPSCR | 64
2053 PPC | KVM_REG_PPC_TM_AMR | 64
2054 PPC | KVM_REG_PPC_TM_PPR | 64
2055 PPC | KVM_REG_PPC_TM_VRSAVE | 64
2056 PPC | KVM_REG_PPC_TM_VSCR | 32
2057 PPC | KVM_REG_PPC_TM_DSCR | 64
2058 PPC | KVM_REG_PPC_TM_TAR | 64
0d808df0 2059 PPC | KVM_REG_PPC_TM_XER | 64
c2d2c21b
JH
2060 | |
2061 MIPS | KVM_REG_MIPS_R0 | 64
2062 ...
2063 MIPS | KVM_REG_MIPS_R31 | 64
2064 MIPS | KVM_REG_MIPS_HI | 64
2065 MIPS | KVM_REG_MIPS_LO | 64
2066 MIPS | KVM_REG_MIPS_PC | 64
2067 MIPS | KVM_REG_MIPS_CP0_INDEX | 32
013044cc
JH
2068 MIPS | KVM_REG_MIPS_CP0_ENTRYLO0 | 64
2069 MIPS | KVM_REG_MIPS_CP0_ENTRYLO1 | 64
c2d2c21b
JH
2070 MIPS | KVM_REG_MIPS_CP0_CONTEXT | 64
2071 MIPS | KVM_REG_MIPS_CP0_USERLOCAL | 64
2072 MIPS | KVM_REG_MIPS_CP0_PAGEMASK | 32
2073 MIPS | KVM_REG_MIPS_CP0_WIRED | 32
2074 MIPS | KVM_REG_MIPS_CP0_HWRENA | 32
2075 MIPS | KVM_REG_MIPS_CP0_BADVADDR | 64
2076 MIPS | KVM_REG_MIPS_CP0_COUNT | 32
2077 MIPS | KVM_REG_MIPS_CP0_ENTRYHI | 64
2078 MIPS | KVM_REG_MIPS_CP0_COMPARE | 32
2079 MIPS | KVM_REG_MIPS_CP0_STATUS | 32
ad58d4d4 2080 MIPS | KVM_REG_MIPS_CP0_INTCTL | 32
c2d2c21b
JH
2081 MIPS | KVM_REG_MIPS_CP0_CAUSE | 32
2082 MIPS | KVM_REG_MIPS_CP0_EPC | 64
1068eaaf 2083 MIPS | KVM_REG_MIPS_CP0_PRID | 32
7801bbe1 2084 MIPS | KVM_REG_MIPS_CP0_EBASE | 64
c2d2c21b
JH
2085 MIPS | KVM_REG_MIPS_CP0_CONFIG | 32
2086 MIPS | KVM_REG_MIPS_CP0_CONFIG1 | 32
2087 MIPS | KVM_REG_MIPS_CP0_CONFIG2 | 32
2088 MIPS | KVM_REG_MIPS_CP0_CONFIG3 | 32
c771607a
JH
2089 MIPS | KVM_REG_MIPS_CP0_CONFIG4 | 32
2090 MIPS | KVM_REG_MIPS_CP0_CONFIG5 | 32
c2d2c21b
JH
2091 MIPS | KVM_REG_MIPS_CP0_CONFIG7 | 32
2092 MIPS | KVM_REG_MIPS_CP0_ERROREPC | 64
05108709
JH
2093 MIPS | KVM_REG_MIPS_CP0_KSCRATCH1 | 64
2094 MIPS | KVM_REG_MIPS_CP0_KSCRATCH2 | 64
2095 MIPS | KVM_REG_MIPS_CP0_KSCRATCH3 | 64
2096 MIPS | KVM_REG_MIPS_CP0_KSCRATCH4 | 64
2097 MIPS | KVM_REG_MIPS_CP0_KSCRATCH5 | 64
2098 MIPS | KVM_REG_MIPS_CP0_KSCRATCH6 | 64
c2d2c21b
JH
2099 MIPS | KVM_REG_MIPS_COUNT_CTL | 64
2100 MIPS | KVM_REG_MIPS_COUNT_RESUME | 64
2101 MIPS | KVM_REG_MIPS_COUNT_HZ | 64
379245cd
JH
2102 MIPS | KVM_REG_MIPS_FPR_32(0..31) | 32
2103 MIPS | KVM_REG_MIPS_FPR_64(0..31) | 64
ab86bd60 2104 MIPS | KVM_REG_MIPS_VEC_128(0..31) | 128
379245cd
JH
2105 MIPS | KVM_REG_MIPS_FCR_IR | 32
2106 MIPS | KVM_REG_MIPS_FCR_CSR | 32
ab86bd60
JH
2107 MIPS | KVM_REG_MIPS_MSA_IR | 32
2108 MIPS | KVM_REG_MIPS_MSA_CSR | 32
414fa985 2109
749cf76c
CD
2110ARM registers are mapped using the lower 32 bits. The upper 16 of that
2111is the register group type, or coprocessor number:
2112
2113ARM core registers have the following id bit patterns:
aa404ddf 2114 0x4020 0000 0010 <index into the kvm_regs struct:16>
749cf76c 2115
1138245c 2116ARM 32-bit CP15 registers have the following id bit patterns:
aa404ddf 2117 0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3>
1138245c
CD
2118
2119ARM 64-bit CP15 registers have the following id bit patterns:
aa404ddf 2120 0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3>
749cf76c 2121
c27581ed 2122ARM CCSIDR registers are demultiplexed by CSSELR value:
aa404ddf 2123 0x4020 0000 0011 00 <csselr:8>
749cf76c 2124
4fe21e4c 2125ARM 32-bit VFP control registers have the following id bit patterns:
aa404ddf 2126 0x4020 0000 0012 1 <regno:12>
4fe21e4c
RR
2127
2128ARM 64-bit FP registers have the following id bit patterns:
aa404ddf 2129 0x4030 0000 0012 0 <regno:12>
4fe21e4c 2130
379e04c7
MZ
2131
2132arm64 registers are mapped using the lower 32 bits. The upper 16 of
2133that is the register group type, or coprocessor number:
2134
2135arm64 core/FP-SIMD registers have the following id bit patterns. Note
2136that the size of the access is variable, as the kvm_regs structure
2137contains elements ranging from 32 to 128 bits. The index is a 32bit
2138value in the kvm_regs structure seen as a 32bit array.
2139 0x60x0 0000 0010 <index into the kvm_regs struct:16>
2140
2141arm64 CCSIDR registers are demultiplexed by CSSELR value:
2142 0x6020 0000 0011 00 <csselr:8>
2143
2144arm64 system registers have the following id bit patterns:
2145 0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3>
2146
c2d2c21b
JH
2147
2148MIPS registers are mapped using the lower 32 bits. The upper 16 of that is
2149the register group type:
2150
2151MIPS core registers (see above) have the following id bit patterns:
2152 0x7030 0000 0000 <reg:16>
2153
2154MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit
2155patterns depending on whether they're 32-bit or 64-bit registers:
2156 0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit)
2157 0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit)
2158
013044cc
JH
2159Note: KVM_REG_MIPS_CP0_ENTRYLO0 and KVM_REG_MIPS_CP0_ENTRYLO1 are the MIPS64
2160versions of the EntryLo registers regardless of the word size of the host
2161hardware, host kernel, guest, and whether XPA is present in the guest, i.e.
2162with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and
2163the PFNX field starting at bit 30.
2164
c2d2c21b
JH
2165MIPS KVM control registers (see above) have the following id bit patterns:
2166 0x7030 0000 0002 <reg:16>
2167
379245cd
JH
2168MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following
2169id bit patterns depending on the size of the register being accessed. They are
2170always accessed according to the current guest FPU mode (Status.FR and
2171Config5.FRE), i.e. as the guest would see them, and they become unpredictable
ab86bd60
JH
2172if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector
2173registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they
2174overlap the FPU registers:
379245cd
JH
2175 0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers)
2176 0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers)
ab86bd60 2177 0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers)
379245cd
JH
2178
2179MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the
2180following id bit patterns:
2181 0x7020 0000 0003 01 <0:3> <reg:5>
2182
ab86bd60
JH
2183MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the
2184following id bit patterns:
2185 0x7020 0000 0003 02 <0:3> <reg:5>
2186
c2d2c21b 2187
e24ed81f
AG
21884.69 KVM_GET_ONE_REG
2189
2190Capability: KVM_CAP_ONE_REG
2191Architectures: all
2192Type: vcpu ioctl
2193Parameters: struct kvm_one_reg (in and out)
2194Returns: 0 on success, negative value on failure
2195
2196This ioctl allows to receive the value of a single register implemented
2197in a vcpu. The register to read is indicated by the "id" field of the
2198kvm_one_reg struct passed in. On success, the register value can be found
2199at the memory location pointed to by "addr".
2200
2201The list of registers accessible using this interface is identical to the
2e232702 2202list in 4.68.
e24ed81f 2203
414fa985 2204
1c0b28c2
EM
22054.70 KVM_KVMCLOCK_CTRL
2206
2207Capability: KVM_CAP_KVMCLOCK_CTRL
2208Architectures: Any that implement pvclocks (currently x86 only)
2209Type: vcpu ioctl
2210Parameters: None
2211Returns: 0 on success, -1 on error
2212
2213This signals to the host kernel that the specified guest is being paused by
2214userspace. The host will set a flag in the pvclock structure that is checked
2215from the soft lockup watchdog. The flag is part of the pvclock structure that
2216is shared between guest and host, specifically the second bit of the flags
2217field of the pvclock_vcpu_time_info structure. It will be set exclusively by
2218the host and read/cleared exclusively by the guest. The guest operation of
2219checking and clearing the flag must an atomic operation so
2220load-link/store-conditional, or equivalent must be used. There are two cases
2221where the guest will clear the flag: when the soft lockup watchdog timer resets
2222itself or when a soft lockup is detected. This ioctl can be called any time
2223after pausing the vcpu, but before it is resumed.
2224
414fa985 2225
07975ad3
JK
22264.71 KVM_SIGNAL_MSI
2227
2228Capability: KVM_CAP_SIGNAL_MSI
2988509d 2229Architectures: x86 arm arm64
07975ad3
JK
2230Type: vm ioctl
2231Parameters: struct kvm_msi (in)
2232Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
2233
2234Directly inject a MSI message. Only valid with in-kernel irqchip that handles
2235MSI messages.
2236
2237struct kvm_msi {
2238 __u32 address_lo;
2239 __u32 address_hi;
2240 __u32 data;
2241 __u32 flags;
2b8ddd93
AP
2242 __u32 devid;
2243 __u8 pad[12];
07975ad3
JK
2244};
2245
6f49b2f3
PB
2246flags: KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM
2247 KVM_CAP_MSI_DEVID capability advertises the requirement to provide
2248 the device ID. If this capability is not available, userspace
2249 should never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
2b8ddd93 2250
6f49b2f3
PB
2251If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier
2252for the device that wrote the MSI message. For PCI, this is usually a
2253BFD identifier in the lower 16 bits.
07975ad3 2254
055b6ae9
PB
2255On x86, address_hi is ignored unless the KVM_X2APIC_API_USE_32BIT_IDS
2256feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,
2257address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of
2258address_hi must be zero.
37131313 2259
414fa985 2260
0589ff6c
JK
22614.71 KVM_CREATE_PIT2
2262
2263Capability: KVM_CAP_PIT2
2264Architectures: x86
2265Type: vm ioctl
2266Parameters: struct kvm_pit_config (in)
2267Returns: 0 on success, -1 on error
2268
2269Creates an in-kernel device model for the i8254 PIT. This call is only valid
2270after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following
2271parameters have to be passed:
2272
2273struct kvm_pit_config {
2274 __u32 flags;
2275 __u32 pad[15];
2276};
2277
2278Valid flags are:
2279
2280#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */
2281
b6ddf05f
JK
2282PIT timer interrupts may use a per-VM kernel thread for injection. If it
2283exists, this thread will have a name of the following pattern:
2284
2285kvm-pit/<owner-process-pid>
2286
2287When running a guest with elevated priorities, the scheduling parameters of
2288this thread may have to be adjusted accordingly.
2289
0589ff6c
JK
2290This IOCTL replaces the obsolete KVM_CREATE_PIT.
2291
2292
22934.72 KVM_GET_PIT2
2294
2295Capability: KVM_CAP_PIT_STATE2
2296Architectures: x86
2297Type: vm ioctl
2298Parameters: struct kvm_pit_state2 (out)
2299Returns: 0 on success, -1 on error
2300
2301Retrieves the state of the in-kernel PIT model. Only valid after
2302KVM_CREATE_PIT2. The state is returned in the following structure:
2303
2304struct kvm_pit_state2 {
2305 struct kvm_pit_channel_state channels[3];
2306 __u32 flags;
2307 __u32 reserved[9];
2308};
2309
2310Valid flags are:
2311
2312/* disable PIT in HPET legacy mode */
2313#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001
2314
2315This IOCTL replaces the obsolete KVM_GET_PIT.
2316
2317
23184.73 KVM_SET_PIT2
2319
2320Capability: KVM_CAP_PIT_STATE2
2321Architectures: x86
2322Type: vm ioctl
2323Parameters: struct kvm_pit_state2 (in)
2324Returns: 0 on success, -1 on error
2325
2326Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
2327See KVM_GET_PIT2 for details on struct kvm_pit_state2.
2328
2329This IOCTL replaces the obsolete KVM_SET_PIT.
2330
2331
5b74716e
BH
23324.74 KVM_PPC_GET_SMMU_INFO
2333
2334Capability: KVM_CAP_PPC_GET_SMMU_INFO
2335Architectures: powerpc
2336Type: vm ioctl
2337Parameters: None
2338Returns: 0 on success, -1 on error
2339
2340This populates and returns a structure describing the features of
2341the "Server" class MMU emulation supported by KVM.
cc22c354 2342This can in turn be used by userspace to generate the appropriate
5b74716e
BH
2343device-tree properties for the guest operating system.
2344
c98be0c9 2345The structure contains some global information, followed by an
5b74716e
BH
2346array of supported segment page sizes:
2347
2348 struct kvm_ppc_smmu_info {
2349 __u64 flags;
2350 __u32 slb_size;
2351 __u32 pad;
2352 struct kvm_ppc_one_seg_page_size sps[KVM_PPC_PAGE_SIZES_MAX_SZ];
2353 };
2354
2355The supported flags are:
2356
2357 - KVM_PPC_PAGE_SIZES_REAL:
2358 When that flag is set, guest page sizes must "fit" the backing
2359 store page sizes. When not set, any page size in the list can
2360 be used regardless of how they are backed by userspace.
2361
2362 - KVM_PPC_1T_SEGMENTS
2363 The emulated MMU supports 1T segments in addition to the
2364 standard 256M ones.
2365
2366The "slb_size" field indicates how many SLB entries are supported
2367
2368The "sps" array contains 8 entries indicating the supported base
2369page sizes for a segment in increasing order. Each entry is defined
2370as follow:
2371
2372 struct kvm_ppc_one_seg_page_size {
2373 __u32 page_shift; /* Base page shift of segment (or 0) */
2374 __u32 slb_enc; /* SLB encoding for BookS */
2375 struct kvm_ppc_one_page_size enc[KVM_PPC_PAGE_SIZES_MAX_SZ];
2376 };
2377
2378An entry with a "page_shift" of 0 is unused. Because the array is
2379organized in increasing order, a lookup can stop when encoutering
2380such an entry.
2381
2382The "slb_enc" field provides the encoding to use in the SLB for the
2383page size. The bits are in positions such as the value can directly
2384be OR'ed into the "vsid" argument of the slbmte instruction.
2385
2386The "enc" array is a list which for each of those segment base page
2387size provides the list of supported actual page sizes (which can be
2388only larger or equal to the base page size), along with the
f884ab15 2389corresponding encoding in the hash PTE. Similarly, the array is
5b74716e
BH
23908 entries sorted by increasing sizes and an entry with a "0" shift
2391is an empty entry and a terminator:
2392
2393 struct kvm_ppc_one_page_size {
2394 __u32 page_shift; /* Page shift (or 0) */
2395 __u32 pte_enc; /* Encoding in the HPTE (>>12) */
2396 };
2397
2398The "pte_enc" field provides a value that can OR'ed into the hash
2399PTE's RPN field (ie, it needs to be shifted left by 12 to OR it
2400into the hash PTE second double word).
2401
f36992e3
AW
24024.75 KVM_IRQFD
2403
2404Capability: KVM_CAP_IRQFD
174178fe 2405Architectures: x86 s390 arm arm64
f36992e3
AW
2406Type: vm ioctl
2407Parameters: struct kvm_irqfd (in)
2408Returns: 0 on success, -1 on error
2409
2410Allows setting an eventfd to directly trigger a guest interrupt.
2411kvm_irqfd.fd specifies the file descriptor to use as the eventfd and
2412kvm_irqfd.gsi specifies the irqchip pin toggled by this event. When
17180032 2413an event is triggered on the eventfd, an interrupt is injected into
f36992e3
AW
2414the guest using the specified gsi pin. The irqfd is removed using
2415the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd
2416and kvm_irqfd.gsi.
2417
7a84428a
AW
2418With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify
2419mechanism allowing emulation of level-triggered, irqfd-based
2420interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an
2421additional eventfd in the kvm_irqfd.resamplefd field. When operating
2422in resample mode, posting of an interrupt through kvm_irq.fd asserts
2423the specified gsi in the irqchip. When the irqchip is resampled, such
17180032 2424as from an EOI, the gsi is de-asserted and the user is notified via
7a84428a
AW
2425kvm_irqfd.resamplefd. It is the user's responsibility to re-queue
2426the interrupt if the device making use of it still requires service.
2427Note that closing the resamplefd is not sufficient to disable the
2428irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment
2429and need not be specified with KVM_IRQFD_FLAG_DEASSIGN.
2430
180ae7b1
EA
2431On arm/arm64, gsi routing being supported, the following can happen:
2432- in case no routing entry is associated to this gsi, injection fails
2433- in case the gsi is associated to an irqchip routing entry,
2434 irqchip.pin + 32 corresponds to the injected SPI ID.
995a0ee9
EA
2435- in case the gsi is associated to an MSI routing entry, the MSI
2436 message and device ID are translated into an LPI (support restricted
2437 to GICv3 ITS in-kernel emulation).
174178fe 2438
5fecc9d8 24394.76 KVM_PPC_ALLOCATE_HTAB
32fad281
PM
2440
2441Capability: KVM_CAP_PPC_ALLOC_HTAB
2442Architectures: powerpc
2443Type: vm ioctl
2444Parameters: Pointer to u32 containing hash table order (in/out)
2445Returns: 0 on success, -1 on error
2446
2447This requests the host kernel to allocate an MMU hash table for a
2448guest using the PAPR paravirtualization interface. This only does
2449anything if the kernel is configured to use the Book 3S HV style of
2450virtualization. Otherwise the capability doesn't exist and the ioctl
2451returns an ENOTTY error. The rest of this description assumes Book 3S
2452HV.
2453
2454There must be no vcpus running when this ioctl is called; if there
2455are, it will do nothing and return an EBUSY error.
2456
2457The parameter is a pointer to a 32-bit unsigned integer variable
2458containing the order (log base 2) of the desired size of the hash
2459table, which must be between 18 and 46. On successful return from the
f98a8bf9 2460ioctl, the value will not be changed by the kernel.
32fad281
PM
2461
2462If no hash table has been allocated when any vcpu is asked to run
2463(with the KVM_RUN ioctl), the host kernel will allocate a
2464default-sized hash table (16 MB).
2465
2466If this ioctl is called when a hash table has already been allocated,
f98a8bf9
DG
2467with a different order from the existing hash table, the existing hash
2468table will be freed and a new one allocated. If this is ioctl is
2469called when a hash table has already been allocated of the same order
2470as specified, the kernel will clear out the existing hash table (zero
2471all HPTEs). In either case, if the guest is using the virtualized
2472real-mode area (VRMA) facility, the kernel will re-create the VMRA
2473HPTEs on the next KVM_RUN of any vcpu.
32fad281 2474
416ad65f
CH
24754.77 KVM_S390_INTERRUPT
2476
2477Capability: basic
2478Architectures: s390
2479Type: vm ioctl, vcpu ioctl
2480Parameters: struct kvm_s390_interrupt (in)
2481Returns: 0 on success, -1 on error
2482
2483Allows to inject an interrupt to the guest. Interrupts can be floating
2484(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.
2485
2486Interrupt parameters are passed via kvm_s390_interrupt:
2487
2488struct kvm_s390_interrupt {
2489 __u32 type;
2490 __u32 parm;
2491 __u64 parm64;
2492};
2493
2494type can be one of the following:
2495
2822545f 2496KVM_S390_SIGP_STOP (vcpu) - sigp stop; optional flags in parm
416ad65f
CH
2497KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm
2498KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm
2499KVM_S390_RESTART (vcpu) - restart
e029ae5b
TH
2500KVM_S390_INT_CLOCK_COMP (vcpu) - clock comparator interrupt
2501KVM_S390_INT_CPU_TIMER (vcpu) - CPU timer interrupt
416ad65f
CH
2502KVM_S390_INT_VIRTIO (vm) - virtio external interrupt; external interrupt
2503 parameters in parm and parm64
2504KVM_S390_INT_SERVICE (vm) - sclp external interrupt; sclp parameter in parm
2505KVM_S390_INT_EMERGENCY (vcpu) - sigp emergency; source cpu in parm
2506KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm
d8346b7d
CH
2507KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm) - compound value to indicate an
2508 I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);
2509 I/O interruption parameters in parm (subchannel) and parm64 (intparm,
2510 interruption subclass)
48a3e950
CH
2511KVM_S390_MCHK (vm, vcpu) - machine check interrupt; cr 14 bits in parm,
2512 machine check interrupt code in parm64 (note that
2513 machine checks needing further payload are not
2514 supported by this ioctl)
416ad65f
CH
2515
2516Note that the vcpu ioctl is asynchronous to vcpu execution.
2517
a2932923
PM
25184.78 KVM_PPC_GET_HTAB_FD
2519
2520Capability: KVM_CAP_PPC_HTAB_FD
2521Architectures: powerpc
2522Type: vm ioctl
2523Parameters: Pointer to struct kvm_get_htab_fd (in)
2524Returns: file descriptor number (>= 0) on success, -1 on error
2525
2526This returns a file descriptor that can be used either to read out the
2527entries in the guest's hashed page table (HPT), or to write entries to
2528initialize the HPT. The returned fd can only be written to if the
2529KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
2530can only be read if that bit is clear. The argument struct looks like
2531this:
2532
2533/* For KVM_PPC_GET_HTAB_FD */
2534struct kvm_get_htab_fd {
2535 __u64 flags;
2536 __u64 start_index;
2537 __u64 reserved[2];
2538};
2539
2540/* Values for kvm_get_htab_fd.flags */
2541#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
2542#define KVM_GET_HTAB_WRITE ((__u64)0x2)
2543
2544The `start_index' field gives the index in the HPT of the entry at
2545which to start reading. It is ignored when writing.
2546
2547Reads on the fd will initially supply information about all
2548"interesting" HPT entries. Interesting entries are those with the
2549bolted bit set, if the KVM_GET_HTAB_BOLTED_ONLY bit is set, otherwise
2550all entries. When the end of the HPT is reached, the read() will
2551return. If read() is called again on the fd, it will start again from
2552the beginning of the HPT, but will only return HPT entries that have
2553changed since they were last read.
2554
2555Data read or written is structured as a header (8 bytes) followed by a
2556series of valid HPT entries (16 bytes) each. The header indicates how
2557many valid HPT entries there are and how many invalid entries follow
2558the valid entries. The invalid entries are not represented explicitly
2559in the stream. The header format is:
2560
2561struct kvm_get_htab_header {
2562 __u32 index;
2563 __u16 n_valid;
2564 __u16 n_invalid;
2565};
2566
2567Writes to the fd create HPT entries starting at the index given in the
2568header; first `n_valid' valid entries with contents from the data
2569written, then `n_invalid' invalid entries, invalidating any previously
2570valid entries found.
2571
852b6d57
SW
25724.79 KVM_CREATE_DEVICE
2573
2574Capability: KVM_CAP_DEVICE_CTRL
2575Type: vm ioctl
2576Parameters: struct kvm_create_device (in/out)
2577Returns: 0 on success, -1 on error
2578Errors:
2579 ENODEV: The device type is unknown or unsupported
2580 EEXIST: Device already created, and this type of device may not
2581 be instantiated multiple times
2582
2583 Other error conditions may be defined by individual device types or
2584 have their standard meanings.
2585
2586Creates an emulated device in the kernel. The file descriptor returned
2587in fd can be used with KVM_SET/GET/HAS_DEVICE_ATTR.
2588
2589If the KVM_CREATE_DEVICE_TEST flag is set, only test whether the
2590device type is supported (not necessarily whether it can be created
2591in the current vm).
2592
2593Individual devices should not define flags. Attributes should be used
2594for specifying any behavior that is not implied by the device type
2595number.
2596
2597struct kvm_create_device {
2598 __u32 type; /* in: KVM_DEV_TYPE_xxx */
2599 __u32 fd; /* out: device handle */
2600 __u32 flags; /* in: KVM_CREATE_DEVICE_xxx */
2601};
2602
26034.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR
2604
f577f6c2
SZ
2605Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
2606 KVM_CAP_VCPU_ATTRIBUTES for vcpu device
2607Type: device ioctl, vm ioctl, vcpu ioctl
852b6d57
SW
2608Parameters: struct kvm_device_attr
2609Returns: 0 on success, -1 on error
2610Errors:
2611 ENXIO: The group or attribute is unknown/unsupported for this device
f9cbd9b0 2612 or hardware support is missing.
852b6d57
SW
2613 EPERM: The attribute cannot (currently) be accessed this way
2614 (e.g. read-only attribute, or attribute that only makes
2615 sense when the device is in a different state)
2616
2617 Other error conditions may be defined by individual device types.
2618
2619Gets/sets a specified piece of device configuration and/or state. The
2620semantics are device-specific. See individual device documentation in
2621the "devices" directory. As with ONE_REG, the size of the data
2622transferred is defined by the particular attribute.
2623
2624struct kvm_device_attr {
2625 __u32 flags; /* no flags currently defined */
2626 __u32 group; /* device-defined */
2627 __u64 attr; /* group-defined */
2628 __u64 addr; /* userspace address of attr data */
2629};
2630
26314.81 KVM_HAS_DEVICE_ATTR
2632
f577f6c2
SZ
2633Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
2634 KVM_CAP_VCPU_ATTRIBUTES for vcpu device
2635Type: device ioctl, vm ioctl, vcpu ioctl
852b6d57
SW
2636Parameters: struct kvm_device_attr
2637Returns: 0 on success, -1 on error
2638Errors:
2639 ENXIO: The group or attribute is unknown/unsupported for this device
f9cbd9b0 2640 or hardware support is missing.
852b6d57
SW
2641
2642Tests whether a device supports a particular attribute. A successful
2643return indicates the attribute is implemented. It does not necessarily
2644indicate that the attribute can be read or written in the device's
2645current state. "addr" is ignored.
f36992e3 2646
d8968f1f 26474.82 KVM_ARM_VCPU_INIT
749cf76c
CD
2648
2649Capability: basic
379e04c7 2650Architectures: arm, arm64
749cf76c 2651Type: vcpu ioctl
beb11fc7 2652Parameters: struct kvm_vcpu_init (in)
749cf76c
CD
2653Returns: 0 on success; -1 on error
2654Errors:
2655  EINVAL:    the target is unknown, or the combination of features is invalid.
2656  ENOENT:    a features bit specified is unknown.
2657
2658This tells KVM what type of CPU to present to the guest, and what
2659optional features it should have.  This will cause a reset of the cpu
2660registers to their initial values.  If this is not called, KVM_RUN will
2661return ENOEXEC for that vcpu.
2662
2663Note that because some registers reflect machine topology, all vcpus
2664should be created before this ioctl is invoked.
2665
f7fa034d
CD
2666Userspace can call this function multiple times for a given vcpu, including
2667after the vcpu has been run. This will reset the vcpu to its initial
2668state. All calls to this function after the initial call must use the same
2669target and same set of feature flags, otherwise EINVAL will be returned.
2670
aa024c2f
MZ
2671Possible features:
2672 - KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state.
3ad8b3de
CD
2673 Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on
2674 and execute guest code when KVM_RUN is called.
379e04c7
MZ
2675 - KVM_ARM_VCPU_EL1_32BIT: Starts the CPU in a 32bit mode.
2676 Depends on KVM_CAP_ARM_EL1_32BIT (arm64 only).
50bb0c94
AP
2677 - KVM_ARM_VCPU_PSCI_0_2: Emulate PSCI v0.2 for the CPU.
2678 Depends on KVM_CAP_ARM_PSCI_0_2.
808e7381
SZ
2679 - KVM_ARM_VCPU_PMU_V3: Emulate PMUv3 for the CPU.
2680 Depends on KVM_CAP_ARM_PMU_V3.
aa024c2f 2681
749cf76c 2682
740edfc0
AP
26834.83 KVM_ARM_PREFERRED_TARGET
2684
2685Capability: basic
2686Architectures: arm, arm64
2687Type: vm ioctl
2688Parameters: struct struct kvm_vcpu_init (out)
2689Returns: 0 on success; -1 on error
2690Errors:
a7265fb1 2691 ENODEV: no preferred target available for the host
740edfc0
AP
2692
2693This queries KVM for preferred CPU target type which can be emulated
2694by KVM on underlying host.
2695
2696The ioctl returns struct kvm_vcpu_init instance containing information
2697about preferred CPU target type and recommended features for it. The
2698kvm_vcpu_init->features bitmap returned will have feature bits set if
2699the preferred target recommends setting these features, but this is
2700not mandatory.
2701
2702The information returned by this ioctl can be used to prepare an instance
2703of struct kvm_vcpu_init for KVM_ARM_VCPU_INIT ioctl which will result in
2704in VCPU matching underlying host.
2705
2706
27074.84 KVM_GET_REG_LIST
749cf76c
CD
2708
2709Capability: basic
c2d2c21b 2710Architectures: arm, arm64, mips
749cf76c
CD
2711Type: vcpu ioctl
2712Parameters: struct kvm_reg_list (in/out)
2713Returns: 0 on success; -1 on error
2714Errors:
2715  E2BIG:     the reg index list is too big to fit in the array specified by
2716             the user (the number required will be written into n).
2717
2718struct kvm_reg_list {
2719 __u64 n; /* number of registers in reg[] */
2720 __u64 reg[0];
2721};
2722
2723This ioctl returns the guest registers that are supported for the
2724KVM_GET_ONE_REG/KVM_SET_ONE_REG calls.
2725
ce01e4e8
CD
2726
27274.85 KVM_ARM_SET_DEVICE_ADDR (deprecated)
3401d546
CD
2728
2729Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
379e04c7 2730Architectures: arm, arm64
3401d546
CD
2731Type: vm ioctl
2732Parameters: struct kvm_arm_device_address (in)
2733Returns: 0 on success, -1 on error
2734Errors:
2735 ENODEV: The device id is unknown
2736 ENXIO: Device not supported on current system
2737 EEXIST: Address already set
2738 E2BIG: Address outside guest physical address space
330690cd 2739 EBUSY: Address overlaps with other device range
3401d546
CD
2740
2741struct kvm_arm_device_addr {
2742 __u64 id;
2743 __u64 addr;
2744};
2745
2746Specify a device address in the guest's physical address space where guests
2747can access emulated or directly exposed devices, which the host kernel needs
2748to know about. The id field is an architecture specific identifier for a
2749specific device.
2750
379e04c7
MZ
2751ARM/arm64 divides the id field into two parts, a device id and an
2752address type id specific to the individual device.
3401d546
CD
2753
2754  bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 |
2755 field: | 0x00000000 | device id | addr type id |
2756
379e04c7
MZ
2757ARM/arm64 currently only require this when using the in-kernel GIC
2758support for the hardware VGIC features, using KVM_ARM_DEVICE_VGIC_V2
2759as the device id. When setting the base address for the guest's
2760mapping of the VGIC virtual CPU and distributor interface, the ioctl
2761must be called after calling KVM_CREATE_IRQCHIP, but before calling
2762KVM_RUN on any of the VCPUs. Calling this ioctl twice for any of the
2763base addresses will return -EEXIST.
3401d546 2764
ce01e4e8
CD
2765Note, this IOCTL is deprecated and the more flexible SET/GET_DEVICE_ATTR API
2766should be used instead.
2767
2768
740edfc0 27694.86 KVM_PPC_RTAS_DEFINE_TOKEN
8e591cb7
ME
2770
2771Capability: KVM_CAP_PPC_RTAS
2772Architectures: ppc
2773Type: vm ioctl
2774Parameters: struct kvm_rtas_token_args
2775Returns: 0 on success, -1 on error
2776
2777Defines a token value for a RTAS (Run Time Abstraction Services)
2778service in order to allow it to be handled in the kernel. The
2779argument struct gives the name of the service, which must be the name
2780of a service that has a kernel-side implementation. If the token
2781value is non-zero, it will be associated with that service, and
2782subsequent RTAS calls by the guest specifying that token will be
2783handled by the kernel. If the token value is 0, then any token
2784associated with the service will be forgotten, and subsequent RTAS
2785calls by the guest for that service will be passed to userspace to be
2786handled.
2787
4bd9d344
AB
27884.87 KVM_SET_GUEST_DEBUG
2789
2790Capability: KVM_CAP_SET_GUEST_DEBUG
0e6f07f2 2791Architectures: x86, s390, ppc, arm64
4bd9d344
AB
2792Type: vcpu ioctl
2793Parameters: struct kvm_guest_debug (in)
2794Returns: 0 on success; -1 on error
2795
2796struct kvm_guest_debug {
2797 __u32 control;
2798 __u32 pad;
2799 struct kvm_guest_debug_arch arch;
2800};
2801
2802Set up the processor specific debug registers and configure vcpu for
2803handling guest debug events. There are two parts to the structure, the
2804first a control bitfield indicates the type of debug events to handle
2805when running. Common control bits are:
2806
2807 - KVM_GUESTDBG_ENABLE: guest debugging is enabled
2808 - KVM_GUESTDBG_SINGLESTEP: the next run should single-step
2809
2810The top 16 bits of the control field are architecture specific control
2811flags which can include the following:
2812
4bd611ca 2813 - KVM_GUESTDBG_USE_SW_BP: using software breakpoints [x86, arm64]
834bf887 2814 - KVM_GUESTDBG_USE_HW_BP: using hardware breakpoints [x86, s390, arm64]
4bd9d344
AB
2815 - KVM_GUESTDBG_INJECT_DB: inject DB type exception [x86]
2816 - KVM_GUESTDBG_INJECT_BP: inject BP type exception [x86]
2817 - KVM_GUESTDBG_EXIT_PENDING: trigger an immediate guest exit [s390]
2818
2819For example KVM_GUESTDBG_USE_SW_BP indicates that software breakpoints
2820are enabled in memory so we need to ensure breakpoint exceptions are
2821correctly trapped and the KVM run loop exits at the breakpoint and not
2822running off into the normal guest vector. For KVM_GUESTDBG_USE_HW_BP
2823we need to ensure the guest vCPUs architecture specific registers are
2824updated to the correct (supplied) values.
2825
2826The second part of the structure is architecture specific and
2827typically contains a set of debug registers.
2828
834bf887
AB
2829For arm64 the number of debug registers is implementation defined and
2830can be determined by querying the KVM_CAP_GUEST_DEBUG_HW_BPS and
2831KVM_CAP_GUEST_DEBUG_HW_WPS capabilities which return a positive number
2832indicating the number of supported registers.
2833
4bd9d344
AB
2834When debug events exit the main run loop with the reason
2835KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run
2836structure containing architecture specific debug information.
3401d546 2837
209cf19f
AB
28384.88 KVM_GET_EMULATED_CPUID
2839
2840Capability: KVM_CAP_EXT_EMUL_CPUID
2841Architectures: x86
2842Type: system ioctl
2843Parameters: struct kvm_cpuid2 (in/out)
2844Returns: 0 on success, -1 on error
2845
2846struct kvm_cpuid2 {
2847 __u32 nent;
2848 __u32 flags;
2849 struct kvm_cpuid_entry2 entries[0];
2850};
2851
2852The member 'flags' is used for passing flags from userspace.
2853
2854#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
2855#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
2856#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
2857
2858struct kvm_cpuid_entry2 {
2859 __u32 function;
2860 __u32 index;
2861 __u32 flags;
2862 __u32 eax;
2863 __u32 ebx;
2864 __u32 ecx;
2865 __u32 edx;
2866 __u32 padding[3];
2867};
2868
2869This ioctl returns x86 cpuid features which are emulated by
2870kvm.Userspace can use the information returned by this ioctl to query
2871which features are emulated by kvm instead of being present natively.
2872
2873Userspace invokes KVM_GET_EMULATED_CPUID by passing a kvm_cpuid2
2874structure with the 'nent' field indicating the number of entries in
2875the variable-size array 'entries'. If the number of entries is too low
2876to describe the cpu capabilities, an error (E2BIG) is returned. If the
2877number is too high, the 'nent' field is adjusted and an error (ENOMEM)
2878is returned. If the number is just right, the 'nent' field is adjusted
2879to the number of valid entries in the 'entries' array, which is then
2880filled.
2881
2882The entries returned are the set CPUID bits of the respective features
2883which kvm emulates, as returned by the CPUID instruction, with unknown
2884or unsupported feature bits cleared.
2885
2886Features like x2apic, for example, may not be present in the host cpu
2887but are exposed by kvm in KVM_GET_SUPPORTED_CPUID because they can be
2888emulated efficiently and thus not included here.
2889
2890The fields in each entry are defined as follows:
2891
2892 function: the eax value used to obtain the entry
2893 index: the ecx value used to obtain the entry (for entries that are
2894 affected by ecx)
2895 flags: an OR of zero or more of the following:
2896 KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
2897 if the index field is valid
2898 KVM_CPUID_FLAG_STATEFUL_FUNC:
2899 if cpuid for this function returns different values for successive
2900 invocations; there will be several entries with the same function,
2901 all with this flag set
2902 KVM_CPUID_FLAG_STATE_READ_NEXT:
2903 for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
2904 the first entry to be read by a cpu
2905 eax, ebx, ecx, edx: the values returned by the cpuid instruction for
2906 this function/index combination
2907
41408c28
TH
29084.89 KVM_S390_MEM_OP
2909
2910Capability: KVM_CAP_S390_MEM_OP
2911Architectures: s390
2912Type: vcpu ioctl
2913Parameters: struct kvm_s390_mem_op (in)
2914Returns: = 0 on success,
2915 < 0 on generic error (e.g. -EFAULT or -ENOMEM),
2916 > 0 if an exception occurred while walking the page tables
2917
5d4f6f3d 2918Read or write data from/to the logical (virtual) memory of a VCPU.
41408c28
TH
2919
2920Parameters are specified via the following structure:
2921
2922struct kvm_s390_mem_op {
2923 __u64 gaddr; /* the guest address */
2924 __u64 flags; /* flags */
2925 __u32 size; /* amount of bytes */
2926 __u32 op; /* type of operation */
2927 __u64 buf; /* buffer in userspace */
2928 __u8 ar; /* the access register number */
2929 __u8 reserved[31]; /* should be set to 0 */
2930};
2931
2932The type of operation is specified in the "op" field. It is either
2933KVM_S390_MEMOP_LOGICAL_READ for reading from logical memory space or
2934KVM_S390_MEMOP_LOGICAL_WRITE for writing to logical memory space. The
2935KVM_S390_MEMOP_F_CHECK_ONLY flag can be set in the "flags" field to check
2936whether the corresponding memory access would create an access exception
2937(without touching the data in the memory at the destination). In case an
2938access exception occurred while walking the MMU tables of the guest, the
2939ioctl returns a positive error number to indicate the type of exception.
2940This exception is also raised directly at the corresponding VCPU if the
2941flag KVM_S390_MEMOP_F_INJECT_EXCEPTION is set in the "flags" field.
2942
2943The start address of the memory region has to be specified in the "gaddr"
2944field, and the length of the region in the "size" field. "buf" is the buffer
2945supplied by the userspace application where the read data should be written
2946to for KVM_S390_MEMOP_LOGICAL_READ, or where the data that should be written
2947is stored for a KVM_S390_MEMOP_LOGICAL_WRITE. "buf" is unused and can be NULL
2948when KVM_S390_MEMOP_F_CHECK_ONLY is specified. "ar" designates the access
2949register number to be used.
2950
2951The "reserved" field is meant for future extensions. It is not used by
2952KVM with the currently defined set of flags.
2953
30ee2a98
JH
29544.90 KVM_S390_GET_SKEYS
2955
2956Capability: KVM_CAP_S390_SKEYS
2957Architectures: s390
2958Type: vm ioctl
2959Parameters: struct kvm_s390_skeys
2960Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage
2961 keys, negative value on error
2962
2963This ioctl is used to get guest storage key values on the s390
2964architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
2965
2966struct kvm_s390_skeys {
2967 __u64 start_gfn;
2968 __u64 count;
2969 __u64 skeydata_addr;
2970 __u32 flags;
2971 __u32 reserved[9];
2972};
2973
2974The start_gfn field is the number of the first guest frame whose storage keys
2975you want to get.
2976
2977The count field is the number of consecutive frames (starting from start_gfn)
2978whose storage keys to get. The count field must be at least 1 and the maximum
2979allowed value is defined as KVM_S390_SKEYS_ALLOC_MAX. Values outside this range
2980will cause the ioctl to return -EINVAL.
2981
2982The skeydata_addr field is the address to a buffer large enough to hold count
2983bytes. This buffer will be filled with storage key data by the ioctl.
2984
29854.91 KVM_S390_SET_SKEYS
2986
2987Capability: KVM_CAP_S390_SKEYS
2988Architectures: s390
2989Type: vm ioctl
2990Parameters: struct kvm_s390_skeys
2991Returns: 0 on success, negative value on error
2992
2993This ioctl is used to set guest storage key values on the s390
2994architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
2995See section on KVM_S390_GET_SKEYS for struct definition.
2996
2997The start_gfn field is the number of the first guest frame whose storage keys
2998you want to set.
2999
3000The count field is the number of consecutive frames (starting from start_gfn)
3001whose storage keys to get. The count field must be at least 1 and the maximum
3002allowed value is defined as KVM_S390_SKEYS_ALLOC_MAX. Values outside this range
3003will cause the ioctl to return -EINVAL.
3004
3005The skeydata_addr field is the address to a buffer containing count bytes of
3006storage keys. Each byte in the buffer will be set as the storage key for a
3007single frame starting at start_gfn for count frames.
3008
3009Note: If any architecturally invalid key value is found in the given data then
3010the ioctl will return -EINVAL.
3011
47b43c52
JF
30124.92 KVM_S390_IRQ
3013
3014Capability: KVM_CAP_S390_INJECT_IRQ
3015Architectures: s390
3016Type: vcpu ioctl
3017Parameters: struct kvm_s390_irq (in)
3018Returns: 0 on success, -1 on error
3019Errors:
3020 EINVAL: interrupt type is invalid
3021 type is KVM_S390_SIGP_STOP and flag parameter is invalid value
3022 type is KVM_S390_INT_EXTERNAL_CALL and code is bigger
3023 than the maximum of VCPUs
3024 EBUSY: type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped
3025 type is KVM_S390_SIGP_STOP and a stop irq is already pending
3026 type is KVM_S390_INT_EXTERNAL_CALL and an external call interrupt
3027 is already pending
3028
3029Allows to inject an interrupt to the guest.
3030
3031Using struct kvm_s390_irq as a parameter allows
3032to inject additional payload which is not
3033possible via KVM_S390_INTERRUPT.
3034
3035Interrupt parameters are passed via kvm_s390_irq:
3036
3037struct kvm_s390_irq {
3038 __u64 type;
3039 union {
3040 struct kvm_s390_io_info io;
3041 struct kvm_s390_ext_info ext;
3042 struct kvm_s390_pgm_info pgm;
3043 struct kvm_s390_emerg_info emerg;
3044 struct kvm_s390_extcall_info extcall;
3045 struct kvm_s390_prefix_info prefix;
3046 struct kvm_s390_stop_info stop;
3047 struct kvm_s390_mchk_info mchk;
3048 char reserved[64];
3049 } u;
3050};
3051
3052type can be one of the following:
3053
3054KVM_S390_SIGP_STOP - sigp stop; parameter in .stop
3055KVM_S390_PROGRAM_INT - program check; parameters in .pgm
3056KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix
3057KVM_S390_RESTART - restart; no parameters
3058KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters
3059KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters
3060KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg
3061KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall
3062KVM_S390_MCHK - machine check interrupt; parameters in .mchk
3063
3064
3065Note that the vcpu ioctl is asynchronous to vcpu execution.
3066
816c7667
JF
30674.94 KVM_S390_GET_IRQ_STATE
3068
3069Capability: KVM_CAP_S390_IRQ_STATE
3070Architectures: s390
3071Type: vcpu ioctl
3072Parameters: struct kvm_s390_irq_state (out)
3073Returns: >= number of bytes copied into buffer,
3074 -EINVAL if buffer size is 0,
3075 -ENOBUFS if buffer size is too small to fit all pending interrupts,
3076 -EFAULT if the buffer address was invalid
3077
3078This ioctl allows userspace to retrieve the complete state of all currently
3079pending interrupts in a single buffer. Use cases include migration
3080and introspection. The parameter structure contains the address of a
3081userspace buffer and its length:
3082
3083struct kvm_s390_irq_state {
3084 __u64 buf;
3085 __u32 flags;
3086 __u32 len;
3087 __u32 reserved[4];
3088};
3089
3090Userspace passes in the above struct and for each pending interrupt a
3091struct kvm_s390_irq is copied to the provided buffer.
3092
3093If -ENOBUFS is returned the buffer provided was too small and userspace
3094may retry with a bigger buffer.
3095
30964.95 KVM_S390_SET_IRQ_STATE
3097
3098Capability: KVM_CAP_S390_IRQ_STATE
3099Architectures: s390
3100Type: vcpu ioctl
3101Parameters: struct kvm_s390_irq_state (in)
3102Returns: 0 on success,
3103 -EFAULT if the buffer address was invalid,
3104 -EINVAL for an invalid buffer length (see below),
3105 -EBUSY if there were already interrupts pending,
3106 errors occurring when actually injecting the
3107 interrupt. See KVM_S390_IRQ.
3108
3109This ioctl allows userspace to set the complete state of all cpu-local
3110interrupts currently pending for the vcpu. It is intended for restoring
3111interrupt state after a migration. The input parameter is a userspace buffer
3112containing a struct kvm_s390_irq_state:
3113
3114struct kvm_s390_irq_state {
3115 __u64 buf;
3116 __u32 len;
3117 __u32 pad;
3118};
3119
3120The userspace memory referenced by buf contains a struct kvm_s390_irq
3121for each interrupt to be injected into the guest.
3122If one of the interrupts could not be injected for some reason the
3123ioctl aborts.
3124
3125len must be a multiple of sizeof(struct kvm_s390_irq). It must be > 0
3126and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq),
3127which is the maximum number of possibly pending cpu-local interrupts.
47b43c52 3128
ed8e5a24 31294.96 KVM_SMI
f077825a
PB
3130
3131Capability: KVM_CAP_X86_SMM
3132Architectures: x86
3133Type: vcpu ioctl
3134Parameters: none
3135Returns: 0 on success, -1 on error
3136
3137Queues an SMI on the thread's vcpu.
3138
d3695aa4
AK
31394.97 KVM_CAP_PPC_MULTITCE
3140
3141Capability: KVM_CAP_PPC_MULTITCE
3142Architectures: ppc
3143Type: vm
3144
3145This capability means the kernel is capable of handling hypercalls
3146H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user
3147space. This significantly accelerates DMA operations for PPC KVM guests.
3148User space should expect that its handlers for these hypercalls
3149are not going to be called if user space previously registered LIOBN
3150in KVM (via KVM_CREATE_SPAPR_TCE or similar calls).
3151
3152In order to enable H_PUT_TCE_INDIRECT and H_STUFF_TCE use in the guest,
3153user space might have to advertise it for the guest. For example,
3154IBM pSeries (sPAPR) guest starts using them if "hcall-multi-tce" is
3155present in the "ibm,hypertas-functions" device-tree property.
3156
3157The hypercalls mentioned above may or may not be processed successfully
3158in the kernel based fast path. If they can not be handled by the kernel,
3159they will get passed on to user space. So user space still has to have
3160an implementation for these despite the in kernel acceleration.
3161
3162This capability is always enabled.
3163
58ded420
AK
31644.98 KVM_CREATE_SPAPR_TCE_64
3165
3166Capability: KVM_CAP_SPAPR_TCE_64
3167Architectures: powerpc
3168Type: vm ioctl
3169Parameters: struct kvm_create_spapr_tce_64 (in)
3170Returns: file descriptor for manipulating the created TCE table
3171
3172This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit
3173windows, described in 4.62 KVM_CREATE_SPAPR_TCE
3174
3175This capability uses extended struct in ioctl interface:
3176
3177/* for KVM_CAP_SPAPR_TCE_64 */
3178struct kvm_create_spapr_tce_64 {
3179 __u64 liobn;
3180 __u32 page_shift;
3181 __u32 flags;
3182 __u64 offset; /* in pages */
3183 __u64 size; /* in pages */
3184};
3185
3186The aim of extension is to support an additional bigger DMA window with
3187a variable page size.
3188KVM_CREATE_SPAPR_TCE_64 receives a 64bit window size, an IOMMU page shift and
3189a bus offset of the corresponding DMA window, @size and @offset are numbers
3190of IOMMU pages.
3191
3192@flags are not used at the moment.
3193
3194The rest of functionality is identical to KVM_CREATE_SPAPR_TCE.
3195
ccc4df4e 31964.99 KVM_REINJECT_CONTROL
107d44a2
RK
3197
3198Capability: KVM_CAP_REINJECT_CONTROL
3199Architectures: x86
3200Type: vm ioctl
3201Parameters: struct kvm_reinject_control (in)
3202Returns: 0 on success,
3203 -EFAULT if struct kvm_reinject_control cannot be read,
3204 -ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier.
3205
3206i8254 (PIT) has two modes, reinject and !reinject. The default is reinject,
3207where KVM queues elapsed i8254 ticks and monitors completion of interrupt from
3208vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its
3209interrupt whenever there isn't a pending interrupt from i8254.
3210!reinject mode injects an interrupt as soon as a tick arrives.
3211
3212struct kvm_reinject_control {
3213 __u8 pit_reinject;
3214 __u8 reserved[31];
3215};
3216
3217pit_reinject = 0 (!reinject mode) is recommended, unless running an old
3218operating system that uses the PIT for timing (e.g. Linux 2.4.x).
3219
ccc4df4e 32204.100 KVM_PPC_CONFIGURE_V3_MMU
c9270132
PM
3221
3222Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3
3223Architectures: ppc
3224Type: vm ioctl
3225Parameters: struct kvm_ppc_mmuv3_cfg (in)
3226Returns: 0 on success,
3227 -EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read,
3228 -EINVAL if the configuration is invalid
3229
3230This ioctl controls whether the guest will use radix or HPT (hashed
3231page table) translation, and sets the pointer to the process table for
3232the guest.
3233
3234struct kvm_ppc_mmuv3_cfg {
3235 __u64 flags;
3236 __u64 process_table;
3237};
3238
3239There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and
3240KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest
3241to use radix tree translation, and if clear, to use HPT translation.
3242KVM_PPC_MMUV3_GTSE, if set and if KVM permits it, configures the guest
3243to be able to use the global TLB and SLB invalidation instructions;
3244if clear, the guest may not use these instructions.
3245
3246The process_table field specifies the address and size of the guest
3247process table, which is in the guest's space. This field is formatted
3248as the second doubleword of the partition table entry, as defined in
3249the Power ISA V3.00, Book III section 5.7.6.1.
3250
ccc4df4e 32514.101 KVM_PPC_GET_RMMU_INFO
c9270132
PM
3252
3253Capability: KVM_CAP_PPC_RADIX_MMU
3254Architectures: ppc
3255Type: vm ioctl
3256Parameters: struct kvm_ppc_rmmu_info (out)
3257Returns: 0 on success,
3258 -EFAULT if struct kvm_ppc_rmmu_info cannot be written,
3259 -EINVAL if no useful information can be returned
3260
3261This ioctl returns a structure containing two things: (a) a list
3262containing supported radix tree geometries, and (b) a list that maps
3263page sizes to put in the "AP" (actual page size) field for the tlbie
3264(TLB invalidate entry) instruction.
3265
3266struct kvm_ppc_rmmu_info {
3267 struct kvm_ppc_radix_geom {
3268 __u8 page_shift;
3269 __u8 level_bits[4];
3270 __u8 pad[3];
3271 } geometries[8];
3272 __u32 ap_encodings[8];
3273};
3274
3275The geometries[] field gives up to 8 supported geometries for the
3276radix page table, in terms of the log base 2 of the smallest page
3277size, and the number of bits indexed at each level of the tree, from
3278the PTE level up to the PGD level in that order. Any unused entries
3279will have 0 in the page_shift field.
3280
3281The ap_encodings gives the supported page sizes and their AP field
3282encodings, encoded with the AP value in the top 3 bits and the log
3283base 2 of the page size in the bottom 6 bits.
3284
ef1ead0c
DG
32854.102 KVM_PPC_RESIZE_HPT_PREPARE
3286
3287Capability: KVM_CAP_SPAPR_RESIZE_HPT
3288Architectures: powerpc
3289Type: vm ioctl
3290Parameters: struct kvm_ppc_resize_hpt (in)
3291Returns: 0 on successful completion,
3292 >0 if a new HPT is being prepared, the value is an estimated
3293 number of milliseconds until preparation is complete
3294 -EFAULT if struct kvm_reinject_control cannot be read,
3295 -EINVAL if the supplied shift or flags are invalid
3296 -ENOMEM if unable to allocate the new HPT
3297 -ENOSPC if there was a hash collision when moving existing
3298 HPT entries to the new HPT
3299 -EIO on other error conditions
3300
3301Used to implement the PAPR extension for runtime resizing of a guest's
3302Hashed Page Table (HPT). Specifically this starts, stops or monitors
3303the preparation of a new potential HPT for the guest, essentially
3304implementing the H_RESIZE_HPT_PREPARE hypercall.
3305
3306If called with shift > 0 when there is no pending HPT for the guest,
3307this begins preparation of a new pending HPT of size 2^(shift) bytes.
3308It then returns a positive integer with the estimated number of
3309milliseconds until preparation is complete.
3310
3311If called when there is a pending HPT whose size does not match that
3312requested in the parameters, discards the existing pending HPT and
3313creates a new one as above.
3314
3315If called when there is a pending HPT of the size requested, will:
3316 * If preparation of the pending HPT is already complete, return 0
3317 * If preparation of the pending HPT has failed, return an error
3318 code, then discard the pending HPT.
3319 * If preparation of the pending HPT is still in progress, return an
3320 estimated number of milliseconds until preparation is complete.
3321
3322If called with shift == 0, discards any currently pending HPT and
3323returns 0 (i.e. cancels any in-progress preparation).
3324
3325flags is reserved for future expansion, currently setting any bits in
3326flags will result in an -EINVAL.
3327
3328Normally this will be called repeatedly with the same parameters until
3329it returns <= 0. The first call will initiate preparation, subsequent
3330ones will monitor preparation until it completes or fails.
3331
3332struct kvm_ppc_resize_hpt {
3333 __u64 flags;
3334 __u32 shift;
3335 __u32 pad;
3336};
3337
33384.103 KVM_PPC_RESIZE_HPT_COMMIT
3339
3340Capability: KVM_CAP_SPAPR_RESIZE_HPT
3341Architectures: powerpc
3342Type: vm ioctl
3343Parameters: struct kvm_ppc_resize_hpt (in)
3344Returns: 0 on successful completion,
3345 -EFAULT if struct kvm_reinject_control cannot be read,
3346 -EINVAL if the supplied shift or flags are invalid
3347 -ENXIO is there is no pending HPT, or the pending HPT doesn't
3348 have the requested size
3349 -EBUSY if the pending HPT is not fully prepared
3350 -ENOSPC if there was a hash collision when moving existing
3351 HPT entries to the new HPT
3352 -EIO on other error conditions
3353
3354Used to implement the PAPR extension for runtime resizing of a guest's
3355Hashed Page Table (HPT). Specifically this requests that the guest be
3356transferred to working with the new HPT, essentially implementing the
3357H_RESIZE_HPT_COMMIT hypercall.
3358
3359This should only be called after KVM_PPC_RESIZE_HPT_PREPARE has
3360returned 0 with the same parameters. In other cases
3361KVM_PPC_RESIZE_HPT_COMMIT will return an error (usually -ENXIO or
3362-EBUSY, though others may be possible if the preparation was started,
3363but failed).
3364
3365This will have undefined effects on the guest if it has not already
3366placed itself in a quiescent state where no vcpu will make MMU enabled
3367memory accesses.
3368
3369On succsful completion, the pending HPT will become the guest's active
3370HPT and the previous HPT will be discarded.
3371
3372On failure, the guest will still be operating on its previous HPT.
3373
3374struct kvm_ppc_resize_hpt {
3375 __u64 flags;
3376 __u32 shift;
3377 __u32 pad;
3378};
3379
9c1b96e3 33805. The kvm_run structure
414fa985 3381------------------------
9c1b96e3
AK
3382
3383Application code obtains a pointer to the kvm_run structure by
3384mmap()ing a vcpu fd. From that point, application code can control
3385execution by changing fields in kvm_run prior to calling the KVM_RUN
3386ioctl, and obtain information about the reason KVM_RUN returned by
3387looking up structure members.
3388
3389struct kvm_run {
3390 /* in */
3391 __u8 request_interrupt_window;
3392
3393Request that KVM_RUN return when it becomes possible to inject external
3394interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
3395
460df4c1
PB
3396 __u8 immediate_exit;
3397
3398This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN
3399exits immediately, returning -EINTR. In the common scenario where a
3400signal is used to "kick" a VCPU out of KVM_RUN, this field can be used
3401to avoid usage of KVM_SET_SIGNAL_MASK, which has worse scalability.
3402Rather than blocking the signal outside KVM_RUN, userspace can set up
3403a signal handler that sets run->immediate_exit to a non-zero value.
3404
3405This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available.
3406
3407 __u8 padding1[6];
9c1b96e3
AK
3408
3409 /* out */
3410 __u32 exit_reason;
3411
3412When KVM_RUN has returned successfully (return value 0), this informs
3413application code why KVM_RUN has returned. Allowable values for this
3414field are detailed below.
3415
3416 __u8 ready_for_interrupt_injection;
3417
3418If request_interrupt_window has been specified, this field indicates
3419an interrupt can be injected now with KVM_INTERRUPT.
3420
3421 __u8 if_flag;
3422
3423The value of the current interrupt flag. Only valid if in-kernel
3424local APIC is not used.
3425
f077825a
PB
3426 __u16 flags;
3427
3428More architecture-specific flags detailing state of the VCPU that may
3429affect the device's behavior. The only currently defined flag is
3430KVM_RUN_X86_SMM, which is valid on x86 machines and is set if the
3431VCPU is in system management mode.
9c1b96e3
AK
3432
3433 /* in (pre_kvm_run), out (post_kvm_run) */
3434 __u64 cr8;
3435
3436The value of the cr8 register. Only valid if in-kernel local APIC is
3437not used. Both input and output.
3438
3439 __u64 apic_base;
3440
3441The value of the APIC BASE msr. Only valid if in-kernel local
3442APIC is not used. Both input and output.
3443
3444 union {
3445 /* KVM_EXIT_UNKNOWN */
3446 struct {
3447 __u64 hardware_exit_reason;
3448 } hw;
3449
3450If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
3451reasons. Further architecture-specific information is available in
3452hardware_exit_reason.
3453
3454 /* KVM_EXIT_FAIL_ENTRY */
3455 struct {
3456 __u64 hardware_entry_failure_reason;
3457 } fail_entry;
3458
3459If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
3460to unknown reasons. Further architecture-specific information is
3461available in hardware_entry_failure_reason.
3462
3463 /* KVM_EXIT_EXCEPTION */
3464 struct {
3465 __u32 exception;
3466 __u32 error_code;
3467 } ex;
3468
3469Unused.
3470
3471 /* KVM_EXIT_IO */
3472 struct {
3473#define KVM_EXIT_IO_IN 0
3474#define KVM_EXIT_IO_OUT 1
3475 __u8 direction;
3476 __u8 size; /* bytes */
3477 __u16 port;
3478 __u32 count;
3479 __u64 data_offset; /* relative to kvm_run start */
3480 } io;
3481
2044892d 3482If exit_reason is KVM_EXIT_IO, then the vcpu has
9c1b96e3
AK
3483executed a port I/O instruction which could not be satisfied by kvm.
3484data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
3485where kvm expects application code to place the data for the next
2044892d 3486KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
9c1b96e3 3487
8ab30c15 3488 /* KVM_EXIT_DEBUG */
9c1b96e3
AK
3489 struct {
3490 struct kvm_debug_exit_arch arch;
3491 } debug;
3492
8ab30c15
AB
3493If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event
3494for which architecture specific information is returned.
9c1b96e3
AK
3495
3496 /* KVM_EXIT_MMIO */
3497 struct {
3498 __u64 phys_addr;
3499 __u8 data[8];
3500 __u32 len;
3501 __u8 is_write;
3502 } mmio;
3503
2044892d 3504If exit_reason is KVM_EXIT_MMIO, then the vcpu has
9c1b96e3
AK
3505executed a memory-mapped I/O instruction which could not be satisfied
3506by kvm. The 'data' member contains the written data if 'is_write' is
3507true, and should be filled by application code otherwise.
3508
6acdb160
CD
3509The 'data' member contains, in its first 'len' bytes, the value as it would
3510appear if the VCPU performed a load or store of the appropriate width directly
3511to the byte array.
3512
cc568ead 3513NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and
ce91ddc4 3514 KVM_EXIT_EPR the corresponding
ad0a048b
AG
3515operations are complete (and guest state is consistent) only after userspace
3516has re-entered the kernel with KVM_RUN. The kernel side will first finish
67961344
MT
3517incomplete operations and then check for pending signals. Userspace
3518can re-enter the guest with an unmasked signal pending to complete
3519pending operations.
3520
9c1b96e3
AK
3521 /* KVM_EXIT_HYPERCALL */
3522 struct {
3523 __u64 nr;
3524 __u64 args[6];
3525 __u64 ret;
3526 __u32 longmode;
3527 __u32 pad;
3528 } hypercall;
3529
647dc49e
AK
3530Unused. This was once used for 'hypercall to userspace'. To implement
3531such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
3532Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
9c1b96e3
AK
3533
3534 /* KVM_EXIT_TPR_ACCESS */
3535 struct {
3536 __u64 rip;
3537 __u32 is_write;
3538 __u32 pad;
3539 } tpr_access;
3540
3541To be documented (KVM_TPR_ACCESS_REPORTING).
3542
3543 /* KVM_EXIT_S390_SIEIC */
3544 struct {
3545 __u8 icptcode;
3546 __u64 mask; /* psw upper half */
3547 __u64 addr; /* psw lower half */
3548 __u16 ipa;
3549 __u32 ipb;
3550 } s390_sieic;
3551
3552s390 specific.
3553
3554 /* KVM_EXIT_S390_RESET */
3555#define KVM_S390_RESET_POR 1
3556#define KVM_S390_RESET_CLEAR 2
3557#define KVM_S390_RESET_SUBSYSTEM 4
3558#define KVM_S390_RESET_CPU_INIT 8
3559#define KVM_S390_RESET_IPL 16
3560 __u64 s390_reset_flags;
3561
3562s390 specific.
3563
e168bf8d
CO
3564 /* KVM_EXIT_S390_UCONTROL */
3565 struct {
3566 __u64 trans_exc_code;
3567 __u32 pgm_code;
3568 } s390_ucontrol;
3569
3570s390 specific. A page fault has occurred for a user controlled virtual
3571machine (KVM_VM_S390_UNCONTROL) on it's host page table that cannot be
3572resolved by the kernel.
3573The program code and the translation exception code that were placed
3574in the cpu's lowcore are presented here as defined by the z Architecture
3575Principles of Operation Book in the Chapter for Dynamic Address Translation
3576(DAT)
3577
9c1b96e3
AK
3578 /* KVM_EXIT_DCR */
3579 struct {
3580 __u32 dcrn;
3581 __u32 data;
3582 __u8 is_write;
3583 } dcr;
3584
ce91ddc4 3585Deprecated - was used for 440 KVM.
9c1b96e3 3586
ad0a048b
AG
3587 /* KVM_EXIT_OSI */
3588 struct {
3589 __u64 gprs[32];
3590 } osi;
3591
3592MOL uses a special hypercall interface it calls 'OSI'. To enable it, we catch
3593hypercalls and exit with this exit struct that contains all the guest gprs.
3594
3595If exit_reason is KVM_EXIT_OSI, then the vcpu has triggered such a hypercall.
3596Userspace can now handle the hypercall and when it's done modify the gprs as
3597necessary. Upon guest entry all guest GPRs will then be replaced by the values
3598in this struct.
3599
de56a948
PM
3600 /* KVM_EXIT_PAPR_HCALL */
3601 struct {
3602 __u64 nr;
3603 __u64 ret;
3604 __u64 args[9];
3605 } papr_hcall;
3606
3607This is used on 64-bit PowerPC when emulating a pSeries partition,
3608e.g. with the 'pseries' machine type in qemu. It occurs when the
3609guest does a hypercall using the 'sc 1' instruction. The 'nr' field
3610contains the hypercall number (from the guest R3), and 'args' contains
3611the arguments (from the guest R4 - R12). Userspace should put the
3612return code in 'ret' and any extra returned values in args[].
3613The possible hypercalls are defined in the Power Architecture Platform
3614Requirements (PAPR) document available from www.power.org (free
3615developer registration required to access it).
3616
fa6b7fe9
CH
3617 /* KVM_EXIT_S390_TSCH */
3618 struct {
3619 __u16 subchannel_id;
3620 __u16 subchannel_nr;
3621 __u32 io_int_parm;
3622 __u32 io_int_word;
3623 __u32 ipb;
3624 __u8 dequeued;
3625 } s390_tsch;
3626
3627s390 specific. This exit occurs when KVM_CAP_S390_CSS_SUPPORT has been enabled
3628and TEST SUBCHANNEL was intercepted. If dequeued is set, a pending I/O
3629interrupt for the target subchannel has been dequeued and subchannel_id,
3630subchannel_nr, io_int_parm and io_int_word contain the parameters for that
3631interrupt. ipb is needed for instruction parameter decoding.
3632
1c810636
AG
3633 /* KVM_EXIT_EPR */
3634 struct {
3635 __u32 epr;
3636 } epr;
3637
3638On FSL BookE PowerPC chips, the interrupt controller has a fast patch
3639interrupt acknowledge path to the core. When the core successfully
3640delivers an interrupt, it automatically populates the EPR register with
3641the interrupt vector number and acknowledges the interrupt inside
3642the interrupt controller.
3643
3644In case the interrupt controller lives in user space, we need to do
3645the interrupt acknowledge cycle through it to fetch the next to be
3646delivered interrupt vector using this exit.
3647
3648It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an
3649external interrupt has just been delivered into the guest. User space
3650should put the acknowledged interrupt vector into the 'epr' field.
3651
8ad6b634
AP
3652 /* KVM_EXIT_SYSTEM_EVENT */
3653 struct {
3654#define KVM_SYSTEM_EVENT_SHUTDOWN 1
3655#define KVM_SYSTEM_EVENT_RESET 2
2ce79189 3656#define KVM_SYSTEM_EVENT_CRASH 3
8ad6b634
AP
3657 __u32 type;
3658 __u64 flags;
3659 } system_event;
3660
3661If exit_reason is KVM_EXIT_SYSTEM_EVENT then the vcpu has triggered
3662a system-level event using some architecture specific mechanism (hypercall
3663or some special instruction). In case of ARM/ARM64, this is triggered using
3664HVC instruction based PSCI call from the vcpu. The 'type' field describes
3665the system-level event type. The 'flags' field describes architecture
3666specific flags for the system-level event.
3667
cf5d3188
CD
3668Valid values for 'type' are:
3669 KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the
3670 VM. Userspace is not obliged to honour this, and if it does honour
3671 this does not need to destroy the VM synchronously (ie it may call
3672 KVM_RUN again before shutdown finally occurs).
3673 KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM.
3674 As with SHUTDOWN, userspace can choose to ignore the request, or
3675 to schedule the reset to occur in the future and may call KVM_RUN again.
2ce79189
AS
3676 KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest
3677 has requested a crash condition maintenance. Userspace can choose
3678 to ignore the request, or to gather VM memory core dump and/or
3679 reset/shutdown of the VM.
cf5d3188 3680
7543a635
SR
3681 /* KVM_EXIT_IOAPIC_EOI */
3682 struct {
3683 __u8 vector;
3684 } eoi;
3685
3686Indicates that the VCPU's in-kernel local APIC received an EOI for a
3687level-triggered IOAPIC interrupt. This exit only triggers when the
3688IOAPIC is implemented in userspace (i.e. KVM_CAP_SPLIT_IRQCHIP is enabled);
3689the userspace IOAPIC should process the EOI and retrigger the interrupt if
3690it is still asserted. Vector is the LAPIC interrupt vector for which the
3691EOI was received.
3692
db397571
AS
3693 struct kvm_hyperv_exit {
3694#define KVM_EXIT_HYPERV_SYNIC 1
83326e43 3695#define KVM_EXIT_HYPERV_HCALL 2
db397571
AS
3696 __u32 type;
3697 union {
3698 struct {
3699 __u32 msr;
3700 __u64 control;
3701 __u64 evt_page;
3702 __u64 msg_page;
3703 } synic;
83326e43
AS
3704 struct {
3705 __u64 input;
3706 __u64 result;
3707 __u64 params[2];
3708 } hcall;
db397571
AS
3709 } u;
3710 };
3711 /* KVM_EXIT_HYPERV */
3712 struct kvm_hyperv_exit hyperv;
3713Indicates that the VCPU exits into userspace to process some tasks
3714related to Hyper-V emulation.
3715Valid values for 'type' are:
3716 KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about
3717Hyper-V SynIC state change. Notification is used to remap SynIC
3718event/message pages and to enable/disable SynIC messages/events processing
3719in userspace.
3720
9c1b96e3
AK
3721 /* Fix the size of the union. */
3722 char padding[256];
3723 };
b9e5dc8d
CB
3724
3725 /*
3726 * shared registers between kvm and userspace.
3727 * kvm_valid_regs specifies the register classes set by the host
3728 * kvm_dirty_regs specified the register classes dirtied by userspace
3729 * struct kvm_sync_regs is architecture specific, as well as the
3730 * bits for kvm_valid_regs and kvm_dirty_regs
3731 */
3732 __u64 kvm_valid_regs;
3733 __u64 kvm_dirty_regs;
3734 union {
3735 struct kvm_sync_regs regs;
3736 char padding[1024];
3737 } s;
3738
3739If KVM_CAP_SYNC_REGS is defined, these fields allow userspace to access
3740certain guest registers without having to call SET/GET_*REGS. Thus we can
3741avoid some system call overhead if userspace has to handle the exit.
3742Userspace can query the validity of the structure by checking
3743kvm_valid_regs for specific bits. These bits are architecture specific
3744and usually define the validity of a groups of registers. (e.g. one bit
3745 for general purpose registers)
3746
d8482c0d
DH
3747Please note that the kernel is allowed to use the kvm_run structure as the
3748primary storage for certain register types. Therefore, the kernel may use the
3749values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set.
3750
9c1b96e3 3751};
821246a5 3752
414fa985 3753
9c15bb1d 3754
699a0ea0
PM
37556. Capabilities that can be enabled on vCPUs
3756--------------------------------------------
821246a5 3757
0907c855
CH
3758There are certain capabilities that change the behavior of the virtual CPU or
3759the virtual machine when enabled. To enable them, please see section 4.37.
3760Below you can find a list of capabilities and what their effect on the vCPU or
3761the virtual machine is when enabling them.
821246a5
AG
3762
3763The following information is provided along with the description:
3764
3765 Architectures: which instruction set architectures provide this ioctl.
3766 x86 includes both i386 and x86_64.
3767
0907c855
CH
3768 Target: whether this is a per-vcpu or per-vm capability.
3769
821246a5
AG
3770 Parameters: what parameters are accepted by the capability.
3771
3772 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
3773 are not detailed, but errors with specific meanings are.
3774
414fa985 3775
821246a5
AG
37766.1 KVM_CAP_PPC_OSI
3777
3778Architectures: ppc
0907c855 3779Target: vcpu
821246a5
AG
3780Parameters: none
3781Returns: 0 on success; -1 on error
3782
3783This capability enables interception of OSI hypercalls that otherwise would
3784be treated as normal system calls to be injected into the guest. OSI hypercalls
3785were invented by Mac-on-Linux to have a standardized communication mechanism
3786between the guest and the host.
3787
3788When this capability is enabled, KVM_EXIT_OSI can occur.
3789
414fa985 3790
821246a5
AG
37916.2 KVM_CAP_PPC_PAPR
3792
3793Architectures: ppc
0907c855 3794Target: vcpu
821246a5
AG
3795Parameters: none
3796Returns: 0 on success; -1 on error
3797
3798This capability enables interception of PAPR hypercalls. PAPR hypercalls are
3799done using the hypercall instruction "sc 1".
3800
3801It also sets the guest privilege level to "supervisor" mode. Usually the guest
3802runs in "hypervisor" privilege mode with a few missing features.
3803
3804In addition to the above, it changes the semantics of SDR1. In this mode, the
3805HTAB address part of SDR1 contains an HVA instead of a GPA, as PAPR keeps the
3806HTAB invisible to the guest.
3807
3808When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
dc83b8bc 3809
414fa985 3810
dc83b8bc
SW
38116.3 KVM_CAP_SW_TLB
3812
3813Architectures: ppc
0907c855 3814Target: vcpu
dc83b8bc
SW
3815Parameters: args[0] is the address of a struct kvm_config_tlb
3816Returns: 0 on success; -1 on error
3817
3818struct kvm_config_tlb {
3819 __u64 params;
3820 __u64 array;
3821 __u32 mmu_type;
3822 __u32 array_len;
3823};
3824
3825Configures the virtual CPU's TLB array, establishing a shared memory area
3826between userspace and KVM. The "params" and "array" fields are userspace
3827addresses of mmu-type-specific data structures. The "array_len" field is an
3828safety mechanism, and should be set to the size in bytes of the memory that
3829userspace has reserved for the array. It must be at least the size dictated
3830by "mmu_type" and "params".
3831
3832While KVM_RUN is active, the shared region is under control of KVM. Its
3833contents are undefined, and any modification by userspace results in
3834boundedly undefined behavior.
3835
3836On return from KVM_RUN, the shared region will reflect the current state of
3837the guest's TLB. If userspace makes any changes, it must call KVM_DIRTY_TLB
3838to tell KVM which entries have been changed, prior to calling KVM_RUN again
3839on this vcpu.
3840
3841For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
3842 - The "params" field is of type "struct kvm_book3e_206_tlb_params".
3843 - The "array" field points to an array of type "struct
3844 kvm_book3e_206_tlb_entry".
3845 - The array consists of all entries in the first TLB, followed by all
3846 entries in the second TLB.
3847 - Within a TLB, entries are ordered first by increasing set number. Within a
3848 set, entries are ordered by way (increasing ESEL).
3849 - The hash for determining set number in TLB0 is: (MAS2 >> 12) & (num_sets - 1)
3850 where "num_sets" is the tlb_sizes[] value divided by the tlb_ways[] value.
3851 - The tsize field of mas1 shall be set to 4K on TLB0, even though the
3852 hardware ignores this value for TLB0.
fa6b7fe9
CH
3853
38546.4 KVM_CAP_S390_CSS_SUPPORT
3855
3856Architectures: s390
0907c855 3857Target: vcpu
fa6b7fe9
CH
3858Parameters: none
3859Returns: 0 on success; -1 on error
3860
3861This capability enables support for handling of channel I/O instructions.
3862
3863TEST PENDING INTERRUPTION and the interrupt portion of TEST SUBCHANNEL are
3864handled in-kernel, while the other I/O instructions are passed to userspace.
3865
3866When this capability is enabled, KVM_EXIT_S390_TSCH will occur on TEST
3867SUBCHANNEL intercepts.
1c810636 3868
0907c855
CH
3869Note that even though this capability is enabled per-vcpu, the complete
3870virtual machine is affected.
3871
1c810636
AG
38726.5 KVM_CAP_PPC_EPR
3873
3874Architectures: ppc
0907c855 3875Target: vcpu
1c810636
AG
3876Parameters: args[0] defines whether the proxy facility is active
3877Returns: 0 on success; -1 on error
3878
3879This capability enables or disables the delivery of interrupts through the
3880external proxy facility.
3881
3882When enabled (args[0] != 0), every time the guest gets an external interrupt
3883delivered, it automatically exits into user space with a KVM_EXIT_EPR exit
3884to receive the topmost interrupt vector.
3885
3886When disabled (args[0] == 0), behavior is as if this facility is unsupported.
3887
3888When this capability is enabled, KVM_EXIT_EPR can occur.
eb1e4f43
SW
3889
38906.6 KVM_CAP_IRQ_MPIC
3891
3892Architectures: ppc
3893Parameters: args[0] is the MPIC device fd
3894 args[1] is the MPIC CPU number for this vcpu
3895
3896This capability connects the vcpu to an in-kernel MPIC device.
5975a2e0
PM
3897
38986.7 KVM_CAP_IRQ_XICS
3899
3900Architectures: ppc
0907c855 3901Target: vcpu
5975a2e0
PM
3902Parameters: args[0] is the XICS device fd
3903 args[1] is the XICS CPU number (server ID) for this vcpu
3904
3905This capability connects the vcpu to an in-kernel XICS device.
8a366a4b
CH
3906
39076.8 KVM_CAP_S390_IRQCHIP
3908
3909Architectures: s390
3910Target: vm
3911Parameters: none
3912
3913This capability enables the in-kernel irqchip for s390. Please refer to
3914"4.24 KVM_CREATE_IRQCHIP" for details.
699a0ea0 3915
5fafd874
JH
39166.9 KVM_CAP_MIPS_FPU
3917
3918Architectures: mips
3919Target: vcpu
3920Parameters: args[0] is reserved for future use (should be 0).
3921
3922This capability allows the use of the host Floating Point Unit by the guest. It
3923allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is
3924done the KVM_REG_MIPS_FPR_* and KVM_REG_MIPS_FCR_* registers can be accessed
3925(depending on the current guest FPU register mode), and the Status.FR,
3926Config5.FRE bits are accessible via the KVM API and also from the guest,
3927depending on them being supported by the FPU.
3928
d952bd07
JH
39296.10 KVM_CAP_MIPS_MSA
3930
3931Architectures: mips
3932Target: vcpu
3933Parameters: args[0] is reserved for future use (should be 0).
3934
3935This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest.
3936It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest.
3937Once this is done the KVM_REG_MIPS_VEC_* and KVM_REG_MIPS_MSA_* registers can be
3938accessed, and the Config5.MSAEn bit is accessible via the KVM API and also from
3939the guest.
3940
699a0ea0
PM
39417. Capabilities that can be enabled on VMs
3942------------------------------------------
3943
3944There are certain capabilities that change the behavior of the virtual
3945machine when enabled. To enable them, please see section 4.37. Below
3946you can find a list of capabilities and what their effect on the VM
3947is when enabling them.
3948
3949The following information is provided along with the description:
3950
3951 Architectures: which instruction set architectures provide this ioctl.
3952 x86 includes both i386 and x86_64.
3953
3954 Parameters: what parameters are accepted by the capability.
3955
3956 Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
3957 are not detailed, but errors with specific meanings are.
3958
3959
39607.1 KVM_CAP_PPC_ENABLE_HCALL
3961
3962Architectures: ppc
3963Parameters: args[0] is the sPAPR hcall number
3964 args[1] is 0 to disable, 1 to enable in-kernel handling
3965
3966This capability controls whether individual sPAPR hypercalls (hcalls)
3967get handled by the kernel or not. Enabling or disabling in-kernel
3968handling of an hcall is effective across the VM. On creation, an
3969initial set of hcalls are enabled for in-kernel handling, which
3970consists of those hcalls for which in-kernel handlers were implemented
3971before this capability was implemented. If disabled, the kernel will
3972not to attempt to handle the hcall, but will always exit to userspace
3973to handle it. Note that it may not make sense to enable some and
3974disable others of a group of related hcalls, but KVM does not prevent
3975userspace from doing that.
ae2113a4
PM
3976
3977If the hcall number specified is not one that has an in-kernel
3978implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL
3979error.
2444b352
DH
3980
39817.2 KVM_CAP_S390_USER_SIGP
3982
3983Architectures: s390
3984Parameters: none
3985
3986This capability controls which SIGP orders will be handled completely in user
3987space. With this capability enabled, all fast orders will be handled completely
3988in the kernel:
3989- SENSE
3990- SENSE RUNNING
3991- EXTERNAL CALL
3992- EMERGENCY SIGNAL
3993- CONDITIONAL EMERGENCY SIGNAL
3994
3995All other orders will be handled completely in user space.
3996
3997Only privileged operation exceptions will be checked for in the kernel (or even
3998in the hardware prior to interception). If this capability is not enabled, the
3999old way of handling SIGP orders is used (partially in kernel and user space).
68c55750
EF
4000
40017.3 KVM_CAP_S390_VECTOR_REGISTERS
4002
4003Architectures: s390
4004Parameters: none
4005Returns: 0 on success, negative value on error
4006
4007Allows use of the vector registers introduced with z13 processor, and
4008provides for the synchronization between host and user space. Will
4009return -EINVAL if the machine does not support vectors.
e44fc8c9
ET
4010
40117.4 KVM_CAP_S390_USER_STSI
4012
4013Architectures: s390
4014Parameters: none
4015
4016This capability allows post-handlers for the STSI instruction. After
4017initial handling in the kernel, KVM exits to user space with
4018KVM_EXIT_S390_STSI to allow user space to insert further data.
4019
4020Before exiting to userspace, kvm handlers should fill in s390_stsi field of
4021vcpu->run:
4022struct {
4023 __u64 addr;
4024 __u8 ar;
4025 __u8 reserved;
4026 __u8 fc;
4027 __u8 sel1;
4028 __u16 sel2;
4029} s390_stsi;
4030
4031@addr - guest address of STSI SYSIB
4032@fc - function code
4033@sel1 - selector 1
4034@sel2 - selector 2
4035@ar - access register number
4036
4037KVM handlers should exit to userspace with rc = -EREMOTE.
e928e9cb 4038
49df6397
SR
40397.5 KVM_CAP_SPLIT_IRQCHIP
4040
4041Architectures: x86
b053b2ae 4042Parameters: args[0] - number of routes reserved for userspace IOAPICs
49df6397
SR
4043Returns: 0 on success, -1 on error
4044
4045Create a local apic for each processor in the kernel. This can be used
4046instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the
4047IOAPIC and PIC (and also the PIT, even though this has to be enabled
4048separately).
4049
b053b2ae
SR
4050This capability also enables in kernel routing of interrupt requests;
4051when KVM_CAP_SPLIT_IRQCHIP only routes of KVM_IRQ_ROUTING_MSI type are
4052used in the IRQ routing table. The first args[0] MSI routes are reserved
4053for the IOAPIC pins. Whenever the LAPIC receives an EOI for these routes,
4054a KVM_EXIT_IOAPIC_EOI vmexit will be reported to userspace.
49df6397
SR
4055
4056Fails if VCPU has already been created, or if the irqchip is already in the
4057kernel (i.e. KVM_CREATE_IRQCHIP has already been called).
4058
051c87f7
DH
40597.6 KVM_CAP_S390_RI
4060
4061Architectures: s390
4062Parameters: none
4063
4064Allows use of runtime-instrumentation introduced with zEC12 processor.
4065Will return -EINVAL if the machine does not support runtime-instrumentation.
4066Will return -EBUSY if a VCPU has already been created.
e928e9cb 4067
37131313
RK
40687.7 KVM_CAP_X2APIC_API
4069
4070Architectures: x86
4071Parameters: args[0] - features that should be enabled
4072Returns: 0 on success, -EINVAL when args[0] contains invalid features
4073
4074Valid feature flags in args[0] are
4075
4076#define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0)
c519265f 4077#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1)
37131313
RK
4078
4079Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior of
4080KVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC,
4081allowing the use of 32-bit APIC IDs. See KVM_CAP_X2APIC_API in their
4082respective sections.
4083
c519265f
RK
4084KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK must be enabled for x2APIC to work
4085in logical mode or with more than 255 VCPUs. Otherwise, KVM treats 0xff
4086as a broadcast even in x2APIC mode in order to support physical x2APIC
4087without interrupt remapping. This is undesirable in logical mode,
4088where 0xff represents CPUs 0-7 in cluster 0.
37131313 4089
6502a34c
DH
40907.8 KVM_CAP_S390_USER_INSTR0
4091
4092Architectures: s390
4093Parameters: none
4094
4095With this capability enabled, all illegal instructions 0x0000 (2 bytes) will
4096be intercepted and forwarded to user space. User space can use this
4097mechanism e.g. to realize 2-byte software breakpoints. The kernel will
4098not inject an operating exception for these instructions, user space has
4099to take care of that.
4100
4101This capability can be enabled dynamically even if VCPUs were already
4102created and are running.
37131313 4103
e928e9cb
ME
41048. Other capabilities.
4105----------------------
4106
4107This section lists capabilities that give information about other
4108features of the KVM implementation.
4109
41108.1 KVM_CAP_PPC_HWRNG
4111
4112Architectures: ppc
4113
4114This capability, if KVM_CHECK_EXTENSION indicates that it is
4115available, means that that the kernel has an implementation of the
4116H_RANDOM hypercall backed by a hardware random-number generator.
4117If present, the kernel H_RANDOM handler can be enabled for guest use
4118with the KVM_CAP_PPC_ENABLE_HCALL capability.
5c919412
AS
4119
41208.2 KVM_CAP_HYPERV_SYNIC
4121
4122Architectures: x86
4123This capability, if KVM_CHECK_EXTENSION indicates that it is
4124available, means that that the kernel has an implementation of the
4125Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is
4126used to support Windows Hyper-V based guest paravirt drivers(VMBus).
4127
4128In order to use SynIC, it has to be activated by setting this
4129capability via KVM_ENABLE_CAP ioctl on the vcpu fd. Note that this
4130will disable the use of APIC hardware virtualization even if supported
4131by the CPU, as it's incompatible with SynIC auto-EOI behavior.
c9270132
PM
4132
41338.3 KVM_CAP_PPC_RADIX_MMU
4134
4135Architectures: ppc
4136
4137This capability, if KVM_CHECK_EXTENSION indicates that it is
4138available, means that that the kernel can support guests using the
4139radix MMU defined in Power ISA V3.00 (as implemented in the POWER9
4140processor).
4141
41428.4 KVM_CAP_PPC_HASH_MMU_V3
4143
4144Architectures: ppc
4145
4146This capability, if KVM_CHECK_EXTENSION indicates that it is
4147available, means that that the kernel can support guests using the
4148hashed page table MMU defined in Power ISA V3.00 (as implemented in
4149the POWER9 processor), including in-memory segment tables.