About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / virtual / kvm / api.txt




Custom Search

Based on kernel version 4.9. Page generated on 2016-12-21 14:37 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.